# jackson254365/lumen-fintech-system architecture

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

- Interactive diagram: https://gitdiagram.com/jackson254365/lumen-fintech-system
- Repository: https://github.com/jackson254365/lumen-fintech-system

## Overview

Lumen is a local-first finance platform whose primary documented runtime is the Rust/Axum server: users submit finance operations through the API, which routes them to accounting, payments, statement ingestion, or research and persists state in SQLite. The Rust ledger and its audit chain form a key internal layer. The tree also contains a Node/Express implementation; it is represented as a parallel legacy backend, not assumed to be called by Rust. README capability descriptions support major features whose implementation details were not sampled; unsampled connections are omitted.

Main entry points: [`src/routes/mod.rs`](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/routes/mod.rs) (API handlers), [`src/statement_engine/mod.rs`](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/mod.rs) (Statement ingestion), [`src/main.rs`](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/main.rs) (Axum server), [`src/ledger/core.rs`](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/core.rs) (Double-entry ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_web_client["Web client<br/>[app.js]"]
  node_research_sdk["Research SDK<br/>[research_client.py]"]
end

subgraph group_rust_api["Rust API runtime"]
  node_rust_server["Axum server<br/>[main.rs]"]
  node_api_routes["API handlers<br/>[mod.rs]"]
  node_middleware["Request middleware"]
end

subgraph group_accounting["Accounting core"]
  node_ledger["Double-entry ledger<br/>[core.rs]"]
  node_audit["Audit chain<br/>[audit_chain.rs]"]
  node_accounts["Chart of accounts"]
end

subgraph group_finance_features["Finance capabilities"]
  node_statements["Statement ingestion<br/>[mod.rs]"]
  node_statement_parser["Statement parser<br/>[parser.rs]"]
  node_statement_dedup["Statement deduplicator<br/>[deduplicator.rs]"]
  node_statement_categorizer["Transaction categorizer<br/>[categorizer.rs]"]
  node_payment_rails["Payment rails"]
  node_research["Finance research"]
end

subgraph group_persistence["Persistence"]
  node_db[("SQLite database<br/>[db.rs]")]
end

subgraph group_legacy["Legacy Node backend"]
  node_legacy_server["Express server<br/>[index.js]"]
  node_legacy_db[("Node SQLite adapter<br/>[db.js]")]
  node_legacy_ledger["Node ledger<br/>[ledger-core.js]"]
  node_legacy_rails["Node payment routes<br/>[rails.js]"]
  node_legacy_crypto["Crypto rail<br/>[crypto.js]"]
end

node_user(("Finance user"))

node_user -.->|"uses"| node_web_client
node_user -->|"requests"| node_api_routes
node_web_client -.->|"calls API"| node_api_routes
node_research_sdk -.->|"queries research"| node_api_routes
node_rust_server -->|"initializes"| node_db
node_rust_server -->|"creates router"| node_api_routes
node_rust_server -->|"applies"| node_middleware
node_api_routes -->|"queries and writes"| node_db
node_api_routes -.->|"posts entries"| node_ledger
node_ledger -->|"hashes entries"| node_audit
node_api_routes -->|"builds trial balance"| node_accounts
node_api_routes -.->|"imports statements"| node_statements
node_statements -->|"parses"| node_statement_parser
node_statements -->|"deduplicates"| node_statement_dedup
node_statements -->|"categorizes"| node_statement_categorizer
node_api_routes -.->|"dispatches payments"| node_payment_rails
node_payment_rails -.->|"records transactions"| node_ledger
node_api_routes -.->|"serves analysis"| node_research
node_legacy_server -->|"initializes"| node_legacy_db
node_legacy_server -->|"mounts routes"| node_legacy_rails
node_legacy_rails -->|"dispatches to"| node_legacy_crypto
node_legacy_crypto -.->|"posts entries"| node_legacy_ledger
node_legacy_ledger -->|"reads and writes"| node_legacy_db

click node_web_client "https://github.com/jackson254365/lumen-fintech-system/blob/main/app.js"
click node_research_sdk "https://github.com/jackson254365/lumen-fintech-system/blob/main/sdk/research_client.py"
click node_rust_server "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/main.rs"
click node_api_routes "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/routes/mod.rs"
click node_middleware "https://github.com/jackson254365/lumen-fintech-system/tree/main/src/middleware"
click node_ledger "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/core.rs"
click node_audit "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/audit_chain.rs"
click node_accounts "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/chart_of_accounts.rs"
click node_db "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/db.rs"
click node_statements "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/mod.rs"
click node_statement_parser "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/parser.rs"
click node_statement_dedup "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/deduplicator.rs"
click node_statement_categorizer "https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/categorizer.rs"
click node_payment_rails "https://github.com/jackson254365/lumen-fintech-system/tree/main/src/rails"
click node_research "https://github.com/jackson254365/lumen-fintech-system/tree/main/src/research_engine"
click node_legacy_server "https://github.com/jackson254365/lumen-fintech-system/blob/main/server/index.js"
click node_legacy_db "https://github.com/jackson254365/lumen-fintech-system/blob/main/server/db.js"
click node_legacy_ledger "https://github.com/jackson254365/lumen-fintech-system/blob/main/server/ledger/ledger-core.js"
click node_legacy_rails "https://github.com/jackson254365/lumen-fintech-system/blob/main/server/routes/rails.js"
click node_legacy_crypto "https://github.com/jackson254365/lumen-fintech-system/blob/main/server/rails/crypto.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_web_client,node_research_sdk,node_user toneBlue
class node_rust_server,node_api_routes,node_middleware toneAmber
class node_ledger,node_audit,node_accounts toneMint
class node_statements,node_statement_parser,node_statement_dedup,node_statement_categorizer,node_payment_rails,node_research toneRose
class node_db toneIndigo
class node_legacy_server,node_legacy_db,node_legacy_ledger,node_legacy_rails,node_legacy_crypto toneTeal
```

## Components

### User interface

- [Web client](https://github.com/jackson254365/lumen-fintech-system/blob/main/app.js): `app.js`
- [Research SDK](https://github.com/jackson254365/lumen-fintech-system/blob/main/sdk/research_client.py): `sdk/research_client.py`

### Rust API runtime

- [Axum server](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/main.rs): `src/main.rs`
- [API handlers](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/routes/mod.rs): `src/routes/mod.rs`
- [Request middleware](https://github.com/jackson254365/lumen-fintech-system/tree/main/src/middleware): `src/middleware`

### Accounting core

- [Double-entry ledger](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/core.rs): `src/ledger/core.rs`
- [Audit chain](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/audit_chain.rs): `src/ledger/audit_chain.rs`
- [Chart of accounts](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/ledger/chart_of_accounts.rs): `src/ledger/chart_of_accounts.rs`

### Finance capabilities

- [Statement ingestion](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/mod.rs): `src/statement_engine/mod.rs`
- [Statement parser](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/parser.rs): `src/statement_engine/parser.rs`
- [Statement deduplicator](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/deduplicator.rs): `src/statement_engine/deduplicator.rs`
- [Transaction categorizer](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/statement_engine/categorizer.rs): `src/statement_engine/categorizer.rs`
- [Payment rails](https://github.com/jackson254365/lumen-fintech-system/tree/main/src/rails): `src/rails`
- [Finance research](https://github.com/jackson254365/lumen-fintech-system/tree/main/src/research_engine): `src/research_engine`

### Persistence

- [SQLite database](https://github.com/jackson254365/lumen-fintech-system/blob/main/src/db.rs): `src/db.rs`

### Legacy Node backend

- [Express server](https://github.com/jackson254365/lumen-fintech-system/blob/main/server/index.js): `server/index.js`
- [Node SQLite adapter](https://github.com/jackson254365/lumen-fintech-system/blob/main/server/db.js): `server/db.js`
- [Node ledger](https://github.com/jackson254365/lumen-fintech-system/blob/main/server/ledger/ledger-core.js): `server/ledger/ledger-core.js`
- [Node payment routes](https://github.com/jackson254365/lumen-fintech-system/blob/main/server/routes/rails.js): `server/routes/rails.js`
- [Crypto rail](https://github.com/jackson254365/lumen-fintech-system/blob/main/server/rails/crypto.js): `server/rails/crypto.js`

### Other components

- **Finance user**

## Connections

- Finance user → Web client: uses (evidence: `README.md`)
- Finance user → API handlers: requests (evidence: `README.md`)
- Web client → API handlers: calls API
- Research SDK → API handlers: queries research
- Axum server → SQLite database: initializes (evidence: `src/main.rs`)
- Axum server → API handlers: creates router (evidence: `src/main.rs`)
- Axum server → Request middleware: applies (evidence: `src/main.rs`)
- API handlers → SQLite database: queries and writes (evidence: `src/routes/mod.rs`)
- API handlers → Double-entry ledger: posts entries (evidence: `README.md`)
- Double-entry ledger → Audit chain: hashes entries (evidence: `src/ledger/core.rs`)
- API handlers → Chart of accounts: builds trial balance (evidence: `src/routes/mod.rs`)
- API handlers → Statement ingestion: imports statements (evidence: `README.md`)
- Statement ingestion → Statement parser: parses (evidence: `src/statement_engine/mod.rs`)
- Statement ingestion → Statement deduplicator: deduplicates (evidence: `src/statement_engine/mod.rs`)
- Statement ingestion → Transaction categorizer: categorizes (evidence: `src/statement_engine/mod.rs`)
- API handlers → Payment rails: dispatches payments (evidence: `README.md`)
- Payment rails → Double-entry ledger: records transactions (evidence: `README.md`)
- API handlers → Finance research: serves analysis (evidence: `README.md`)
- Express server → Node SQLite adapter: initializes (evidence: `server/index.js`)
- Express server → Node payment routes: mounts routes (evidence: `server/index.js`)
- Node payment routes → Crypto rail: dispatches to (evidence: `server/routes/rails.js`)
- Crypto rail → Node ledger: posts entries (evidence: `server/rails/crypto.js`)
- Node ledger → Node SQLite adapter: reads and writes (evidence: `server/ledger/ledger-core.js`)
