account-tracking/docs/superpowers/specs/2026-03-19-finance-tracker-design.md

Finance Tracker — Design Spec

Date: 2026-03-19 Stack: .NET 8 · MySQL 8 · Vue.js 3 · Vuetify 3 · NSwag · ApexCharts · Docker

---

Overview

A personal web app for tracking finances. The primary workflow is importing CSV bank exports (ČSOB format) and visualising spending over time. Single-user with a login screen for security. Deployed via docker-compose on a home server behind an existing Nginx reverse proxy.

---

Architecture

Three docker-compose services sharing an internal network:

Service	Image	Exposed Port	Role
api	.NET 8 (custom)	5000	REST API + business logic
web	Nginx (custom, serves Vue build)	3000	Frontend SPA
db	MySQL 8	3306 (internal only)	Persistence

Host Nginx routing — the .NET API mounts all routes under /api/..., so Nginx passes the full URI through without stripping the prefix:

location /api/  { proxy_pass http://localhost:5000; }
location /      { proxy_pass http://localhost:3000; }

CORS — the API enables CORS for http://localhost:3000 (dev) and the production frontend origin via the ALLOWED_ORIGIN env var.

Secrets provided via .env file (not committed to git):

• DB_CONNECTION — MySQL connection string
• JWT_SECRET — 32-byte random value, Base64-encoded (e.g. openssl rand -base64 32)
• APP_USERNAME / APP_PASSWORD — single user credentials (password stored as bcrypt hash in .env)
• ALLOWED_ORIGIN — frontend origin for CORS

DB persistence & migrations — a named Docker volume persists MySQL data across restarts. The db service has a health check (mysqladmin ping). The api service depends on db with condition: service_healthy. Schema is managed via EF Core migrations, applied automatically at API startup using Polly retry: 5 attempts, exponential backoff (1s, 2s, 4s, 8s, 16s). If all attempts fail, the container exits.

---

NSwag Client Generation

The TypeScript API client is generated from the .NET OpenAPI spec at build time — no running API or database is needed.

Mechanism:

1. AccountTracking.Api uses the NSwag.MSBuild NuGet package, which generates openapi.json into the project output directory as part of dotnet build.
2. The AccountTracking.Web Dockerfile is a two-stage build:
   • Stage 1 (sdk): runs dotnet build on the API project (no DB needed) — produces openapi.json.
   • Stage 2 (node): copies openapi.json from stage 1, runs nswag run nswag.json to generate the TypeScript client into src/api/, then runs npm run build.
3. The final image is Nginx serving the Vue build output.

NSwag client base URL: configured as /api (relative), so it works identically in development (through Vite's dev server proxy) and production (through Nginx proxy). No build-time URL argument needed.

Vite dev proxy — vite.config.ts proxies /api → http://localhost:5000 with no path rewriting (since the API mounts all routes under /api/...):

server: {
  proxy: {
    '/api': { target: 'http://localhost:5000', changeOrigin: true }
  }
}

---

Data Model

All DATETIME columns are stored as UTC. EF Core models use DateTimeKind.Utc on datetime properties (required when using Pomelo's MySQL EF Core provider to avoid implicit UTC conversion issues).

transactions

Column	Type	Notes
id	INT PK AUTO_INCREMENT
account_number	VARCHAR(30)	e.g. 216868554/0300
booking_date	DATE
amount	DECIMAL(15,2)	negative = outgoing
currency	VARCHAR(3)	CZK
balance	DECIMAL(15,2)	account balance after transaction
counter_party_name	VARCHAR(255)	merchant or sender name
operation_description	VARCHAR(255)	e.g. "Transakce platební kartou"
message	TEXT	full description from CSV
category	VARCHAR(100)	from bank CSV, used as-is
variable_symbol	VARCHAR(30)
bank_note	VARCHAR(255)	"vlastní poznámka" from CSV (read-only, not user-editable)
transaction_id	VARCHAR(512) UNIQUE, collation utf8mb4_bin	case-sensitive; format transhist-v-YYYY-MM_<sha>

Additional CSV columns (counter bank code, constant symbol, specific symbol, order name, exchange rate, E2E id, payer reference, original payer, final recipient, original transaction) stored as nullable VARCHAR(255) but not used in UI.

import_logs

Column	Type	Notes
id	INT PK AUTO_INCREMENT
imported_at	DATETIME	stored as UTC
filename	VARCHAR(255)	original filename
records_imported	INT	new transactions saved
records_skipped	INT	duplicates ignored

---

ČSOB CSV Format

The CSV is semicolon-delimited, UTF-8. Lines 1–2 are a bank-generated title. The parser locates the header row by scanning for the first line that starts with číslo účtu (case-insensitive) rather than hardcoding a line number.

Column mapping:

CSV Column (Czech)	Model Field
číslo účtu	account_number
datum zaúčtování	booking_date
částka	amount
měna	currency
zůstatek	balance
jméno protistrany	counter_party_name
označení operace	operation_description
zpráva	message
kategorie	category
variabilní symbol	variable_symbol
vlastní poznámka	bank_note
ID transakce	transaction_id

Amount and balance values use Czech locale formatting (comma as decimal separator, space as thousands separator) — normalise before parsing (remove spaces, replace comma with dot).

Error handling:

• Header row not found, or required columns (částka, ID transakce, datum zaúčtování) missing → HTTP 400 { error: string }
• File exceeds 10 MB → HTTP 400 { error: "File too large" } (Kestrel MaxRequestBodySize set to 10 MB; framework error caught and returned as structured response)
• Zero new transactions and zero duplicates → HTTP 200 { recordsImported: 0, recordsSkipped: 0 }

---

API Endpoints

All endpoints except login require Authorization: Bearer <token>. JWT tokens expire after 30 days; expiresAt is an ISO 8601 UTC string (e.g. "2026-04-18T10:00:00Z"). The frontend stores both token and expiresAt in localStorage. The Vue Router navigation guard checks Date.now() < Date.parse(expiresAt) to detect expiry locally. On any 401 API response, the auth store clears both values and redirects to /login.

POST  /api/auth/login
      Body: { username, password }
      Returns 200: { token, expiresAt }
      Returns 401: wrong credentials

POST  /api/transactions/import
      Body: multipart/form-data (CSV file, max 10 MB)
      Returns 200: { recordsImported, recordsSkipped }
      Returns 400: { error: string }

GET   /api/transactions
      Query: year (required), month (optional), category (optional),
             search (optional), page (default 1), pageSize (default 50, max 200)
      — search: case-insensitive contains match (%term%) on counter_party_name
                OR message; uses database collation (utf8mb4_unicode_ci)
      Returns 200: { items: [...], totalCount, page, pageSize }

GET   /api/transactions/categories
      No query params — returns all-time distinct categories (not period-filtered)
      Returns 200: string[] sorted alphabetically

GET   /api/dashboard/summary
      Query: year (required), month (optional)
      — if month omitted: totals are for the entire year
      — if month provided: totals are for that month only
      Returns 200: { totalSpent, totalIncome }
      — totalSpent: absolute value of sum of negative amounts for the period
      — totalIncome: sum of positive amounts for the period

GET   /api/dashboard/spending-by-category
      Query: year (required), month (optional)
      — if month omitted: totals for the entire year
      — if month provided: totals for that month only
      Returns 200: [{ category, total }]
      — total: absolute value of sum of negative amounts for that category in period
      — positive amounts within any category are excluded from totals
      — sorted descending by total

GET   /api/dashboard/monthly-balances
      Query: year (required)
      Returns 200: [{ month, closingBalance }]
      — one entry per month that has transactions (months with no transactions omitted)
      — closingBalance: balance from the transaction with the latest booking_date
                        in that month (highest id as tiebreaker for same-date rows)
      — always year-scoped

GET   /api/dashboard/cumulative-spending
      Query: year (required), month (required)
      Returns 200: [{ day, cumulativeSpent }]
      — one entry per day that has outgoing transactions within the given month
      — cumulativeSpent: running absolute total of negative amounts from day 1
                         through that day (sorted ascending by day)
      — days with no spending are included with the previous day's cumulative value
        so the line chart has no gaps

---

Frontend

Pages

Page	Route	Auth Required
Login	/login	No
Dashboard	/	Yes
Transactions	/transactions	Yes

JWT and expiresAt stored in localStorage. Vue Router navigation guard checks local expiry and redirects unauthenticated/expired users to /login. On 401 API response, auth store clears storage and redirects to /login.

Dashboard Layout

App bar — spans full width at top. Contains app title on the left and an "Upload CSV" button on the right. Clicking Upload CSV opens a file picker dialog; the selected file is uploaded via POST /api/transactions/import with an inline result snackbar ("Imported X, skipped Y" or error message). No separate import page.

Two-column body — equal-width columns side by side below the app bar.

Left column — Year Summary

• Toolbar: previous-year button, selected year label, next-year button
• Summary row: Total Expenses (red) | Total Income (green) — year-only totals (see API note below)
• Two sub-columns:
  • Doughnut chart (ApexCharts) — expenses by category for the selected year; legend with category name and amount
  • Monthly balances bar chart (ApexCharts) — closing balance per month for the selected year, from /api/dashboard/monthly-balances

Right column — Month Summary

• Toolbar: previous-month button, selected month+year label, next-month button (wraps year when crossing Jan/Dec boundary)
• Summary row: Total Expenses (red) | Total Income (green) — from /api/dashboard/summary (year+month)
• Two sub-columns:
  • Doughnut chart (ApexCharts) — expenses by category for the selected month; legend with category name and amount
  • Cumulative spending line chart (ApexCharts) — running total of expenses day by day through the selected month, from /api/dashboard/cumulative-spending

All widgets show a skeleton loader while fetching and a subtle error indicator on failure.

Shared period state — both columns share a single { year, month } value. The toolbars are two views of the same state:

• Next/prev month (right toolbar): increments/decrements the month, wrapping the year (e.g. Dec 2024 → Jan 2025 updates both columns to year=2025, month=1)
• Next/prev year (left toolbar): increments/decrements the year, keeping the current month (e.g. year 2025, month=1 → next year → year=2026, month=1, right column updates to Jan 2026)

Transactions Page

Vuetify data table:

• Columns: Date, Counter Party, Category, Amount, Balance
• Filters: year (required), month (optional), category dropdown — server-side query params
• Search box — server-side (search query param, debounced 300 ms)
• Server-side pagination (page, pageSize=50)

State Management (Pinia)

• auth — token, expiresAt, login/logout actions, 401 handler
• dashPeriod — { year, month } shared by both dashboard columns; next/prev month wraps year, next/prev year keeps month
• txPeriod — selected year/month for the transactions page (independent)

---

Project Structure

account-tracking/
├── docker-compose.yml
├── .env                          # secrets (gitignored)
├── .env.example                  # template with placeholder values
├── src/
│   ├── AccountTracking.Api/      # .NET 8 Web API
│   │   ├── Controllers/
│   │   ├── Services/
│   │   ├── Models/
│   │   ├── Data/                 # EF Core DbContext + migrations
│   │   └── Dockerfile
│   └── AccountTracking.Web/      # Vue 3 + Vuetify frontend
│       ├── src/
│       │   ├── api/              # NSwag-generated client (do not edit manually)
│       │   ├── stores/           # Pinia: auth, period
│       │   ├── views/            # Login, Dashboard, Transactions
│       │   └── components/       # YearSummary, MonthSummary, DonutChart,
│       │                         # MonthlyBalancesChart, CumulativeSpendingChart
│       ├── nswag.json            # NSwag config (input: openapi.json, output: src/api/)
│       ├── vite.config.ts        # includes /api proxy to http://localhost:5000
│       └── Dockerfile
└── docs/
    └── superpowers/specs/

---

Key Decisions

• Single user from config — no user table; credentials in .env; password stored as bcrypt hash.
• JWT lifetime 30 days — long-lived for convenience; Base64-encoded 32-byte secret; expiry in ISO 8601 UTC; checked locally in router guard; redirect on expiry or 401.
• Bank categories used as-is — no re-categorisation UI needed.
• Deduplication via transaction_id — format transhist-v-YYYY-MM_<sha>; VARCHAR(512) utf8mb4_bin (case-sensitive) for correctness and future-proofing.
• CSV header detection — scan for line starting with číslo účtu; do not hardcode line number.
• Spending totals exclude positive amounts per category — refunds within a spending category are excluded from totals.
• Dashboard columns share one period — a single { year, month } drives both columns; month toolbar wraps the year on overflow, year toolbar keeps the month.
• Upload CSV in app bar — file picker dialog in-place, no separate import page; result shown as snackbar.
• Month summary line chart is cumulative spending — running total of expenses day by day through the selected month; gaps filled so line is continuous.
• Monthly balances bar chart — closing balance per month for the year (sparse, months with no data omitted).
• Search is contains-match (OR) — %term% on counter_party_name OR message; case-insensitive via utf8mb4_unicode_ci.
• Server-side search and pagination — no client-side filtering of paginated data.
• NSwag via MSBuild — openapi.json generated at dotnet build; web Dockerfile copies it; no running API needed.
• NSwag client base URL: /api — relative; Vite dev proxy and Nginx prod proxy both resolve it correctly.
• EF Core migrations at startup — Polly retry: 5 attempts, exponential backoff; container exits on all-fail.
• EF Core UTC datetime — DateTimeKind.Utc on all datetime model properties (Pomelo requirement).
• bank_note is read-only — maps to ČSOB's "vlastní poznámka"; no user-edit UI.
• ApexCharts — Vue 3 compatible, dark theme compatible with Vuetify.