# b-3llum/finance-tracker architecture

> Architecture diagram of the GitHub repository b-3llum/finance-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b-3llum/finance-tracker
- Repository: https://github.com/b-3llum/finance-tracker

## Overview

FinTrack is a self-hosted personal finance tracker. Its main workflow is to register and configure an account, add or import transactions, then use those records for balance tracking, budgets, forecasts, reports, and AI insights. The graph preserves the README’s other finance domains and the sampled API-to-SQLite behavior. Page-to-endpoint wiring and unsampled route internals are not shown; documented AI provider options are marked optional.

Main entry points: [`src/lib/db.ts`](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/db.ts) (SQLite database), [`src/lib/auth.ts`](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/auth.ts) (JWT authentication), [`src/app/api/ai`](https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/ai) (AI feature routes), [`src/lib/ai-client.ts`](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/ai-client.ts) (AI provider client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and interface"]
  node_authui["Login and registration<br/>[page.tsx]"]
  node_appui["Finance workspace<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_pwa["Offline app shell<br/>[sw.js]"]
end

subgraph group_records["Financial records"]
  node_transactions["Transactions API<br/>[route.ts]"]
  node_import["Bank data import<br/>[route.ts]"]
  node_accounts["Accounts and balances<br/>[route.ts]"]
  node_categories["Categories<br/>[route.ts]"]
  node_bills["Recurring bills<br/>[route.ts]"]
end

subgraph group_planning["Planning and analysis"]
  node_budget["Category budgets<br/>[route.ts]"]
  node_savings["Savings goals<br/>[route.ts]"]
  node_debts["Debt tracking"]
  node_networth["Net worth<br/>[route.ts]"]
  node_forecast["Cash flow forecast<br/>[route.ts]"]
end

subgraph group_insights["Reports and AI"]
  node_reports["Report generation<br/>[route.ts]"]
  node_reportgen["Report builder"]
  node_aiapi["AI feature routes"]
  node_aiclient["AI provider client<br/>[ai-client.ts]"]
end

subgraph group_runtime["Runtime services"]
  node_authapi["Authentication routes"]
  node_authlib["JWT authentication<br/>[auth.ts]"]
  node_ollama["Ollama service<br/>[ollama.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
end

node_person(("Finance user"))
node_cloudai{{"Claude or OpenAI"}}

node_person -->|"uses"| node_authui
node_person -->|"uses"| node_appui
node_authui -->|"submits credentials"| node_authapi
node_authapi -->|"authenticates"| node_authlib
node_transactions -->|"gets user ID"| node_authlib
node_import -->|"gets user ID"| node_authlib
node_accounts -->|"gets user ID"| node_authlib
node_categories -->|"gets user ID"| node_authlib
node_budget -->|"gets user ID"| node_authlib
node_forecast -->|"gets user ID"| node_authlib
node_reports -->|"gets user ID"| node_authlib
node_aiapi -->|"gets user ID"| node_authlib
node_transactions -->|"reads and writes"| node_database
node_import -->|"imports rows"| node_database
node_accounts -->|"reads and writes"| node_database
node_categories -->|"reads and writes"| node_database
node_bills -->|"reads and writes"| node_database
node_budget -->|"reads"| node_database
node_savings -->|"reads and writes"| node_database
node_debts -->|"reads and writes"| node_database
node_networth -->|"reads"| node_database
node_forecast -->|"reads"| node_database
node_reports -->|"generates reports"| node_reportgen
node_reportgen -->|"stores report data"| node_database
node_aiapi -->|"requests AI"| node_aiclient
node_aiclient -.->|"queries local model"| node_ollama
node_aiclient -.->|"queries cloud model"| node_cloudai
node_aiapi -->|"reads and stores insights"| node_database
node_pwa -->|"supports offline use"| node_person

click node_authui "https://github.com/b-3llum/finance-tracker/blob/main/src/app/(auth)/login/page.tsx"
click node_appui "https://github.com/b-3llum/finance-tracker/blob/main/src/app/(app)/layout.tsx"
click node_dashboard "https://github.com/b-3llum/finance-tracker/blob/main/src/app/(app)/dashboard/page.tsx"
click node_authapi "https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/auth"
click node_authlib "https://github.com/b-3llum/finance-tracker/blob/main/src/lib/auth.ts"
click node_transactions "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/transactions/route.ts"
click node_import "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/import/route.ts"
click node_accounts "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/accounts/route.ts"
click node_categories "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/categories/route.ts"
click node_bills "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/bills/route.ts"
click node_budget "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/budget/route.ts"
click node_savings "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/savings/route.ts"
click node_debts "https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/debts"
click node_networth "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/net-worth/route.ts"
click node_forecast "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/forecast/route.ts"
click node_reports "https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/reports/route.ts"
click node_reportgen "https://github.com/b-3llum/finance-tracker/blob/main/src/lib/report-generator.ts"
click node_aiapi "https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/ai"
click node_aiclient "https://github.com/b-3llum/finance-tracker/blob/main/src/lib/ai-client.ts"
click node_ollama "https://github.com/b-3llum/finance-tracker/blob/main/src/lib/ollama.ts"
click node_database "https://github.com/b-3llum/finance-tracker/blob/main/src/lib/db.ts"
click node_pwa "https://github.com/b-3llum/finance-tracker/blob/main/public/sw.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_authui,node_appui,node_dashboard,node_pwa,node_person toneBlue
class node_transactions,node_import,node_accounts,node_categories,node_bills toneAmber
class node_budget,node_savings,node_debts,node_networth,node_forecast toneMint
class node_reports,node_reportgen,node_aiapi,node_aiclient toneRose
class node_authapi,node_authlib,node_ollama,node_database,node_cloudai toneIndigo
```

## Components

### Access and interface

- [Login and registration](https://github.com/b-3llum/finance-tracker/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Finance workspace](https://github.com/b-3llum/finance-tracker/blob/main/src/app/(app)/layout.tsx): `src/app/(app)/layout.tsx`
- [Dashboard](https://github.com/b-3llum/finance-tracker/blob/main/src/app/(app)/dashboard/page.tsx): `src/app/(app)/dashboard/page.tsx`
- [Offline app shell](https://github.com/b-3llum/finance-tracker/blob/main/public/sw.js): `public/sw.js`

### Financial records

- [Transactions API](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/transactions/route.ts): `src/app/api/transactions/route.ts`
- [Bank data import](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/import/route.ts): `src/app/api/import/route.ts`
- [Accounts and balances](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/accounts/route.ts): `src/app/api/accounts/route.ts`
- [Categories](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/categories/route.ts): `src/app/api/categories/route.ts`
- [Recurring bills](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/bills/route.ts): `src/app/api/bills/route.ts`

### Planning and analysis

- [Category budgets](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/budget/route.ts): `src/app/api/budget/route.ts`
- [Savings goals](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/savings/route.ts): `src/app/api/savings/route.ts`
- [Debt tracking](https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/debts): `src/app/api/debts`
- [Net worth](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/net-worth/route.ts): `src/app/api/net-worth/route.ts`
- [Cash flow forecast](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/forecast/route.ts): `src/app/api/forecast/route.ts`

### Reports and AI

- [Report generation](https://github.com/b-3llum/finance-tracker/blob/main/src/app/api/reports/route.ts): `src/app/api/reports/route.ts`
- [Report builder](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/report-generator.ts): `src/lib/report-generator.ts`
- [AI feature routes](https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/ai): `src/app/api/ai`
- [AI provider client](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/ai-client.ts): `src/lib/ai-client.ts`

### Runtime services

- [Authentication routes](https://github.com/b-3llum/finance-tracker/tree/main/src/app/api/auth): `src/app/api/auth`
- [JWT authentication](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Ollama service](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/ollama.ts): `src/lib/ollama.ts`
- [SQLite database](https://github.com/b-3llum/finance-tracker/blob/main/src/lib/db.ts): `src/lib/db.ts`

### Other components

- **Finance user**
- **Claude or OpenAI**

## Connections

- Finance user → Login and registration: uses
- Finance user → Finance workspace: uses
- Login and registration → Authentication routes: submits credentials
- Authentication routes → JWT authentication: authenticates
- Transactions API → JWT authentication: gets user ID
- Bank data import → JWT authentication: gets user ID
- Accounts and balances → JWT authentication: gets user ID
- Categories → JWT authentication: gets user ID
- Category budgets → JWT authentication: gets user ID
- Cash flow forecast → JWT authentication: gets user ID
- Report generation → JWT authentication: gets user ID
- AI feature routes → JWT authentication: gets user ID
- Transactions API → SQLite database: reads and writes
- Bank data import → SQLite database: imports rows
- Accounts and balances → SQLite database: reads and writes
- Categories → SQLite database: reads and writes
- Recurring bills → SQLite database: reads and writes
- Category budgets → SQLite database: reads
- Savings goals → SQLite database: reads and writes
- Debt tracking → SQLite database: reads and writes
- Net worth → SQLite database: reads
- Cash flow forecast → SQLite database: reads
- Report generation → Report builder: generates reports
- Report builder → SQLite database: stores report data
- AI feature routes → AI provider client: requests AI
- AI provider client → Ollama service: queries local model
- AI provider client → Claude or OpenAI: queries cloud model
- AI feature routes → SQLite database: reads and stores insights
- Offline app shell → Finance user: supports offline use