# eftikharazim/ledgerx architecture

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

- Interactive diagram: https://gitdiagram.com/eftikharazim/ledgerx
- Repository: https://github.com/eftikharazim/ledgerx

## Overview

LedgerX is a double-entry accounting API with a React client. Users authenticate, manage accounts, record or transfer funds, and inspect balances, summaries, and transaction history; they can also request and download exports. The backend combines HTTP handlers, business services, and PostgreSQL queries, while Redis-backed workers handle exports, snapshots, categorization, and outbox events. The README documents these capabilities; sampled source supports selected wiring and UI/API calls, so some subsystem links remain unverified.

Main entry points: [`ledgerx-ui/src/api/endpoints.ts`](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/api/endpoints.ts) (API client), [`internal/repo/sqlc/transactions.sql.go`](https://github.com/eftikharazim/ledgerx/blob/main/internal/repo/sqlc/transactions.sql.go) (SQL queries), [`ledgerx-ui/src/main.tsx`](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/main.tsx) (React application), [`internal/transport/http/transactions.go`](https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/transactions.go) (Account and ledger handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_ui["React application<br/>[main.tsx]"]
  node_authpages["Login and registration<br/>[Login.tsx]"]
  node_accountpages["Accounts and ledger views<br/>[AccountDetails.tsx]"]
  node_exportpage["Export screen<br/>[Exports.tsx]"]
  node_api["API client<br/>[endpoints.ts]"]
end

subgraph group_http["HTTP API"]
  node_routes["HTTP routes<br/>[router.go]"]
  node_auth["Auth endpoints<br/>[auth.go]"]
  node_handlers["Account and ledger handlers<br/>[transactions.go]"]
  node_exporthandler["Export endpoints<br/>[exports.go]"]
end

subgraph group_domain["Ledger services"]
  node_authsvc["Auth and tokens<br/>[auth.go]"]
  node_transactions["Transaction processing<br/>[transactions.go]"]
  node_balance["Balance computation<br/>[balance.go]"]
  node_summary["Account summaries<br/>[summary.go]"]
  node_categorizer["AI categorization<br/>[categorizer.go]"]
end

subgraph group_async["Background processing"]
  node_workers["Async job handlers<br/>[snapshot_worker.go]"]
  node_outbox["Outbox publisher<br/>[outbox.go]"]
  node_csv["CSV export worker<br/>[csv-export.go]"]
end

subgraph group_infra["Data and integrations"]
  node_repo["SQL queries"]
  node_postgres[("PostgreSQL")]
  node_storage["Export storage<br/>[storage.go]"]
  node_redis[("Redis")]
end

node_user(("User"))
node_claude{{"Claude API"}}
node_s3{{"S3 storage"}}

node_user -->|"uses"| node_ui
node_ui -->|"routes to"| node_authpages
node_ui -->|"routes to"| node_accountpages
node_ui -->|"routes to"| node_exportpage
node_authpages -->|"calls"| node_api
node_accountpages -->|"calls"| node_api
node_exportpage -->|"calls"| node_api
node_api -->|"requests"| node_auth
node_api -->|"requests"| node_handlers
node_api -->|"requests"| node_exporthandler
node_routes -->|"registers"| node_auth
node_handlers -->|"delegates to"| node_transactions
node_auth -->|"uses"| node_authsvc
node_transactions -->|"queries"| node_repo
node_summary -->|"queries"| node_repo
node_repo -->|"reads and writes"| node_postgres
node_handlers -.->|"serves balance"| node_balance
node_handlers -.->|"serves summary"| node_summary
node_transactions -.->|"requests suggestion"| node_categorizer
node_categorizer -.->|"optionally queries"| node_claude
node_exporthandler -.->|"enqueues jobs"| node_redis
node_workers -->|"queries"| node_repo
node_workers -.->|"handles exports"| node_csv
node_csv -->|"reads transactions"| node_repo
node_csv -.->|"writes files"| node_storage
node_storage -->|"optionally stores"| node_s3
node_outbox -->|"claims events"| node_postgres
node_outbox -->|"publishes events"| node_redis

click node_ui "https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/main.tsx"
click node_authpages "https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/Login.tsx"
click node_accountpages "https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/AccountDetails.tsx"
click node_exportpage "https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/Exports.tsx"
click node_api "https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/api/endpoints.ts"
click node_routes "https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/router.go"
click node_auth "https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/auth.go"
click node_handlers "https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/transactions.go"
click node_exporthandler "https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/exports.go"
click node_authsvc "https://github.com/eftikharazim/ledgerx/blob/main/internal/service/auth.go"
click node_transactions "https://github.com/eftikharazim/ledgerx/blob/main/internal/service/transactions.go"
click node_balance "https://github.com/eftikharazim/ledgerx/blob/main/internal/service/balance.go"
click node_summary "https://github.com/eftikharazim/ledgerx/blob/main/internal/service/summary.go"
click node_categorizer "https://github.com/eftikharazim/ledgerx/blob/main/internal/ai/categorizer.go"
click node_repo "https://github.com/eftikharazim/ledgerx/blob/main/internal/repo/sqlc/transactions.sql.go"
click node_workers "https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/snapshot_worker.go"
click node_outbox "https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/outbox.go"
click node_storage "https://github.com/eftikharazim/ledgerx/blob/main/internal/storage/storage.go"
click node_csv "https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/csv-export.go"

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_ui,node_authpages,node_accountpages,node_exportpage,node_api,node_user toneBlue
class node_routes,node_auth,node_handlers,node_exporthandler,node_s3 toneAmber
class node_authsvc,node_transactions,node_balance,node_summary,node_categorizer,node_claude toneMint
class node_workers,node_outbox,node_csv toneRose
class node_repo,node_postgres,node_storage,node_redis toneIndigo
```

## Components

### Web client

- [React application](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/main.tsx): `ledgerx-ui/src/main.tsx`
- [Login and registration](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/Login.tsx): `ledgerx-ui/src/pages/Login.tsx`
- [Accounts and ledger views](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/AccountDetails.tsx): `ledgerx-ui/src/pages/AccountDetails.tsx`
- [Export screen](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/pages/Exports.tsx): `ledgerx-ui/src/pages/Exports.tsx`
- [API client](https://github.com/eftikharazim/ledgerx/blob/main/ledgerx-ui/src/api/endpoints.ts): `ledgerx-ui/src/api/endpoints.ts`

### HTTP API

- [HTTP routes](https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/router.go): `internal/transport/http/router.go`
- [Auth endpoints](https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/auth.go): `internal/transport/http/auth.go`
- [Account and ledger handlers](https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/transactions.go): `internal/transport/http/transactions.go`
- [Export endpoints](https://github.com/eftikharazim/ledgerx/blob/main/internal/transport/http/exports.go): `internal/transport/http/exports.go`

### Ledger services

- [Auth and tokens](https://github.com/eftikharazim/ledgerx/blob/main/internal/service/auth.go): `internal/service/auth.go`
- [Transaction processing](https://github.com/eftikharazim/ledgerx/blob/main/internal/service/transactions.go): `internal/service/transactions.go`
- [Balance computation](https://github.com/eftikharazim/ledgerx/blob/main/internal/service/balance.go): `internal/service/balance.go`
- [Account summaries](https://github.com/eftikharazim/ledgerx/blob/main/internal/service/summary.go): `internal/service/summary.go`
- [AI categorization](https://github.com/eftikharazim/ledgerx/blob/main/internal/ai/categorizer.go): `internal/ai/categorizer.go`

### Background processing

- [Async job handlers](https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/snapshot_worker.go): `internal/worker/snapshot_worker.go`
- [Outbox publisher](https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/outbox.go): `internal/worker/outbox.go`
- [CSV export worker](https://github.com/eftikharazim/ledgerx/blob/main/internal/worker/csv-export.go): `internal/worker/csv-export.go`

### Data and integrations

- [SQL queries](https://github.com/eftikharazim/ledgerx/blob/main/internal/repo/sqlc/transactions.sql.go): `internal/repo/sqlc/transactions.sql.go`
- **PostgreSQL**
- [Export storage](https://github.com/eftikharazim/ledgerx/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- **Redis**

### Other components

- **User**
- **Claude API**
- **S3 storage**

## Connections

- User → React application: uses
- React application → Login and registration: routes to
- React application → Accounts and ledger views: routes to
- React application → Export screen: routes to
- Login and registration → API client: calls (evidence: `ledgerx-ui/src/pages/Login.tsx`)
- Accounts and ledger views → API client: calls (evidence: `ledgerx-ui/src/pages/AccountDetails.tsx`)
- Export screen → API client: calls (evidence: `ledgerx-ui/src/pages/Exports.tsx`)
- API client → Auth endpoints: requests
- API client → Account and ledger handlers: requests
- API client → Export endpoints: requests
- HTTP routes → Auth endpoints: registers (evidence: `internal/transport/http/auth.go`)
- Account and ledger handlers → Transaction processing: delegates to (evidence: `internal/transport/http/transactions.go`)
- Auth endpoints → Auth and tokens: uses (evidence: `internal/transport/http/auth.go`)
- Transaction processing → SQL queries: queries (evidence: `internal/service/transactions.go`)
- Account summaries → SQL queries: queries (evidence: `internal/service/summary.go`)
- SQL queries → PostgreSQL: reads and writes
- Account and ledger handlers → Balance computation: serves balance
- Account and ledger handlers → Account summaries: serves summary
- Transaction processing → AI categorization: requests suggestion
- AI categorization → Claude API: optionally queries
- Export endpoints → Redis: enqueues jobs
- Async job handlers → SQL queries: queries (evidence: `internal/worker/snapshot_worker.go`)
- Async job handlers → CSV export worker: handles exports
- CSV export worker → SQL queries: reads transactions (evidence: `internal/worker/csv-export.go`)
- CSV export worker → Export storage: writes files
- Export storage → S3 storage: optionally stores
- Outbox publisher → PostgreSQL: claims events
- Outbox publisher → Redis: publishes events