# mavulahq/finance-platform architecture

> Architecture diagram of the GitHub repository mavulahq/finance-platform, 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/finance-platform
- Repository: https://github.com/mavulahq/finance-platform

## Overview

MAVULA is a modular financial infrastructure platform spanning identity, ledger, lending, payments, workflow, and operational controls. Its documented event workflow sends settlement-completed events from Settlements through Workbench to Ledger Core, where they are recorded idempotently without directly mutating ledger or lending state. The graph also preserves the major documented modules and contract-validation tooling. Package internals were not sampled, so relationships beyond those explicitly documented are omitted rather than inferred.

Main entry points: [`scripts/validate-domain-contracts.mjs`](https://github.com/mavulahq/finance-platform/blob/main/scripts/validate-domain-contracts.mjs) (Contract validator), [`packages/workbench`](https://github.com/mavulahq/finance-platform/tree/main/packages/workbench) (Workbench), [`packages/settlements`](https://github.com/mavulahq/finance-platform/tree/main/packages/settlements) (Settlements), [`packages/identity-access`](https://github.com/mavulahq/finance-platform/tree/main/packages/identity-access) (Identity Access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Financial platform"]
  node_identity["Identity Access"]
  node_ledger[("Ledger Core")]
  node_settlements["Settlements"]
  node_workbench["Workbench"]
end

subgraph group_contracts["Contracts and validation"]
  node_events["Domain event contracts<br/>[event-catalog.json]"]
  node_identitycontracts["Identity contracts"]
  node_regulatory["Regulatory contracts"]
  node_contractcheck["Contract validator"]
end

subgraph group_integration["Integration capabilities"]
  node_legacy["Legacy Connectors"]
  node_developerdocs["Developer Docs"]
end

subgraph group_operations["Operations"]
  node_operationspkg["Operations"]
end

node_institution(("Institutional user"))

node_institution -.->|"uses identity"| node_identity
node_settlements -->|"delivers event through"| node_workbench
node_workbench -->|"delivers event to"| node_ledger
node_contractcheck -->|"validates"| node_events
node_contractcheck -->|"validates"| node_identitycontracts
node_contractcheck -->|"validates"| node_regulatory
node_contractcheck -->|"checks interoperability"| node_legacy
node_contractcheck -->|"checks published contracts"| node_developerdocs

click node_identity "https://github.com/mavulahq/finance-platform/tree/main/packages/identity-access"
click node_ledger "https://github.com/mavulahq/finance-platform/tree/main/packages/ledger-core"
click node_settlements "https://github.com/mavulahq/finance-platform/tree/main/packages/settlements"
click node_workbench "https://github.com/mavulahq/finance-platform/tree/main/packages/workbench"
click node_events "https://github.com/mavulahq/finance-platform/blob/main/contracts/domain-events/event-catalog.json"
click node_identitycontracts "https://github.com/mavulahq/finance-platform/tree/main/contracts/identity"
click node_regulatory "https://github.com/mavulahq/finance-platform/tree/main/contracts/regulatory"
click node_contractcheck "https://github.com/mavulahq/finance-platform/blob/main/scripts/validate-domain-contracts.mjs"
click node_legacy "https://github.com/mavulahq/finance-platform/tree/main/packages/legacy-connectors"
click node_developerdocs "https://github.com/mavulahq/finance-platform/tree/main/packages/developer-docs"
click node_operationspkg "https://github.com/mavulahq/finance-platform/tree/main/packages/operations"

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_identity,node_ledger,node_settlements,node_workbench,node_institution toneBlue
class node_events,node_identitycontracts,node_regulatory,node_contractcheck toneAmber
class node_legacy,node_developerdocs toneMint
class node_operationspkg toneRose
```

## Components

### Financial platform

- [Identity Access](https://github.com/mavulahq/finance-platform/tree/main/packages/identity-access): `packages/identity-access`
- [Ledger Core](https://github.com/mavulahq/finance-platform/tree/main/packages/ledger-core): `packages/ledger-core`
- [Settlements](https://github.com/mavulahq/finance-platform/tree/main/packages/settlements): `packages/settlements`
- [Workbench](https://github.com/mavulahq/finance-platform/tree/main/packages/workbench): `packages/workbench`

### Contracts and validation

- [Domain event contracts](https://github.com/mavulahq/finance-platform/blob/main/contracts/domain-events/event-catalog.json): `contracts/domain-events/event-catalog.json`
- [Identity contracts](https://github.com/mavulahq/finance-platform/tree/main/contracts/identity): `contracts/identity`
- [Regulatory contracts](https://github.com/mavulahq/finance-platform/tree/main/contracts/regulatory): `contracts/regulatory`
- [Contract validator](https://github.com/mavulahq/finance-platform/blob/main/scripts/validate-domain-contracts.mjs): `scripts/validate-domain-contracts.mjs`

### Integration capabilities

- [Legacy Connectors](https://github.com/mavulahq/finance-platform/tree/main/packages/legacy-connectors): `packages/legacy-connectors`
- [Developer Docs](https://github.com/mavulahq/finance-platform/tree/main/packages/developer-docs): `packages/developer-docs`

### Operations

- [Operations](https://github.com/mavulahq/finance-platform/tree/main/packages/operations): `packages/operations`

### Other components

- **Institutional user**

## Connections

- Institutional user → Identity Access: uses identity (evidence: `README.md`)
- Settlements → Workbench: delivers event through (evidence: `README.md`)
- Workbench → Ledger Core: delivers event to (evidence: `README.md`)
- Contract validator → Domain event contracts: validates (evidence: `scripts/validate-domain-contracts.mjs`)
- Contract validator → Identity contracts: validates (evidence: `scripts/validate-domain-contracts.mjs`)
- Contract validator → Regulatory contracts: validates (evidence: `scripts/validate-domain-contracts.mjs`)
- Contract validator → Legacy Connectors: checks interoperability (evidence: `scripts/validate-domain-contracts.mjs`)
- Contract validator → Developer Docs: checks published contracts (evidence: `scripts/validate-domain-contracts.mjs`)