121 lines
3.1 KiB
Markdown
121 lines
3.1 KiB
Markdown
# Finance App
|
|
|
|
Personal finance web app for tracking bank transactions, monitoring net worth, and visualizing spending. Self-hosted via Docker Compose — no cloud services required.
|
|
|
|
## Features
|
|
|
|
- Import transactions from CSV exports (Discover Savings, Discover Credit Card, Huntington Checking, Fidelity)
|
|
- Net worth tracking across bank accounts
|
|
- Browse, filter, and annotate transactions
|
|
- Assign transactions to budgets with optional monthly caps
|
|
- Dashboard: net worth snapshot, cash flow, recent transactions, budget summary
|
|
- Charts: net worth trend, monthly cash flow, spending by category, budget performance
|
|
|
|
## Quick start
|
|
|
|
**Prerequisites:** Docker and Docker Compose
|
|
|
|
```sh
|
|
# 1. Copy the example env file
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env`:
|
|
- Set `NEXTAUTH_SECRET` to the output of `openssl rand -base64 32`
|
|
- Set `SEED_EMAIL` and `SEED_PASSWORD` to your desired login credentials
|
|
- Change `POSTGRES_PASSWORD` to a strong password
|
|
|
|
```sh
|
|
# 2. Build and start the stack
|
|
docker compose up --build -d
|
|
|
|
# 3. First-run only: apply the schema and create your user
|
|
docker compose exec app npx prisma db push
|
|
docker compose exec app npx prisma db seed
|
|
|
|
# 4. Open the app
|
|
open http://localhost:3000
|
|
```
|
|
|
|
Sign in with the `SEED_EMAIL` / `SEED_PASSWORD` you set.
|
|
|
|
## Environment variables
|
|
|
|
| Variable | Description |
|
|
|---|---|
|
|
| `NEXTAUTH_SECRET` | Secret for JWT signing — run `openssl rand -base64 32` |
|
|
| `NEXTAUTH_URL` | Public URL of the app (default: `http://localhost:3000`) |
|
|
| `SEED_EMAIL` | Login email created by the seed script |
|
|
| `SEED_PASSWORD` | Login password created by the seed script |
|
|
| `POSTGRES_USER` | PostgreSQL username |
|
|
| `POSTGRES_PASSWORD` | PostgreSQL password |
|
|
| `POSTGRES_DB` | PostgreSQL database name |
|
|
| `DATABASE_URL` | Full connection string — set automatically by Compose |
|
|
|
|
## Useful commands
|
|
|
|
```sh
|
|
# View logs
|
|
docker compose logs -f app
|
|
|
|
# Stop the stack
|
|
docker compose down
|
|
|
|
# Stop and wipe the database volume
|
|
docker compose down -v
|
|
|
|
# Re-seed after a wipe
|
|
docker compose exec app npx prisma db push
|
|
docker compose exec app npx prisma db seed
|
|
|
|
# Check health
|
|
curl http://localhost:3000/api/health
|
|
```
|
|
|
|
## CSV import
|
|
|
|
Upload CSV files at `/upload`. The bank profile is auto-detected from the header row. Supported profiles:
|
|
|
|
| Bank | Account type |
|
|
|---|---|
|
|
| Discover High Yield Savings | BANK |
|
|
| Discover Credit Card | CREDIT_CARD |
|
|
| Huntington Checking | BANK |
|
|
| Fidelity (cash activity only) | BANK |
|
|
|
|
If auto-detection fails, a column mapper is shown for manual field assignment.
|
|
|
|
**BANK** accounts count toward net worth and cash flow. **CREDIT_CARD** accounts are tracked only.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
# Start the database
|
|
docker compose up db -d
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Apply schema
|
|
npx prisma db push
|
|
|
|
# Seed a user
|
|
npx prisma db seed
|
|
|
|
# Start the dev server
|
|
npm run dev
|
|
```
|
|
|
|
The app is at http://localhost:3000.
|
|
|
|
## Architecture
|
|
|
|
| Layer | Choice |
|
|
|---|---|
|
|
| Framework | Next.js 16 App Router + TypeScript |
|
|
| Database | PostgreSQL 16 + Prisma ORM |
|
|
| Auth | NextAuth.js v5 (JWT sessions, bcrypt) |
|
|
| UI | Tailwind CSS + shadcn/ui |
|
|
| Charts | Recharts |
|
|
| Deployment | Docker Compose |
|