# mhabachia/cashflow architecture

> Architecture diagram of the GitHub repository mhabachia/cashflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mhabachia/cashflow
- Repository: https://github.com/mhabachia/cashflow

## Overview

Cashflow is a self-hosted personal-finance web app and PWA. Its main workflow is recording or importing income and expenses, categorizing transactions, and using the resulting data for monthly cash-flow, budgets, recurring costs, and savings goals. Banking adds PSD2 account linking and transaction synchronization; authentication and local SQLite persistence support the application. The graph reflects README capabilities and the supplied source index and excerpts; unsampled page wiring and some action internals are not asserted.

Main entry points: [`src/lib/db/index.ts`](https://github.com/mhabachia/cashflow/blob/main/src/lib/db/index.ts) (SQLite finance store), [`src/components/transactions/transactions-view.tsx`](https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/transactions-view.tsx) (Transaction list), [`src/lib/bank-sync/sync-engine.ts`](https://github.com/mhabachia/cashflow/blob/main/src/lib/bank-sync/sync-engine.ts) (Transaction sync engine), [`src/app/(app)/page.tsx`](https://github.com/mhabachia/cashflow/blob/main/src/app/(app)/page.tsx) (Cash-flow dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_finance["Finance workspace"]
  node_dashboard["Cash-flow dashboard<br/>[page.tsx]"]
  node_dashboard_widgets["Dashboard widgets"]
  node_savings["Savings goals"]
  node_categories["Categories and budgets"]
  node_recurring["Recurring costs"]
  node_recurring_form["Recurring entry form"]
end

subgraph group_ingest["Transactions and import"]
  node_transactions["Transaction list"]
  node_quick_add["Quick entry"]
  node_statement_import["Statement import"]
  node_csv_actions["CSV and statement actions<br/>[csv-actions.ts]"]
  node_pdf_parser["PDF statement parser"]
  node_transaction_actions["Transaction actions"]
  node_category_rules["Auto-categorization rules<br/>[category-rules.ts]"]
end

subgraph group_banking["Banking"]
  node_banking_view["Banking hub"]
  node_bank_actions["Bank account actions<br/>[bank-actions.ts]"]
  node_bank_authorize["Bank authorization<br/>[route.ts]"]
  node_bank_callback["Bank callback<br/>[route.ts]"]
  node_bank_provider["Banking provider<br/>[provider.ts]"]
  node_sync_engine["Transaction sync engine<br/>[sync-engine.ts]"]
  node_vault["Token vault<br/>[vault.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth_pages["Login and registration<br/>[page.tsx]"]
  node_auth_route["Authentication API<br/>[route.ts]"]
  node_auth["Authentication service<br/>[auth.ts]"]
  node_auth_actions["Account actions<br/>[auth-actions.ts]"]
  node_session["Session and access checks<br/>[session.ts]"]
end

subgraph group_platform["Shared platform"]
  node_database[("SQLite finance store<br/>[index.ts]")]
  node_schema["Data model<br/>[schema.ts]"]
end

node_user(("User"))

node_user -->|"views finances"| node_dashboard
node_dashboard -->|"reads monthly data"| node_database
node_dashboard -->|"renders widgets"| node_dashboard_widgets
node_dashboard -->|"renders goals"| node_savings
node_user -->|"manages transactions"| node_transactions
node_transactions -->|"invokes actions"| node_transaction_actions
node_transactions -->|"opens entry"| node_quick_add
node_quick_add -->|"submits transaction"| node_transaction_actions
node_transactions -->|"opens import"| node_statement_import
node_statement_import -->|"submits import"| node_csv_actions
node_csv_actions -->|"parses statements"| node_pdf_parser
node_csv_actions -->|"applies rules"| node_category_rules
node_transactions -->|"manages rules"| node_category_rules
node_user -->|"sets budgets"| node_categories
node_categories -->|"manages finance settings"| node_database
node_user -->|"manages recurring costs"| node_recurring
node_recurring -->|"creates entries"| node_recurring_form
node_recurring_form -.->|"saves recurring items"| node_database
node_savings -.->|"updates goals"| node_database
node_user -->|"manages accounts"| node_banking_view
node_banking_view -->|"invokes actions"| node_bank_actions
node_bank_actions -->|"starts synchronization"| node_sync_engine
node_bank_authorize -->|"starts authorization"| node_bank_provider
node_bank_callback -->|"exchanges code"| node_bank_provider
node_bank_callback -->|"starts initial sync"| node_sync_engine
node_sync_engine -->|"fetches transactions"| node_bank_provider
node_sync_engine -->|"reads and writes"| node_database
node_bank_callback -->|"protects bank tokens"| node_vault
node_sync_engine -->|"categorizes imports"| node_category_rules
node_user -->|"signs in"| node_auth_pages
node_auth_pages -.->|"uses authentication API"| node_auth_route
node_auth_route -->|"dispatches authentication"| node_auth
node_auth -->|"uses identity store"| node_database
node_auth_actions -->|"checks access"| node_session
node_session -->|"checks session"| node_auth
node_auth_actions -->|"manages accounts"| node_database
node_database -->|"uses data model"| node_schema

click node_dashboard "https://github.com/mhabachia/cashflow/blob/main/src/app/(app)/page.tsx"
click node_dashboard_widgets "https://github.com/mhabachia/cashflow/blob/main/src/components/dashboard/dashboard-widget-system.tsx"
click node_savings "https://github.com/mhabachia/cashflow/blob/main/src/components/savings/savings-goals-section.tsx"
click node_categories "https://github.com/mhabachia/cashflow/blob/main/src/components/categories/categories-presets-view.tsx"
click node_recurring "https://github.com/mhabachia/cashflow/blob/main/src/components/recurring/fixed-costs-view.tsx"
click node_recurring_form "https://github.com/mhabachia/cashflow/blob/main/src/components/recurring/create-recurring-modal.tsx"
click node_transactions "https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/transactions-view.tsx"
click node_quick_add "https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/quick-add-modal.tsx"
click node_statement_import "https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/statement-import-modal.tsx"
click node_csv_actions "https://github.com/mhabachia/cashflow/blob/main/src/actions/csv-actions.ts"
click node_pdf_parser "https://github.com/mhabachia/cashflow/blob/main/src/lib/pdf-statement-parser.ts"
click node_transaction_actions "https://github.com/mhabachia/cashflow/blob/main/src/actions/transaction-actions.ts"
click node_category_rules "https://github.com/mhabachia/cashflow/blob/main/src/lib/category-rules.ts"
click node_banking_view "https://github.com/mhabachia/cashflow/blob/main/src/components/banking/banking-hub-view.tsx"
click node_bank_actions "https://github.com/mhabachia/cashflow/blob/main/src/actions/bank-actions.ts"
click node_bank_authorize "https://github.com/mhabachia/cashflow/blob/main/src/app/api/bank-sync/authorize/route.ts"
click node_bank_callback "https://github.com/mhabachia/cashflow/blob/main/src/app/api/bank-sync/callback/route.ts"
click node_bank_provider "https://github.com/mhabachia/cashflow/blob/main/src/lib/bank-sync/provider.ts"
click node_sync_engine "https://github.com/mhabachia/cashflow/blob/main/src/lib/bank-sync/sync-engine.ts"
click node_vault "https://github.com/mhabachia/cashflow/blob/main/src/lib/crypto/vault.ts"
click node_auth_pages "https://github.com/mhabachia/cashflow/blob/main/src/app/(auth)/login/page.tsx"
click node_auth_route "https://github.com/mhabachia/cashflow/blob/main/src/app/api/auth/%5B...all%5D/route.ts"
click node_auth "https://github.com/mhabachia/cashflow/blob/main/src/lib/auth.ts"
click node_auth_actions "https://github.com/mhabachia/cashflow/blob/main/src/actions/auth-actions.ts"
click node_session "https://github.com/mhabachia/cashflow/blob/main/src/lib/session.ts"
click node_database "https://github.com/mhabachia/cashflow/blob/main/src/lib/db/index.ts"
click node_schema "https://github.com/mhabachia/cashflow/blob/main/src/lib/db/schema.ts"

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_dashboard,node_dashboard_widgets,node_savings,node_categories,node_recurring,node_recurring_form,node_user toneBlue
class node_transactions,node_quick_add,node_statement_import,node_csv_actions,node_pdf_parser,node_transaction_actions,node_category_rules toneAmber
class node_banking_view,node_bank_actions,node_bank_authorize,node_bank_callback,node_bank_provider,node_sync_engine,node_vault toneMint
class node_auth_pages,node_auth_route,node_auth,node_auth_actions,node_session toneRose
class node_database,node_schema toneIndigo
```

## Components

### Finance workspace

- [Cash-flow dashboard](https://github.com/mhabachia/cashflow/blob/main/src/app/(app)/page.tsx): `src/app/(app)/page.tsx`
- [Dashboard widgets](https://github.com/mhabachia/cashflow/blob/main/src/components/dashboard/dashboard-widget-system.tsx): `src/components/dashboard/dashboard-widget-system.tsx`
- [Savings goals](https://github.com/mhabachia/cashflow/blob/main/src/components/savings/savings-goals-section.tsx): `src/components/savings/savings-goals-section.tsx`
- [Categories and budgets](https://github.com/mhabachia/cashflow/blob/main/src/components/categories/categories-presets-view.tsx): `src/components/categories/categories-presets-view.tsx`
- [Recurring costs](https://github.com/mhabachia/cashflow/blob/main/src/components/recurring/fixed-costs-view.tsx): `src/components/recurring/fixed-costs-view.tsx`
- [Recurring entry form](https://github.com/mhabachia/cashflow/blob/main/src/components/recurring/create-recurring-modal.tsx): `src/components/recurring/create-recurring-modal.tsx`

### Transactions and import

- [Transaction list](https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/transactions-view.tsx): `src/components/transactions/transactions-view.tsx`
- [Quick entry](https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/quick-add-modal.tsx): `src/components/transactions/quick-add-modal.tsx`
- [Statement import](https://github.com/mhabachia/cashflow/blob/main/src/components/transactions/statement-import-modal.tsx): `src/components/transactions/statement-import-modal.tsx`
- [CSV and statement actions](https://github.com/mhabachia/cashflow/blob/main/src/actions/csv-actions.ts): `src/actions/csv-actions.ts`
- [PDF statement parser](https://github.com/mhabachia/cashflow/blob/main/src/lib/pdf-statement-parser.ts): `src/lib/pdf-statement-parser.ts`
- [Transaction actions](https://github.com/mhabachia/cashflow/blob/main/src/actions/transaction-actions.ts): `src/actions/transaction-actions.ts`
- [Auto-categorization rules](https://github.com/mhabachia/cashflow/blob/main/src/lib/category-rules.ts): `src/lib/category-rules.ts`

### Banking

- [Banking hub](https://github.com/mhabachia/cashflow/blob/main/src/components/banking/banking-hub-view.tsx): `src/components/banking/banking-hub-view.tsx`
- [Bank account actions](https://github.com/mhabachia/cashflow/blob/main/src/actions/bank-actions.ts): `src/actions/bank-actions.ts`
- [Bank authorization](https://github.com/mhabachia/cashflow/blob/main/src/app/api/bank-sync/authorize/route.ts): `src/app/api/bank-sync/authorize/route.ts`
- [Bank callback](https://github.com/mhabachia/cashflow/blob/main/src/app/api/bank-sync/callback/route.ts): `src/app/api/bank-sync/callback/route.ts`
- [Banking provider](https://github.com/mhabachia/cashflow/blob/main/src/lib/bank-sync/provider.ts): `src/lib/bank-sync/provider.ts`
- [Transaction sync engine](https://github.com/mhabachia/cashflow/blob/main/src/lib/bank-sync/sync-engine.ts): `src/lib/bank-sync/sync-engine.ts`
- [Token vault](https://github.com/mhabachia/cashflow/blob/main/src/lib/crypto/vault.ts): `src/lib/crypto/vault.ts`

### Identity and access

- [Login and registration](https://github.com/mhabachia/cashflow/blob/main/src/app/(auth)/login/page.tsx): `src/app/(auth)/login/page.tsx`
- [Authentication API](https://github.com/mhabachia/cashflow/blob/main/src/app/api/auth/%5B...all%5D/route.ts): `src/app/api/auth/[...all]/route.ts`
- [Authentication service](https://github.com/mhabachia/cashflow/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Account actions](https://github.com/mhabachia/cashflow/blob/main/src/actions/auth-actions.ts): `src/actions/auth-actions.ts`
- [Session and access checks](https://github.com/mhabachia/cashflow/blob/main/src/lib/session.ts): `src/lib/session.ts`

### Shared platform

- [SQLite finance store](https://github.com/mhabachia/cashflow/blob/main/src/lib/db/index.ts): `src/lib/db/index.ts`
- [Data model](https://github.com/mhabachia/cashflow/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Other components

- **User**

## Connections

- User → Cash-flow dashboard: views finances
- Cash-flow dashboard → SQLite finance store: reads monthly data (evidence: `src/app/(app)/page.tsx`)
- Cash-flow dashboard → Dashboard widgets: renders widgets (evidence: `src/app/(app)/page.tsx`)
- Cash-flow dashboard → Savings goals: renders goals (evidence: `src/app/(app)/page.tsx`)
- User → Transaction list: manages transactions
- Transaction list → Transaction actions: invokes actions (evidence: `src/components/transactions/transactions-view.tsx`)
- Transaction list → Quick entry: opens entry (evidence: `src/components/transactions/transactions-view.tsx`)
- Quick entry → Transaction actions: submits transaction (evidence: `src/components/transactions/quick-add-modal.tsx`)
- Transaction list → Statement import: opens import (evidence: `src/components/transactions/transactions-view.tsx`)
- Statement import → CSV and statement actions: submits import (evidence: `src/components/transactions/statement-import-modal.tsx`)
- CSV and statement actions → PDF statement parser: parses statements (evidence: `src/actions/csv-actions.ts`)
- CSV and statement actions → Auto-categorization rules: applies rules (evidence: `src/actions/csv-actions.ts`)
- Transaction list → Auto-categorization rules: manages rules (evidence: `src/components/transactions/transactions-view.tsx`)
- User → Categories and budgets: sets budgets
- Categories and budgets → SQLite finance store: manages finance settings (evidence: `src/components/categories/categories-presets-view.tsx`)
- User → Recurring costs: manages recurring costs
- Recurring costs → Recurring entry form: creates entries
- Recurring entry form → SQLite finance store: saves recurring items
- Savings goals → SQLite finance store: updates goals
- User → Banking hub: manages accounts
- Banking hub → Bank account actions: invokes actions (evidence: `src/components/banking/banking-hub-view.tsx`)
- Bank account actions → Transaction sync engine: starts synchronization (evidence: `src/actions/bank-actions.ts`)
- Bank authorization → Banking provider: starts authorization (evidence: `src/app/api/bank-sync/authorize/route.ts`)
- Bank callback → Banking provider: exchanges code (evidence: `src/app/api/bank-sync/callback/route.ts`)
- Bank callback → Transaction sync engine: starts initial sync (evidence: `src/app/api/bank-sync/callback/route.ts`)
- Transaction sync engine → Banking provider: fetches transactions (evidence: `src/lib/bank-sync/sync-engine.ts`)
- Transaction sync engine → SQLite finance store: reads and writes (evidence: `src/lib/bank-sync/sync-engine.ts`)
- Bank callback → Token vault: protects bank tokens (evidence: `src/app/api/bank-sync/callback/route.ts`)
- Transaction sync engine → Auto-categorization rules: categorizes imports (evidence: `src/lib/bank-sync/sync-engine.ts`)
- User → Login and registration: signs in
- Login and registration → Authentication API: uses authentication API
- Authentication API → Authentication service: dispatches authentication (evidence: `src/app/api/auth/[...all]/route.ts`)
- Authentication service → SQLite finance store: uses identity store (evidence: `src/lib/auth.ts`)
- Account actions → Session and access checks: checks access (evidence: `src/actions/auth-actions.ts`)
- Session and access checks → Authentication service: checks session (evidence: `src/lib/session.ts`)
- Account actions → SQLite finance store: manages accounts (evidence: `src/actions/auth-actions.ts`)
- SQLite finance store → Data model: uses data model (evidence: `src/lib/db/index.ts`)
