# louislefo/finly architecture

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

- Interactive diagram: https://gitdiagram.com/louislefo/finly
- Repository: https://github.com/louislefo/finly
- Video tour (about a minute): https://gitdiagram.com/louislefo/finly/video

## Overview

Finly is a self-hosted personal-finance and wealth-management app. Users sign in, connect bank accounts or import transactions, then review normalized and categorized activity alongside budgets, goals, analysis, and net worth. The backend exposes those workflows through FastAPI and persists user and financial records in SQLite; Woob supplies bank aggregation. README documents broader capabilities such as exports, real estate, and administration. Some frontend-to-backend wiring and unsampled subsystems are represented at subsystem level; dashed edges mark unverified HTTP integration.

Main entry points: [`backend/app/api/router.py`](https://github.com/louislefo/finly/blob/main/backend/app/api/router.py) (API router), [`backend/app/core/database.py`](https://github.com/louislefo/finly/blob/main/backend/app/core/database.py) (SQLite database), [`backend/app/api/endpoints/transactions.py`](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/transactions.py) (Transactions), [`backend/app/api/endpoints/sync.py`](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/sync.py) (Sync and import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_login["Sign in<br/>[page.tsx]"]
  node_finance_ui["Finance workspace"]
  node_client_api["API client<br/>[finly-api.ts]"]
end

subgraph group_api["API workflows"]
  node_api_router["API router<br/>[router.py]"]
  node_auth_api["Authentication<br/>[auth.py]"]
  node_transaction_api["Transactions<br/>[transactions.py]"]
  node_sync_api["Sync and import<br/>[sync.py]"]
  node_woob_api["Bank connections<br/>[woob.py]"]
  node_budget_api["Budgets<br/>[budgets.py]"]
  node_projects_api["Projects and goals<br/>[projects.py]"]
  node_other_api["Other finance APIs"]
end

subgraph group_services["Finance services"]
  node_sync_service["Sync orchestration<br/>[sync_service.py]"]
  node_csv_parser["CSV parsing"]
  node_cleaner["Merchant cleanup<br/>[cleaner_service.py]"]
  node_categorizer["Categorization rules"]
  node_reconciliation["Reconciliation"]
  node_scheduler["Scheduled sync<br/>[cron_jobs.py]"]
end

subgraph group_persistence["Identity and data"]
  node_database[("SQLite database<br/>[database.py]")]
  node_security["Authentication and encryption<br/>[security.py]"]
  node_models["Finance records"]
end

subgraph group_integrations["Bank integrations"]
  node_woob_service["Woob bank engine<br/>[woob_service.py]"]
end

node_person(("Finance user"))
node_banks{{"Banking institutions"}}

node_person -->|"signs in"| node_login
node_person -->|"manages finances"| node_finance_ui
node_login -.->|"uses API client"| node_client_api
node_finance_ui -.->|"requests finance data"| node_client_api
node_client_api -.->|"calls HTTP API"| node_api_router
node_api_router -->|"routes auth"| node_auth_api
node_api_router -->|"routes transactions"| node_transaction_api
node_api_router -->|"routes sync"| node_sync_api
node_api_router -->|"routes banking"| node_woob_api
node_api_router -->|"routes budgets"| node_budget_api
node_api_router -->|"routes projects"| node_projects_api
node_api_router -->|"routes other domains"| node_other_api
node_auth_api -->|"creates tokens"| node_security
node_auth_api -->|"reads and writes users"| node_database
node_transaction_api -->|"parses imports"| node_csv_parser
node_transaction_api -->|"normalizes labels"| node_cleaner
node_transaction_api -->|"categorizes activity"| node_categorizer
node_transaction_api -->|"reconciles records"| node_reconciliation
node_transaction_api -->|"reads and writes"| node_database
node_csv_parser -->|"cleans descriptions"| node_cleaner
node_csv_parser -->|"categorizes imports"| node_categorizer
node_categorizer -->|"cleans merchant names"| node_cleaner
node_sync_api -->|"delegates sync"| node_sync_service
node_sync_api -->|"normalizes transactions"| node_cleaner
node_sync_api -->|"categorizes transactions"| node_categorizer
node_sync_api -->|"reconciles transactions"| node_reconciliation
node_sync_api -->|"reads and writes"| node_database
node_woob_api -->|"configures bank access"| node_woob_service
node_woob_api -->|"starts synchronization"| node_sync_service
node_woob_api -->|"encrypts credentials"| node_security
node_woob_api -->|"stores connections"| node_database
node_woob_service -.->|"retrieves bank data"| node_banks
node_budget_api -->|"reads and writes"| node_database
node_projects_api -->|"reads and writes"| node_database
node_scheduler -.->|"runs scheduled sync"| node_sync_service
node_database -.->|"maps records"| node_models
node_api_router -.->|"starts scheduler"| node_scheduler

click node_login "https://github.com/louislefo/finly/blob/main/finly-app/app/(auth)/login/page.tsx"
click node_finance_ui "https://github.com/louislefo/finly/tree/main/finly-app/components/views"
click node_client_api "https://github.com/louislefo/finly/blob/main/finly-app/lib/api/finly-api.ts"
click node_api_router "https://github.com/louislefo/finly/blob/main/backend/app/api/router.py"
click node_auth_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/auth.py"
click node_transaction_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/transactions.py"
click node_sync_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/sync.py"
click node_woob_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/woob.py"
click node_budget_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/budgets.py"
click node_projects_api "https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/projects.py"
click node_other_api "https://github.com/louislefo/finly/tree/main/backend/app/api/endpoints"
click node_sync_service "https://github.com/louislefo/finly/blob/main/backend/app/services/sync_service.py"
click node_csv_parser "https://github.com/louislefo/finly/blob/main/backend/app/services/csv_parser_service.py"
click node_cleaner "https://github.com/louislefo/finly/blob/main/backend/app/services/cleaner_service.py"
click node_categorizer "https://github.com/louislefo/finly/blob/main/backend/app/services/categorizer_service.py"
click node_reconciliation "https://github.com/louislefo/finly/blob/main/backend/app/services/reconciliation_service.py"
click node_scheduler "https://github.com/louislefo/finly/blob/main/backend/app/scheduler/cron_jobs.py"
click node_database "https://github.com/louislefo/finly/blob/main/backend/app/core/database.py"
click node_security "https://github.com/louislefo/finly/blob/main/backend/app/core/security.py"
click node_models "https://github.com/louislefo/finly/tree/main/backend/app/models"
click node_woob_service "https://github.com/louislefo/finly/blob/main/backend/app/services/woob_service.py"

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_login,node_finance_ui,node_client_api,node_person toneBlue
class node_api_router,node_auth_api,node_transaction_api,node_sync_api,node_woob_api,node_budget_api,node_projects_api,node_other_api toneAmber
class node_sync_service,node_csv_parser,node_cleaner,node_categorizer,node_reconciliation,node_scheduler toneMint
class node_database,node_security,node_models toneRose
class node_woob_service,node_banks toneIndigo
```

## Components

### Web experience

- [Sign in](https://github.com/louislefo/finly/blob/main/finly-app/app/(auth)/login/page.tsx): `finly-app/app/(auth)/login/page.tsx`
- [Finance workspace](https://github.com/louislefo/finly/tree/main/finly-app/components/views): `finly-app/components/views`
- [API client](https://github.com/louislefo/finly/blob/main/finly-app/lib/api/finly-api.ts): `finly-app/lib/api/finly-api.ts`

### API workflows

- [API router](https://github.com/louislefo/finly/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/auth.py): `backend/app/api/endpoints/auth.py`
- [Transactions](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/transactions.py): `backend/app/api/endpoints/transactions.py`
- [Sync and import](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/sync.py): `backend/app/api/endpoints/sync.py`
- [Bank connections](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/woob.py): `backend/app/api/endpoints/woob.py`
- [Budgets](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/budgets.py): `backend/app/api/endpoints/budgets.py`
- [Projects and goals](https://github.com/louislefo/finly/blob/main/backend/app/api/endpoints/projects.py): `backend/app/api/endpoints/projects.py`
- [Other finance APIs](https://github.com/louislefo/finly/tree/main/backend/app/api/endpoints): `backend/app/api/endpoints`

### Finance services

- [Sync orchestration](https://github.com/louislefo/finly/blob/main/backend/app/services/sync_service.py): `backend/app/services/sync_service.py`
- [CSV parsing](https://github.com/louislefo/finly/blob/main/backend/app/services/csv_parser_service.py): `backend/app/services/csv_parser_service.py`
- [Merchant cleanup](https://github.com/louislefo/finly/blob/main/backend/app/services/cleaner_service.py): `backend/app/services/cleaner_service.py`
- [Categorization rules](https://github.com/louislefo/finly/blob/main/backend/app/services/categorizer_service.py): `backend/app/services/categorizer_service.py`
- [Reconciliation](https://github.com/louislefo/finly/blob/main/backend/app/services/reconciliation_service.py): `backend/app/services/reconciliation_service.py`
- [Scheduled sync](https://github.com/louislefo/finly/blob/main/backend/app/scheduler/cron_jobs.py): `backend/app/scheduler/cron_jobs.py`

### Identity and data

- [SQLite database](https://github.com/louislefo/finly/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Authentication and encryption](https://github.com/louislefo/finly/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Finance records](https://github.com/louislefo/finly/tree/main/backend/app/models): `backend/app/models`

### Bank integrations

- [Woob bank engine](https://github.com/louislefo/finly/blob/main/backend/app/services/woob_service.py): `backend/app/services/woob_service.py`

### Other components

- **Finance user**
- **Banking institutions**

## Connections

- Finance user → Sign in: signs in (evidence: `finly-app/app/(auth)/login/page.tsx`)
- Finance user → Finance workspace: manages finances
- Sign in → API client: uses API client
- Finance workspace → API client: requests finance data
- API client → API router: calls HTTP API
- API router → Authentication: routes auth (evidence: `backend/app/api/router.py`)
- API router → Transactions: routes transactions (evidence: `backend/app/api/router.py`)
- API router → Sync and import: routes sync (evidence: `backend/app/api/router.py`)
- API router → Bank connections: routes banking (evidence: `backend/app/api/router.py`)
- API router → Budgets: routes budgets (evidence: `backend/app/api/router.py`)
- API router → Projects and goals: routes projects (evidence: `backend/app/api/router.py`)
- API router → Other finance APIs: routes other domains (evidence: `backend/app/api/router.py`)
- Authentication → Authentication and encryption: creates tokens (evidence: `backend/app/api/endpoints/auth.py`)
- Authentication → SQLite database: reads and writes users (evidence: `backend/app/api/endpoints/auth.py`)
- Transactions → CSV parsing: parses imports (evidence: `backend/app/api/endpoints/transactions.py`)
- Transactions → Merchant cleanup: normalizes labels (evidence: `backend/app/api/endpoints/transactions.py`)
- Transactions → Categorization rules: categorizes activity (evidence: `backend/app/api/endpoints/transactions.py`)
- Transactions → Reconciliation: reconciles records (evidence: `backend/app/api/endpoints/transactions.py`)
- Transactions → SQLite database: reads and writes (evidence: `backend/app/api/endpoints/transactions.py`)
- CSV parsing → Merchant cleanup: cleans descriptions (evidence: `backend/app/services/csv_parser_service.py`)
- CSV parsing → Categorization rules: categorizes imports (evidence: `backend/app/services/csv_parser_service.py`)
- Categorization rules → Merchant cleanup: cleans merchant names (evidence: `backend/app/services/categorizer_service.py`)
- Sync and import → Sync orchestration: delegates sync (evidence: `backend/app/api/endpoints/sync.py`)
- Sync and import → Merchant cleanup: normalizes transactions (evidence: `backend/app/api/endpoints/sync.py`)
- Sync and import → Categorization rules: categorizes transactions (evidence: `backend/app/api/endpoints/sync.py`)
- Sync and import → Reconciliation: reconciles transactions (evidence: `backend/app/api/endpoints/sync.py`)
- Sync and import → SQLite database: reads and writes (evidence: `backend/app/api/endpoints/sync.py`)
- Bank connections → Woob bank engine: configures bank access (evidence: `backend/app/api/endpoints/woob.py`)
- Bank connections → Sync orchestration: starts synchronization (evidence: `backend/app/api/endpoints/woob.py`)
- Bank connections → Authentication and encryption: encrypts credentials (evidence: `backend/app/api/endpoints/woob.py`)
- Bank connections → SQLite database: stores connections (evidence: `backend/app/api/endpoints/woob.py`)
- Woob bank engine → Banking institutions: retrieves bank data
- Budgets → SQLite database: reads and writes (evidence: `backend/app/api/endpoints/budgets.py`)
- Projects and goals → SQLite database: reads and writes (evidence: `backend/app/api/endpoints/projects.py`)
- Scheduled sync → Sync orchestration: runs scheduled sync
- SQLite database → Finance records: maps records
- API router → Scheduled sync: starts scheduler