# csantiagu/ledgerlite architecture

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

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

## Overview

LedgerLite is a self-hosted bookkeeping app for small UK businesses. Owners and accountants use the browser app to manage invoices, bills, bank imports and reconciliation, then review reports and export VAT-quarter or year-end records. The Worker API handles requests and persists bookkeeping data in D1, with R2 for documents and backups. The graph preserves major documented features, but several routes and services are unsampled; their detailed links are omitted where the excerpts do not establish them.

Main entry points: [`worker/src/index.ts`](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/index.ts) (Request router), [`worker/src/routes/invoices.ts`](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/invoices.ts) (Invoices), [`frontend/src/lib/api.ts`](https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/lib/api.ts) (API client), [`worker/src/routes/reports.ts`](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/reports.ts) (Reports and exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Browser app"]
  node_webapp["Bookkeeping UI"]
  node_txnreview["Bank review UI<br/>[ReviewTab.tsx]"]
  node_invoiceui["Invoice UI<br/>[page.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_api["Worker API"]
  node_worker["Request router<br/>[index.ts]"]
  node_authroutes["Sign-in and setup<br/>[auth.ts]"]
end

subgraph group_bookkeeping["Bookkeeping workflows"]
  node_invoices["Invoices<br/>[invoices.ts]"]
  node_bills["Supplier bills<br/>[bills.ts]"]
  node_bankimports["Statement imports<br/>[bankImports.ts]"]
  node_transactions["Bank transactions<br/>[transactions.ts]"]
  node_matching["Reconciliation"]
  node_bankreview["Posting payments<br/>[bankReview.ts]"]
  node_reports["Reports and exports<br/>[reports.ts]"]
  node_accountantexport["Accountant exports"]
  node_yearend["Year-end packs<br/>[yearEndExport.ts]"]
end

subgraph group_platform["Security and storage"]
  node_authmw["Session security<br/>[auth.ts]"]
  node_rbac["Role permissions<br/>[rbac.ts]"]
  node_audit["Audit history<br/>[audit.ts]"]
  node_files["Document handling<br/>[files.ts]"]
  node_backup["Backups<br/>[backup.ts]"]
  node_d1[("D1 database")]
  node_r2[("R2 storage")]
end

node_browser(("Owner / accountant"))

node_browser -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_apiclient
node_txnreview -->|"submits matches"| node_apiclient
node_invoiceui -.->|"manages invoice"| node_apiclient
node_apiclient -->|"calls API"| node_worker
node_worker -->|"routes requests"| node_authroutes
node_worker -->|"routes requests"| node_invoices
node_worker -->|"routes requests"| node_bills
node_worker -->|"routes requests"| node_bankimports
node_worker -->|"routes requests"| node_transactions
node_worker -->|"routes requests"| node_matching
node_worker -->|"routes requests"| node_reports
node_worker -->|"checks configuration"| node_authmw
node_authroutes -->|"issues sessions"| node_authmw
node_invoices -->|"records changes"| node_audit
node_invoices -->|"checks uploads"| node_files
node_invoices -->|"stores PDFs"| node_r2
node_matching -.->|"posts matches"| node_bankreview
node_bankimports -.->|"imports lines"| node_transactions
node_worker -->|"reads and writes"| node_d1
node_worker -->|"stores files"| node_r2
node_reports -.->|"exports records"| node_accountantexport
node_reports -.->|"builds year-end pack"| node_yearend
node_backup -->|"backs up database"| node_d1
node_backup -->|"backs up files"| node_r2

click node_webapp "https://github.com/csantiagu/ledgerlite/tree/main/frontend/src/app"
click node_txnreview "https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/app/transactions/ReviewTab.tsx"
click node_invoiceui "https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/app/invoices/view/page.tsx"
click node_apiclient "https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/lib/api.ts"
click node_worker "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/index.ts"
click node_authroutes "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/auth.ts"
click node_invoices "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/invoices.ts"
click node_bills "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/bills.ts"
click node_bankimports "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/bankImports.ts"
click node_transactions "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/transactions.ts"
click node_matching "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/transactionMatches.ts"
click node_bankreview "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/bankReview.ts"
click node_reports "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/reports.ts"
click node_accountantexport "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/accountantExport.ts"
click node_yearend "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/yearEndExport.ts"
click node_authmw "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/auth.ts"
click node_rbac "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/rbac.ts"
click node_audit "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/audit.ts"
click node_files "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/files.ts"
click node_backup "https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/backup.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_webapp,node_txnreview,node_invoiceui,node_apiclient toneBlue
class node_worker,node_authroutes toneAmber
class node_invoices,node_bills,node_bankimports,node_transactions,node_matching,node_bankreview,node_reports,node_accountantexport,node_yearend toneMint
class node_authmw,node_rbac,node_audit,node_files,node_backup,node_d1,node_r2 toneRose
class node_browser toneIndigo
```

## Components

### Browser app

- [Bookkeeping UI](https://github.com/csantiagu/ledgerlite/tree/main/frontend/src/app): `frontend/src/app`
- [Bank review UI](https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/app/transactions/ReviewTab.tsx): `frontend/src/app/transactions/ReviewTab.tsx`
- [Invoice UI](https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/app/invoices/view/page.tsx): `frontend/src/app/invoices/view/page.tsx`
- [API client](https://github.com/csantiagu/ledgerlite/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Worker API

- [Request router](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/index.ts): `worker/src/index.ts`
- [Sign-in and setup](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/auth.ts): `worker/src/routes/auth.ts`

### Bookkeeping workflows

- [Invoices](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/invoices.ts): `worker/src/routes/invoices.ts`
- [Supplier bills](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/bills.ts): `worker/src/routes/bills.ts`
- [Statement imports](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/bankImports.ts): `worker/src/routes/bankImports.ts`
- [Bank transactions](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/transactions.ts): `worker/src/routes/transactions.ts`
- [Reconciliation](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/transactionMatches.ts): `worker/src/routes/transactionMatches.ts`
- [Posting payments](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/bankReview.ts): `worker/src/services/bankReview.ts`
- [Reports and exports](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/routes/reports.ts): `worker/src/routes/reports.ts`
- [Accountant exports](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/accountantExport.ts): `worker/src/services/accountantExport.ts`
- [Year-end packs](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/yearEndExport.ts): `worker/src/services/yearEndExport.ts`

### Security and storage

- [Session security](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/auth.ts): `worker/src/middleware/auth.ts`
- [Role permissions](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/rbac.ts): `worker/src/middleware/rbac.ts`
- [Audit history](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/middleware/audit.ts): `worker/src/middleware/audit.ts`
- [Document handling](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/files.ts): `worker/src/services/files.ts`
- [Backups](https://github.com/csantiagu/ledgerlite/blob/main/worker/src/services/backup.ts): `worker/src/services/backup.ts`
- **D1 database**
- **R2 storage**

### Other components

- **Owner / accountant**

## Connections

- Owner / accountant → Bookkeeping UI: uses (evidence: `README.md`)
- Bookkeeping UI → API client: requests data
- Bank review UI → API client: submits matches (evidence: `frontend/src/app/transactions/ReviewTab.tsx`)
- Invoice UI → API client: manages invoice
- API client → Request router: calls API (evidence: `README.md`)
- Request router → Sign-in and setup: routes requests (evidence: `worker/src/index.ts`)
- Request router → Invoices: routes requests (evidence: `worker/src/index.ts`)
- Request router → Supplier bills: routes requests (evidence: `worker/src/index.ts`)
- Request router → Statement imports: routes requests (evidence: `worker/src/index.ts`)
- Request router → Bank transactions: routes requests (evidence: `worker/src/index.ts`)
- Request router → Reconciliation: routes requests (evidence: `worker/src/index.ts`)
- Request router → Reports and exports: routes requests (evidence: `worker/src/index.ts`)
- Request router → Session security: checks configuration (evidence: `worker/src/index.ts`)
- Sign-in and setup → Session security: issues sessions (evidence: `worker/src/routes/auth.ts`)
- Invoices → Audit history: records changes (evidence: `worker/src/routes/invoices.ts`)
- Invoices → Document handling: checks uploads (evidence: `worker/src/routes/invoices.ts`)
- Invoices → R2 storage: stores PDFs (evidence: `worker/src/routes/invoices.ts`)
- Reconciliation → Posting payments: posts matches
- Statement imports → Bank transactions: imports lines
- Request router → D1 database: reads and writes (evidence: `README.md`)
- Request router → R2 storage: stores files (evidence: `README.md`)
- Reports and exports → Accountant exports: exports records
- Reports and exports → Year-end packs: builds year-end pack
- Backups → D1 database: backs up database (evidence: `README.md`)
- Backups → R2 storage: backs up files (evidence: `README.md`)