# xander-murray/ledge architecture

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

- Interactive diagram: https://gitdiagram.com/xander-murray/ledge
- Repository: https://github.com/xander-murray/ledge

## Overview

Ledge is a read-only, event-driven bank-transaction reconciliation pipeline. Its main workflow accepts a normalized webhook, durably records it, processes it under a lease, fetches cursor-based Plaid updates, and atomically commits reconciled ledger history. Separate capabilities provide Plaid Sandbox onboarding, user-scoped account/transaction/sync-status reads, and local readiness checks. The README describes AWS SQS/Lambda delivery as a planned milestone; those adapters are shown as optional infrastructure, not as an established automatic dispatch path. Some internal relationships are supported by the SOURCE INDEX or README rather than full source excerpts.

Main entry points: [`src/persistence/models.py`](https://github.com/xander-murray/ledge/blob/main/src/persistence/models.py) (Persistence models), [`src/application/synchronization.py`](https://github.com/xander-murray/ledge/blob/main/src/application/synchronization.py) (Cursor synchronization), [`src/api/webhooks.py`](https://github.com/xander-murray/ledge/blob/main/src/api/webhooks.py) (Webhook intake), [`src/application/event_processing.py`](https://github.com/xander-murray/ledge/blob/main/src/application/event_processing.py) (Leased event processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["API and intake"]
  node_api["FastAPI app<br/>[app.py]"]
  node_webhook["Webhook intake<br/>[webhooks.py]"]
  node_eventqueue["Event queue port<br/>[event_queue.py]"]
end

subgraph group_processing["Event processing"]
  node_worker["Leased event processor"]
  node_sync["Cursor synchronization<br/>[synchronization.py]"]
  node_sqs["SQS adapter<br/>[sqs.py]"]
  node_lambda["Lambda runtime<br/>[lambda_runtime.py]"]
end

subgraph group_accounting["Ledger and persistence"]
  node_inbox[("Durable event inbox<br/>[inbound_events.py]")]
  node_ledger["Ledger rules<br/>[ledger.py]"]
  node_domainmodels["Accounting models<br/>[models.py]"]
  node_repository["Ledger repository<br/>[repository.py]"]
  node_dbmodels["Persistence models<br/>[models.py]"]
  node_postgres[("PostgreSQL<br/>[database.py]")]
end

subgraph group_providers["Provider integration"]
  node_providerport["Transaction provider port<br/>[base.py]"]
  node_plaid["Plaid transaction adapter<br/>[plaid.py]"]
  node_plaidservice["Plaid connection service"]
  node_sandbox["Plaid Sandbox client<br/>[plaid_sandbox.py]"]
end

subgraph group_operations["Reads and operations"]
  node_readapi["User-scoped read APIs<br/>[accounts.py]"]
  node_dashboard["Dashboard views<br/>[dashboard.py]"]
  node_syncstatus["Sync status API<br/>[sync_status.py]"]
  node_health["Readiness API<br/>[health.py]"]
  node_sandboxcommands["Sandbox CLI<br/>[plaid_sandbox.py]"]
  node_synccommands["Sync CLI<br/>[plaid_sync.py]"]
end

node_consumer(("Sandbox consumer"))
node_plaidcloud{{"Plaid Sandbox"}}

node_consumer -->|"uses"| node_api
node_api -->|"routes"| node_webhook
node_webhook -->|"persists event"| node_inbox
node_webhook -->|"publishes identity"| node_eventqueue
node_eventqueue -->|"adapts publishing"| node_sqs
node_sqs -.->|"delivers message"| node_lambda
node_lambda -.->|"invokes"| node_worker
node_worker -->|"claims and finalizes"| node_inbox
node_worker -->|"runs synchronization"| node_sync
node_sync -->|"fetches updates"| node_providerport
node_plaid -->|"requests transaction pages"| node_plaidcloud
node_sync -->|"reconciles changes"| node_ledger
node_sync -->|"persists batch"| node_repository
node_repository -->|"applies ledger rules"| node_ledger
node_ledger -->|"creates journal entries"| node_domainmodels
node_repository -->|"maps records"| node_dbmodels
node_dbmodels -->|"stores records"| node_postgres
node_plaidservice -->|"creates Item and lists accounts"| node_sandbox
node_sandbox -->|"calls Sandbox API"| node_plaidcloud
node_plaidservice -->|"records account mappings"| node_dbmodels
node_consumer -->|"requests accounts and transactions"| node_readapi
node_consumer -->|"checks sync state"| node_syncstatus
node_consumer -->|"requests dashboard"| node_dashboard
node_consumer -->|"checks readiness"| node_health
node_readapi -->|"queries user data"| node_dbmodels
node_dashboard -->|"queries read views"| node_dbmodels
node_syncstatus -->|"queries sync state"| node_dbmodels
node_health -->|"checks readiness"| node_postgres
node_sandboxcommands -->|"bootstraps connection"| node_plaidservice
node_synccommands -->|"runs synchronization"| node_sync
node_synccommands -->|"configures provider"| node_plaid

click node_api "https://github.com/xander-murray/ledge/blob/main/src/api/app.py"
click node_webhook "https://github.com/xander-murray/ledge/blob/main/src/api/webhooks.py"
click node_eventqueue "https://github.com/xander-murray/ledge/blob/main/src/application/event_queue.py"
click node_inbox "https://github.com/xander-murray/ledge/blob/main/src/persistence/inbound_events.py"
click node_worker "https://github.com/xander-murray/ledge/blob/main/src/application/event_processing.py"
click node_sync "https://github.com/xander-murray/ledge/blob/main/src/application/synchronization.py"
click node_providerport "https://github.com/xander-murray/ledge/blob/main/src/providers/base.py"
click node_plaid "https://github.com/xander-murray/ledge/blob/main/src/providers/plaid.py"
click node_plaidservice "https://github.com/xander-murray/ledge/blob/main/src/application/plaid_connection.py"
click node_sandbox "https://github.com/xander-murray/ledge/blob/main/src/providers/plaid_sandbox.py"
click node_ledger "https://github.com/xander-murray/ledge/blob/main/src/domain/ledger.py"
click node_domainmodels "https://github.com/xander-murray/ledge/blob/main/src/domain/models.py"
click node_repository "https://github.com/xander-murray/ledge/blob/main/src/persistence/repository.py"
click node_dbmodels "https://github.com/xander-murray/ledge/blob/main/src/persistence/models.py"
click node_postgres "https://github.com/xander-murray/ledge/blob/main/src/persistence/database.py"
click node_readapi "https://github.com/xander-murray/ledge/blob/main/src/api/accounts.py"
click node_dashboard "https://github.com/xander-murray/ledge/blob/main/src/api/dashboard.py"
click node_syncstatus "https://github.com/xander-murray/ledge/blob/main/src/api/sync_status.py"
click node_health "https://github.com/xander-murray/ledge/blob/main/src/api/health.py"
click node_sandboxcommands "https://github.com/xander-murray/ledge/blob/main/src/commands/plaid_sandbox.py"
click node_synccommands "https://github.com/xander-murray/ledge/blob/main/src/commands/plaid_sync.py"
click node_sqs "https://github.com/xander-murray/ledge/blob/main/src/infrastructure/sqs.py"
click node_lambda "https://github.com/xander-murray/ledge/blob/main/src/infrastructure/lambda_runtime.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_api,node_webhook,node_eventqueue toneBlue
class node_worker,node_sync,node_sqs,node_lambda toneAmber
class node_inbox,node_ledger,node_domainmodels,node_repository,node_dbmodels,node_postgres toneMint
class node_providerport,node_plaid,node_plaidservice,node_sandbox toneRose
class node_readapi,node_dashboard,node_syncstatus,node_health,node_sandboxcommands,node_synccommands,node_consumer,node_plaidcloud toneIndigo
```

## Components

### API and intake

- [FastAPI app](https://github.com/xander-murray/ledge/blob/main/src/api/app.py): `src/api/app.py`
- [Webhook intake](https://github.com/xander-murray/ledge/blob/main/src/api/webhooks.py): `src/api/webhooks.py`
- [Event queue port](https://github.com/xander-murray/ledge/blob/main/src/application/event_queue.py): `src/application/event_queue.py`

### Event processing

- [Leased event processor](https://github.com/xander-murray/ledge/blob/main/src/application/event_processing.py): `src/application/event_processing.py`
- [Cursor synchronization](https://github.com/xander-murray/ledge/blob/main/src/application/synchronization.py): `src/application/synchronization.py`
- [SQS adapter](https://github.com/xander-murray/ledge/blob/main/src/infrastructure/sqs.py): `src/infrastructure/sqs.py`
- [Lambda runtime](https://github.com/xander-murray/ledge/blob/main/src/infrastructure/lambda_runtime.py): `src/infrastructure/lambda_runtime.py`

### Ledger and persistence

- [Durable event inbox](https://github.com/xander-murray/ledge/blob/main/src/persistence/inbound_events.py): `src/persistence/inbound_events.py`
- [Ledger rules](https://github.com/xander-murray/ledge/blob/main/src/domain/ledger.py): `src/domain/ledger.py`
- [Accounting models](https://github.com/xander-murray/ledge/blob/main/src/domain/models.py): `src/domain/models.py`
- [Ledger repository](https://github.com/xander-murray/ledge/blob/main/src/persistence/repository.py): `src/persistence/repository.py`
- [Persistence models](https://github.com/xander-murray/ledge/blob/main/src/persistence/models.py): `src/persistence/models.py`
- [PostgreSQL](https://github.com/xander-murray/ledge/blob/main/src/persistence/database.py): `src/persistence/database.py`

### Provider integration

- [Transaction provider port](https://github.com/xander-murray/ledge/blob/main/src/providers/base.py): `src/providers/base.py`
- [Plaid transaction adapter](https://github.com/xander-murray/ledge/blob/main/src/providers/plaid.py): `src/providers/plaid.py`
- [Plaid connection service](https://github.com/xander-murray/ledge/blob/main/src/application/plaid_connection.py): `src/application/plaid_connection.py`
- [Plaid Sandbox client](https://github.com/xander-murray/ledge/blob/main/src/providers/plaid_sandbox.py): `src/providers/plaid_sandbox.py`

### Reads and operations

- [User-scoped read APIs](https://github.com/xander-murray/ledge/blob/main/src/api/accounts.py): `src/api/accounts.py`
- [Dashboard views](https://github.com/xander-murray/ledge/blob/main/src/api/dashboard.py): `src/api/dashboard.py`
- [Sync status API](https://github.com/xander-murray/ledge/blob/main/src/api/sync_status.py): `src/api/sync_status.py`
- [Readiness API](https://github.com/xander-murray/ledge/blob/main/src/api/health.py): `src/api/health.py`
- [Sandbox CLI](https://github.com/xander-murray/ledge/blob/main/src/commands/plaid_sandbox.py): `src/commands/plaid_sandbox.py`
- [Sync CLI](https://github.com/xander-murray/ledge/blob/main/src/commands/plaid_sync.py): `src/commands/plaid_sync.py`

### Other components

- **Sandbox consumer**
- **Plaid Sandbox**

## Connections

- Sandbox consumer → FastAPI app: uses (evidence: `README.md`)
- FastAPI app → Webhook intake: routes (evidence: `src/api/app.py`)
- Webhook intake → Durable event inbox: persists event (evidence: `README.md`)
- Webhook intake → Event queue port: publishes identity (evidence: `src/api/webhooks.py`)
- Event queue port → SQS adapter: adapts publishing (evidence: `src/infrastructure/sqs.py`)
- SQS adapter → Lambda runtime: delivers message
- Lambda runtime → Leased event processor: invokes (evidence: `src/infrastructure/lambda_runtime.py`)
- Leased event processor → Durable event inbox: claims and finalizes (evidence: `README.md`)
- Leased event processor → Cursor synchronization: runs synchronization (evidence: `src/application/event_processing.py`)
- Cursor synchronization → Transaction provider port: fetches updates (evidence: `src/application/synchronization.py`)
- Plaid transaction adapter → Plaid Sandbox: requests transaction pages (evidence: `src/providers/plaid.py`)
- Cursor synchronization → Ledger rules: reconciles changes (evidence: `src/application/synchronization.py`)
- Cursor synchronization → Ledger repository: persists batch (evidence: `src/application/synchronization.py`)
- Ledger repository → Ledger rules: applies ledger rules (evidence: `src/persistence/repository.py`)
- Ledger rules → Accounting models: creates journal entries (evidence: `src/domain/ledger.py`)
- Ledger repository → Persistence models: maps records (evidence: `src/persistence/repository.py`)
- Persistence models → PostgreSQL: stores records (evidence: `README.md`)
- Plaid connection service → Plaid Sandbox client: creates Item and lists accounts (evidence: `src/application/plaid_connection.py`)
- Plaid Sandbox client → Plaid Sandbox: calls Sandbox API (evidence: `src/providers/plaid_sandbox.py`)
- Plaid connection service → Persistence models: records account mappings (evidence: `src/application/plaid_connection.py`)
- Sandbox consumer → User-scoped read APIs: requests accounts and transactions (evidence: `README.md`)
- Sandbox consumer → Sync status API: checks sync state (evidence: `README.md`)
- Sandbox consumer → Dashboard views: requests dashboard
- Sandbox consumer → Readiness API: checks readiness (evidence: `README.md`)
- User-scoped read APIs → Persistence models: queries user data (evidence: `src/api/accounts.py`)
- Dashboard views → Persistence models: queries read views (evidence: `src/api/dashboard.py`)
- Sync status API → Persistence models: queries sync state (evidence: `src/api/sync_status.py`)
- Readiness API → PostgreSQL: checks readiness (evidence: `README.md`)
- Sandbox CLI → Plaid connection service: bootstraps connection (evidence: `src/commands/plaid_sandbox.py`)
- Sync CLI → Cursor synchronization: runs synchronization (evidence: `src/commands/plaid_sync.py`)
- Sync CLI → Plaid transaction adapter: configures provider (evidence: `src/commands/plaid_sync.py`)
