mirror of
https://github.com/acedanger/finance.git
synced 2025-12-05 22:50:12 -08:00
135 lines
4.4 KiB
Markdown
135 lines
4.4 KiB
Markdown
# Financial Transaction Manager
|
|
|
|
A web application for managing financial transactions across multiple bank accounts.
|
|
|
|
## Project Overview
|
|
|
|
* **Purpose:** Provides a user interface for CRUD operations on financial transactions.
|
|
* **Technology:** Built with Astro, TypeScript, and plain CSS, utilizing Astro API routes.
|
|
* **Layout:** Features a two-column dashboard design with a sidebar for account selection/actions and a main area for transaction display.
|
|
* **Data Management:** Uses Prisma ORM for database operations (`src/data/db.service.ts`), accessed via API endpoints (`src/pages/api/`).
|
|
* **Key Features (Implemented & Planned):** Account switching, transaction listing, adding, editing, and deleting transactions.
|
|
|
|
## Logs
|
|
This app is currently deployed using Cloudflare Pages. The logs can be viewed with the `npx wrangler pages deployment tail --project-name finance` command.
|
|
|
|
## Development Environment Setup
|
|
|
|
For detailed setup instructions, including environment configuration and troubleshooting, see [ENVIRONMENT_SETUP.md](ENVIRONMENT_SETUP.md).
|
|
|
|
### Quick Start
|
|
|
|
1. **Prerequisites**
|
|
- Node.js (version 18 or higher)
|
|
- PostgreSQL (local installation or Docker)
|
|
- Git
|
|
|
|
2. **Setup Steps**
|
|
- Clone this repository
|
|
- Run `npm install`
|
|
- Copy `.env.example` to `.env` and configure your database connection
|
|
- Run `npx prisma migrate dev` to set up the database
|
|
|
|
### Database Setup
|
|
|
|
The project uses Prisma ORM for database operations. To set up the database:
|
|
|
|
1. Create a `.env` file in the project root with your database connection string:
|
|
```
|
|
DATABASE_URL="postgresql://username:password@localhost:5432/finance"
|
|
```
|
|
|
|
2. Run database migrations:
|
|
```bash
|
|
npx prisma migrate dev
|
|
```
|
|
|
|
3. Seed the database with initial data (optional):
|
|
```bash
|
|
npx prisma db seed
|
|
```
|
|
|
|
4. To view and manage your data visually:
|
|
```bash
|
|
npx prisma studio
|
|
```
|
|
|
|
## Path Aliases
|
|
|
|
This project uses TypeScript path aliases for cleaner imports. Instead of using relative paths like `../../../../data/db.service`, use the following aliases:
|
|
|
|
- `@/*` - Maps to `src/*`
|
|
- `@components/*` - Maps to `src/components/*`
|
|
- `@layouts/*` - Maps to `src/layouts/*`
|
|
- `@data/*` - Maps to `src/data/*`
|
|
- `@pages/*` - Maps to `src/pages/*`
|
|
- `@styles/*` - Maps to `src/styles/*`
|
|
- `@stores/*` - Maps to `src/stores/*`
|
|
- `@utils/*` - Maps to `src/utils.ts`
|
|
- `@types` - Maps to `src/types.ts`
|
|
|
|
Example:
|
|
```typescript
|
|
// ✅ DO use path aliases like this
|
|
import { transactionService } from '@data/db.service';
|
|
import type { Transaction } from '@types';
|
|
|
|
// ❌ DON'T use relative imports like this
|
|
import { transactionService } from '../../../../data/db.service';
|
|
```
|
|
|
|
### Enforcing Path Aliases with Biome.js
|
|
|
|
This project uses [Biome.js](https://biomejs.dev/) for code formatting and linting. Biome enforces the use of path aliases instead of relative imports.
|
|
|
|
## Code Quality Tools
|
|
|
|
This project uses Biome.js for maintaining code quality, formatting, and linting. Biome provides fast, reliable tooling for JavaScript and TypeScript projects.
|
|
|
|
### Available Commands
|
|
|
|
#### Quick Commands (via npm scripts):
|
|
```bash
|
|
# Format all files (fixes formatting only)
|
|
npm run format
|
|
|
|
# Lint all files (shows issues without fixing)
|
|
npm run lint
|
|
|
|
# Check and fix all auto-fixable issues (recommended)
|
|
npm run check
|
|
```
|
|
|
|
#### Direct Biome Commands:
|
|
```bash
|
|
# Format with write
|
|
npx biome format --write .
|
|
|
|
# Lint only (no fixes)
|
|
npx biome lint .
|
|
|
|
# Check and apply safe fixes
|
|
npx biome check --write .
|
|
|
|
# Check and apply all fixes (including unsafe ones)
|
|
npx biome check --write --unsafe .
|
|
```
|
|
|
|
### What Biome.js Enforces:
|
|
|
|
- **Path Aliases**: Enforces use of `@components/*`, `@types`, etc. instead of relative imports
|
|
- **Node.js Import Protocols**: Requires `node:path` instead of `path` for Node.js built-ins
|
|
- **Code Formatting**: Consistent indentation, quotes, semicolons, and line width (100 chars)
|
|
- **Import Organization**: Automatic sorting and organization of imports
|
|
- **TypeScript Best Practices**: Warns about `any` types, unused imports, excessive complexity
|
|
|
|
### Pre-commit Hooks
|
|
|
|
This project uses Husky for Git hooks. Biome.js checks run automatically before commits to ensure code quality.
|
|
|
|
### Configuration
|
|
|
|
Biome.js configuration is in `biome.json`. Key settings:
|
|
- **Formatter**: 2-space indentation, single quotes, 100-character line width
|
|
- **Linter**: Recommended rules plus custom rules for path aliases and Node.js protocols
|
|
- **Ignored Files**: `dist/`, `node_modules/`, coverage reports |