kakei 家計

A single-user personal finance tracker. Record transactions and account balances manually or by uploading a bank screenshot — a local AI vision model (Ollama) extracts the data and pre-fills the form for you.

---

Prerequisites

Tool	Version	Purpose
Docker Desktop	any recent	PostgreSQL database
pyenv	any	Python version management
Python	3.14.3 (via pyenv)	Backend runtime
nvm	any	Node.js version management
Node.js	24 (via nvm)	Frontend build tooling
Ollama	any recent	Local AI vision model

---

First-Time Setup

1. Configure environment variables

cp .env.example .env

Open .env and fill in two values:

Generate a secret key:

openssl rand -hex 32

Paste the output as SECRET_KEY=...

Generate your login password hash:

cd backend && source .venv/bin/activate
python -c "import bcrypt; print(bcrypt.hashpw(b'your-password-here', bcrypt.gensalt()).decode())"

Paste the output as APP_PASSWORD_HASH=...

2. Start the database

docker compose up -d

Verify it is healthy:

docker compose ps

3. Create the Python virtual environment and install dependencies

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. Run database migrations

# (inside backend/ with .venv active)
alembic upgrade head

5. Install frontend dependencies

cd frontend
source ~/.nvm/nvm.sh   # if nvm is not already in your shell
npm install

6. Pull the Ollama vision model

ollama pull qwen3-vl:4b

This is a one-time download. qwen3-vl:4b is a strong vision model well-suited for document and screenshot OCR.

---

Starting the Application

Open three terminal tabs and run one command in each.

Tab 1 — Backend

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

The API is now available at http://localhost:8000. Interactive API docs: http://localhost:8000/docs

Tab 2 — Frontend

cd frontend
source ~/.nvm/nvm.sh   # if nvm is not already in your shell
npm run dev

The app is now available at http://localhost:5173.

Tab 3 — Ollama (required for screenshot parsing)

ollama serve

If Ollama is not running, all other features still work — only the "Parse with AI" button will fail. The frontend warns you when Ollama is unreachable.

---

Stopping the Application

• Backend / Frontend / Ollama: Ctrl+C in each terminal tab.
• Database: docker compose stop (data is preserved) or docker compose down (stops containers, data volume intact).

---

Use Cases

1. Log a transaction manually

1. Go to Transactions (/transactions).
2. Click Add Transaction.
3. Fill in the form — amount (positive for income, negative for expense), account number, description, date, category, and status.
4. Click Save. The transaction appears in the table immediately.

Tip: Use a negative amount for debits (e.g. -42.50) and a positive amount for credits (e.g. +2500.00). The table colour-codes them automatically.

---

2. Log a transaction from a bank screenshot

1. Go to Transactions → Add Transaction.
2. Switch to the Upload Screenshot tab.
3. Drag and drop (or click to select) a screenshot of a bank transaction.
4. Click Parse with AI — Ollama reads the image and extracts the amount, description, date, account number, and currency.
5. The modal automatically switches to the Manual Entry tab with the form pre-filled. A preview banner shows what was extracted.
6. Review and correct any fields, then click Save.

The original screenshot is stored in uploads/ and linked to the transaction as a receipt.

---

3. Record an account balance snapshot

Account snapshots are point-in-time balance records used to build the balance history chart on the dashboard.

1. Go to Accounts (/accounts).
2. Click Add Snapshot.
3. Enter the account name (e.g. "Chase Checking"), account number (last 4 digits is fine), account type, balance, currency, and the date/time the balance was observed.
4. Click Save. A card for that account appears in the grid showing the latest balance.

You can also upload a bank balance screenshot and let Ollama pre-fill the form — the flow is identical to transactions (steps 2–6 above, just from the Accounts page).

---

4. Browse and filter transactions

On the Transactions page, use the filter bar to narrow results:

Filter	What it does
Account number	Exact or partial match on account number
Category	Filter by spending category (food, transport, income, etc.)
Status	Show only completed or pending transactions
Start / End date	Restrict to a date range
Clear filters	Resets all filters at once

---

5. Export transactions to CSV

1. On the Transactions page, optionally set Start date and/or End date to scope the export.
2. Click Export CSV in the top-right. Your browser downloads a .csv file with all matching transactions.

---

6. View the dashboard

The Dashboard (/) gives a financial overview at a glance:

• Summary cards — Total balance across all accounts, income year-to-date, expenses year-to-date, and net.
• Balance History chart — Line chart showing each account's balance over time, built from your snapshots.
• Income vs Expenses chart — Grouped bar chart by month. Use the year picker to compare different years.
• Recent Transactions — The last 10 transactions in a quick-scan table.

The dashboard reflects the data you have entered. Add more snapshots over time for a richer balance history chart.

---

Project Layout

kakei/
├── .env                  # secrets (gitignored) — copy from .env.example
├── docker-compose.yml    # PostgreSQL 16
├── uploads/              # stored screenshots (gitignored)
├── docs/                 # architecture diagrams
├── backend/
│   ├── .venv/            # Python virtual environment (gitignored)
│   ├── requirements.txt
│   ├── alembic/          # database migrations
│   └── app/
│       ├── main.py
│       ├── routers/      # auth, artifacts, transactions, accounts, dashboard
│       ├── models/       # SQLAlchemy ORM models
│       ├── schemas/      # Pydantic request/response schemas
│       └── services/     # vision.py (Ollama), file_storage.py
└── frontend/
    └── src/
        ├── api/          # Axios API client modules
        ├── components/   # layout, forms, charts, upload, common
        ├── pages/        # Dashboard, Transactions, Accounts, Login
        └── store/        # Zustand auth store

For a deeper look at how components interact, see docs/backend-architecture.md and docs/frontend-architecture.md.