How xander-murray/ledge works
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: models.py Persistence models · synchronization.py Cursor synchronization · webhooks.py Webhook intake · event_processing.py Leased event processor
Components 25
API and intake
- FastAPI app
src/api/app.py - Webhook intake
src/api/webhooks.py - Event queue port
src/application/event_queue.py
Event processing
- Leased event processor
src/application/event_processing.py - Cursor synchronization
src/application/synchronization.py - SQS adapter
src/infrastructure/sqs.py - Lambda runtime
src/infrastructure/lambda_runtime.py
Ledger and persistence
- Durable event inbox
src/persistence/inbound_events.py - Ledger rules
src/domain/ledger.py - Accounting models
src/domain/models.py - Ledger repository
src/persistence/repository.py - Persistence models
src/persistence/models.py - PostgreSQL
src/persistence/database.py
Provider integration
- Transaction provider port
src/providers/base.py - Plaid transaction adapter
src/providers/plaid.py - Plaid connection service
src/application/plaid_connection.py - Plaid Sandbox client
src/providers/plaid_sandbox.py
Reads and operations
- User-scoped read APIs
src/api/accounts.py - Dashboard views
src/api/dashboard.py - Sync status API
src/api/sync_status.py - Readiness API
src/api/health.py - Sandbox CLI
src/commands/plaid_sandbox.py - Sync CLI
src/commands/plaid_sync.py
Other components
- Sandbox consumer
- Plaid Sandbox
Connections 31
- Sandbox consumer → FastAPI app: uses
README.md - FastAPI app → Webhook intake: routes
src/api/app.py - Webhook intake → Durable event inbox: persists event
README.md - Webhook intake → Event queue port: publishes identity
src/api/webhooks.py - Event queue port → SQS adapter: adapts publishing
src/infrastructure/sqs.py - SQS adapter → Lambda runtime: delivers message
- Lambda runtime → Leased event processor: invokes
src/infrastructure/lambda_runtime.py - Leased event processor → Durable event inbox: claims and finalizes
README.md - Leased event processor → Cursor synchronization: runs synchronization
src/application/event_processing.py - Cursor synchronization → Transaction provider port: fetches updates
src/application/synchronization.py - Plaid transaction adapter → Plaid Sandbox: requests transaction pages
src/providers/plaid.py - Cursor synchronization → Ledger rules: reconciles changes
src/application/synchronization.py - Cursor synchronization → Ledger repository: persists batch
src/application/synchronization.py - Ledger repository → Ledger rules: applies ledger rules
src/persistence/repository.py - Ledger rules → Accounting models: creates journal entries
src/domain/ledger.py - Ledger repository → Persistence models: maps records
src/persistence/repository.py - Persistence models → PostgreSQL: stores records
README.md - Plaid connection service → Plaid Sandbox client: creates Item and lists accounts
src/application/plaid_connection.py - Plaid Sandbox client → Plaid Sandbox: calls Sandbox API
src/providers/plaid_sandbox.py - Plaid connection service → Persistence models: records account mappings
src/application/plaid_connection.py - Sandbox consumer → User-scoped read APIs: requests accounts and transactions
README.md - Sandbox consumer → Sync status API: checks sync state
README.md - Sandbox consumer → Dashboard views: requests dashboard
- Sandbox consumer → Readiness API: checks readiness
README.md - User-scoped read APIs → Persistence models: queries user data
src/api/accounts.py - Dashboard views → Persistence models: queries read views
src/api/dashboard.py - Sync status API → Persistence models: queries sync state
src/api/sync_status.py - Readiness API → PostgreSQL: checks readiness
README.md - Sandbox CLI → Plaid connection service: bootstraps connection
src/commands/plaid_sandbox.py - Sync CLI → Cursor synchronization: runs synchronization
src/commands/plaid_sync.py - Sync CLI → Plaid transaction adapter: configures provider
src/commands/plaid_sync.py