Skip to content

Architecture

Design documentation for LedgerLens MCP, the Model Context Protocol server for Kosha Financial (a fictional Indian neobank). Decisions trace back to plan v1.0 and data model v0.2; lasting trade-offs live in ADRs.

High-level design

Document Covers
HLD System context, containers, AWS deployment, request & auth flows, SLOs, cost, trade-offs

Low-level design

Document Covers
MCP gateway Middleware pipeline, tool contracts, error taxonomy, cursor signing, scopes
Core API Routers, repositories, transaction boundaries, outbox, idempotency, ledger posting
Data model ER diagrams, status lifecycles, indexes, partitioning, RLS, PII handling
Resilience Deadlines, retry, circuit breaker, bulkhead, rate limiting, load shedding, chaos
RAG pipeline Ingestion, chunking, embeddings, hybrid retrieval SQL, evals, injection defences
Async messaging Transactional outbox, relay, idempotent consumers, DLQ handling
Security STRIDE threat model, secrets, KMS envelope encryption, audit, OWASP LLM Top 10
Deployment & CI/CD GitHub Actions, OIDC, image strategy, CodeDeploy canary, rollback
Observability OpenTelemetry signal flow, RED metrics, log schema, dashboards, alarms

Reading order

  1. HLD for the shape of the system.
  2. MCP gateway and Core API for the request path.
  3. Data model for what is stored and why.
  4. Resilience, async messaging and RAG for behaviour under load and failure.
  5. Security, deployment and observability for running it in production.