# mavulahq/ledger-core architecture

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

- Interactive diagram: https://gitdiagram.com/mavulahq/ledger-core
- Repository: https://github.com/mavulahq/ledger-core

## Overview

MAVULA Ledger Core is a tenant-aware financial source of truth. Operators and clients submit product, account, loan, and transaction requests; the service applies rules and records balanced ledger postings, account entries, and audit history. Controlled lifecycle changes and financial adjustments add maker-checker approval stages. Domain events flow through an outbox/inbox to workers and read projections, with regulatory export and operational metrics as supporting capabilities. Relationships among unsampled controllers and services are documented where visible in the README or source index; other uncertain wiring is omitted.

Main entry points: [`src/transactions/transaction.service.ts`](https://github.com/mavulahq/ledger-core/blob/main/src/transactions/transaction.service.ts) (Transaction processing), [`src/loans/loan.service.ts`](https://github.com/mavulahq/ledger-core/blob/main/src/loans/loan.service.ts) (Loan servicing), [`src/ledger/ledger.service.ts`](https://github.com/mavulahq/ledger-core/blob/main/src/ledger/ledger.service.ts) (Ledger posting), [`src/domain-events/domain-outbox.service.ts`](https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-outbox.service.ts) (Transactional outbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_accounts_api["Accounts API"]
  node_lifecycle_api["Lifecycle API"]
  node_adjustments_api["Adjustments API"]
  node_internal_api["Worker API"]
end

subgraph group_finance["Financial operations"]
  node_account_service["Account management"]
  node_loan_service["Loan servicing<br/>[loan.service.ts]"]
  node_transaction_service["Transaction processing"]
  node_ledger_service["Ledger posting<br/>[ledger.service.ts]"]
  node_adjustments["Financial adjustments"]
end

subgraph group_configuration["Tenant configuration"]
  node_product_config["Product configuration"]
  node_rules["Rules engine"]
  node_schemas["Schema manager"]
  node_workflow_api["Workflow API"]
end

subgraph group_events["Events and projections"]
  node_outbox["Transactional outbox"]
  node_publisher["Outbox publisher"]
  node_inbox["Event inbox"]
  node_worker["Engine event worker"]
  node_projections["Read projections"]
  node_regulatory["Regulatory export"]
end

subgraph group_platform["Persistence and operations"]
  node_store[("Financial store")]
  node_prisma[("Tenant persistence<br/>[prisma.service.ts]")]
  node_audit["Audit trail"]
  node_metrics["Metrics<br/>[metrics.service.ts]"]
end

node_client(("API client"))

node_client -->|"submits account requests"| node_accounts_api
node_client -->|"requests lifecycle changes"| node_lifecycle_api
node_client -->|"submits adjustments"| node_adjustments_api
node_accounts_api -->|"delegates account operations"| node_account_service
node_lifecycle_api -.->|"requests status changes"| node_account_service
node_adjustments_api -->|"submits approval requests"| node_adjustments
node_internal_api -->|"triggers publishing"| node_publisher
node_internal_api -->|"dispatches events"| node_worker
node_internal_api -->|"requests projection work"| node_projections
node_internal_api -->|"requests export data"| node_regulatory
node_transaction_service -->|"posts journal entries"| node_ledger_service
node_transaction_service -->|"evaluates rules"| node_rules
node_loan_service -->|"processes loan payments"| node_transaction_service
node_loan_service -->|"validates loan rules"| node_rules
node_loan_service -->|"reads product configuration"| node_product_config
node_account_service -->|"uses account products"| node_product_config
node_adjustments -->|"posts ledger corrections"| node_ledger_service
node_adjustments -->|"adjusts lending records"| node_loan_service
node_adjustments -->|"reverses transactions"| node_transaction_service
node_product_config -->|"writes domain events"| node_outbox
node_ledger_service -->|"records posting events"| node_outbox
node_loan_service -->|"records lending events"| node_outbox
node_publisher -->|"claims and marks events"| node_outbox
node_worker -->|"deduplicates incoming events"| node_inbox
node_worker -->|"updates projections"| node_projections
node_transaction_service -->|"reads and saves transactions"| node_store
node_ledger_service -->|"reads ledger state"| node_store
node_rules -->|"loads and saves rules"| node_store
node_schemas -.->|"persists schemas"| node_store
node_store -->|"persists tenant data"| node_prisma
node_outbox -->|"stores event records"| node_prisma
node_inbox -->|"stores inbox records"| node_prisma
node_projections -->|"persists read models"| node_prisma
node_transaction_service -->|"records transaction audit"| node_audit
node_ledger_service -->|"records ledger audit"| node_audit
node_adjustments_api -->|"records request metrics"| node_metrics

click node_accounts_api "https://github.com/mavulahq/ledger-core/blob/main/src/controllers/accounts.controller.ts"
click node_lifecycle_api "https://github.com/mavulahq/ledger-core/blob/main/src/controllers/account-lifecycle.controller.ts"
click node_adjustments_api "https://github.com/mavulahq/ledger-core/blob/main/src/controllers/financial-adjustments.controller.ts"
click node_internal_api "https://github.com/mavulahq/ledger-core/blob/main/src/controllers/internal-worker.controller.ts"
click node_account_service "https://github.com/mavulahq/ledger-core/blob/main/src/services/accounts.service.ts"
click node_loan_service "https://github.com/mavulahq/ledger-core/blob/main/src/loans/loan.service.ts"
click node_transaction_service "https://github.com/mavulahq/ledger-core/blob/main/src/transactions/transaction.service.ts"
click node_ledger_service "https://github.com/mavulahq/ledger-core/blob/main/src/ledger/ledger.service.ts"
click node_adjustments "https://github.com/mavulahq/ledger-core/blob/main/src/adjustments/financial-adjustments.service.ts"
click node_product_config "https://github.com/mavulahq/ledger-core/blob/main/src/products/product-config.service.ts"
click node_rules "https://github.com/mavulahq/ledger-core/blob/main/src/rules-engine/rules-engine.service.ts"
click node_schemas "https://github.com/mavulahq/ledger-core/blob/main/src/schema-manager/schema-manager.service.ts"
click node_workflow_api "https://github.com/mavulahq/ledger-core/blob/main/src/controllers/workflows.controller.ts"
click node_outbox "https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-outbox.service.ts"
click node_publisher "https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-outbox-publisher.service.ts"
click node_inbox "https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-inbox.service.ts"
click node_worker "https://github.com/mavulahq/ledger-core/blob/main/src/worker/engine-event.service.ts"
click node_projections "https://github.com/mavulahq/ledger-core/blob/main/src/read-models/read-projection.service.ts"
click node_regulatory "https://github.com/mavulahq/ledger-core/blob/main/src/regulatory/regulatory-export-source.service.ts"
click node_store "https://github.com/mavulahq/ledger-core/blob/main/src/services/fengine-store.service.ts"
click node_prisma "https://github.com/mavulahq/ledger-core/blob/main/src/services/prisma.service.ts"
click node_audit "https://github.com/mavulahq/ledger-core/blob/main/src/services/audit-trail.service.ts"
click node_metrics "https://github.com/mavulahq/ledger-core/blob/main/src/metrics/metrics.service.ts"

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_accounts_api,node_lifecycle_api,node_adjustments_api,node_internal_api,node_client toneBlue
class node_account_service,node_loan_service,node_transaction_service,node_ledger_service,node_adjustments toneAmber
class node_product_config,node_rules,node_schemas,node_workflow_api toneMint
class node_outbox,node_publisher,node_inbox,node_worker,node_projections,node_regulatory toneRose
class node_store,node_prisma,node_audit,node_metrics toneIndigo
```

## Components

### API and access

- [Accounts API](https://github.com/mavulahq/ledger-core/blob/main/src/controllers/accounts.controller.ts): `src/controllers/accounts.controller.ts`
- [Lifecycle API](https://github.com/mavulahq/ledger-core/blob/main/src/controllers/account-lifecycle.controller.ts): `src/controllers/account-lifecycle.controller.ts`
- [Adjustments API](https://github.com/mavulahq/ledger-core/blob/main/src/controllers/financial-adjustments.controller.ts): `src/controllers/financial-adjustments.controller.ts`
- [Worker API](https://github.com/mavulahq/ledger-core/blob/main/src/controllers/internal-worker.controller.ts): `src/controllers/internal-worker.controller.ts`

### Financial operations

- [Account management](https://github.com/mavulahq/ledger-core/blob/main/src/services/accounts.service.ts): `src/services/accounts.service.ts`
- [Loan servicing](https://github.com/mavulahq/ledger-core/blob/main/src/loans/loan.service.ts): `src/loans/loan.service.ts`
- [Transaction processing](https://github.com/mavulahq/ledger-core/blob/main/src/transactions/transaction.service.ts): `src/transactions/transaction.service.ts`
- [Ledger posting](https://github.com/mavulahq/ledger-core/blob/main/src/ledger/ledger.service.ts): `src/ledger/ledger.service.ts`
- [Financial adjustments](https://github.com/mavulahq/ledger-core/blob/main/src/adjustments/financial-adjustments.service.ts): `src/adjustments/financial-adjustments.service.ts`

### Tenant configuration

- [Product configuration](https://github.com/mavulahq/ledger-core/blob/main/src/products/product-config.service.ts): `src/products/product-config.service.ts`
- [Rules engine](https://github.com/mavulahq/ledger-core/blob/main/src/rules-engine/rules-engine.service.ts): `src/rules-engine/rules-engine.service.ts`
- [Schema manager](https://github.com/mavulahq/ledger-core/blob/main/src/schema-manager/schema-manager.service.ts): `src/schema-manager/schema-manager.service.ts`
- [Workflow API](https://github.com/mavulahq/ledger-core/blob/main/src/controllers/workflows.controller.ts): `src/controllers/workflows.controller.ts`

### Events and projections

- [Transactional outbox](https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-outbox.service.ts): `src/domain-events/domain-outbox.service.ts`
- [Outbox publisher](https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-outbox-publisher.service.ts): `src/domain-events/domain-outbox-publisher.service.ts`
- [Event inbox](https://github.com/mavulahq/ledger-core/blob/main/src/domain-events/domain-inbox.service.ts): `src/domain-events/domain-inbox.service.ts`
- [Engine event worker](https://github.com/mavulahq/ledger-core/blob/main/src/worker/engine-event.service.ts): `src/worker/engine-event.service.ts`
- [Read projections](https://github.com/mavulahq/ledger-core/blob/main/src/read-models/read-projection.service.ts): `src/read-models/read-projection.service.ts`
- [Regulatory export](https://github.com/mavulahq/ledger-core/blob/main/src/regulatory/regulatory-export-source.service.ts): `src/regulatory/regulatory-export-source.service.ts`

### Persistence and operations

- [Financial store](https://github.com/mavulahq/ledger-core/blob/main/src/services/fengine-store.service.ts): `src/services/fengine-store.service.ts`
- [Tenant persistence](https://github.com/mavulahq/ledger-core/blob/main/src/services/prisma.service.ts): `src/services/prisma.service.ts`
- [Audit trail](https://github.com/mavulahq/ledger-core/blob/main/src/services/audit-trail.service.ts): `src/services/audit-trail.service.ts`
- [Metrics](https://github.com/mavulahq/ledger-core/blob/main/src/metrics/metrics.service.ts): `src/metrics/metrics.service.ts`

### Other components

- **API client**

## Connections

- API client → Accounts API: submits account requests (evidence: `README.md`)
- API client → Lifecycle API: requests lifecycle changes (evidence: `README.md`)
- API client → Adjustments API: submits adjustments (evidence: `README.md`)
- Accounts API → Account management: delegates account operations (evidence: `src/controllers/accounts.controller.ts`)
- Lifecycle API → Account management: requests status changes
- Adjustments API → Financial adjustments: submits approval requests (evidence: `src/controllers/financial-adjustments.controller.ts`)
- Worker API → Outbox publisher: triggers publishing (evidence: `src/controllers/internal-worker.controller.ts`)
- Worker API → Engine event worker: dispatches events (evidence: `src/controllers/internal-worker.controller.ts`)
- Worker API → Read projections: requests projection work (evidence: `src/controllers/internal-worker.controller.ts`)
- Worker API → Regulatory export: requests export data (evidence: `src/controllers/internal-worker.controller.ts`)
- Transaction processing → Ledger posting: posts journal entries (evidence: `src/transactions/transaction.service.ts`)
- Transaction processing → Rules engine: evaluates rules (evidence: `src/transactions/transaction.service.ts`)
- Loan servicing → Transaction processing: processes loan payments (evidence: `src/loans/loan.service.ts`)
- Loan servicing → Rules engine: validates loan rules (evidence: `src/loans/loan.service.ts`)
- Loan servicing → Product configuration: reads product configuration (evidence: `src/loans/loan.service.ts`)
- Account management → Product configuration: uses account products (evidence: `src/services/accounts.service.ts`)
- Financial adjustments → Ledger posting: posts ledger corrections (evidence: `src/adjustments/financial-adjustments.service.ts`)
- Financial adjustments → Loan servicing: adjusts lending records (evidence: `src/adjustments/financial-adjustments.service.ts`)
- Financial adjustments → Transaction processing: reverses transactions (evidence: `src/adjustments/financial-adjustments.service.ts`)
- Product configuration → Transactional outbox: writes domain events (evidence: `src/products/product-config.service.ts`)
- Ledger posting → Transactional outbox: records posting events (evidence: `src/ledger/ledger.service.ts`)
- Loan servicing → Transactional outbox: records lending events (evidence: `src/loans/loan.service.ts`)
- Outbox publisher → Transactional outbox: claims and marks events (evidence: `src/domain-events/domain-outbox-publisher.service.ts`)
- Engine event worker → Event inbox: deduplicates incoming events (evidence: `src/worker/engine-event.service.ts`)
- Engine event worker → Read projections: updates projections (evidence: `src/worker/engine-event.service.ts`)
- Transaction processing → Financial store: reads and saves transactions (evidence: `src/transactions/transaction.service.ts`)
- Ledger posting → Financial store: reads ledger state (evidence: `src/ledger/ledger.service.ts`)
- Rules engine → Financial store: loads and saves rules (evidence: `src/rules-engine/rules-engine.service.ts`)
- Schema manager → Financial store: persists schemas (evidence: `src/schema-manager/schema-manager.service.ts`)
- Financial store → Tenant persistence: persists tenant data (evidence: `src/services/fengine-store.service.ts`)
- Transactional outbox → Tenant persistence: stores event records (evidence: `src/domain-events/domain-outbox.service.ts`)
- Event inbox → Tenant persistence: stores inbox records (evidence: `src/domain-events/domain-inbox.service.ts`)
- Read projections → Tenant persistence: persists read models (evidence: `src/read-models/read-projection.service.ts`)
- Transaction processing → Audit trail: records transaction audit (evidence: `src/transactions/transaction.service.ts`)
- Ledger posting → Audit trail: records ledger audit (evidence: `src/ledger/ledger.service.ts`)
- Adjustments API → Metrics: records request metrics (evidence: `src/controllers/financial-adjustments.controller.ts`)