Finance — architecture documentation index

Architecture-layer documentation for the Ethica Capital finance module. Each page describes how a feature fits into the broader posting pipeline: data flow (with Mermaid diagrams), interactions between components, invariants the feature must preserve, and failure modes.

Audience: lead engineers, architects, and anyone making cross-cutting decisions about the module.

For per-feature technical detail (models, endpoints, file paths) see the technical finance docs. For staff-facing flow descriptions see the business finance docs.

The posting pipeline (overview)

The whole finance module is built around a single ledger pipeline:

• GL is append-only and hash-chained (see hash chain verifier).
• Subledgers mirror GL control accounts and are reconciled daily.
• Validation + Shariah engines are introduced in Phase 1 Block 1.B; before that, posting paths call journal-entries.service.ts directly.

Phase 0 — Foundation fixes (complete)

Phase 0 did not add new pipeline stages; it strengthened the GL layer (more SourceModule values, AAOIFI account skeleton, reversal handling, server-side integrity check). For full task detail see phase-0-foundation and the technical docs.

Phase 1 — Critical infrastructure

• Block 1.A — subledgers + reconciliation — pipeline diagram of how GL ↔ subledger ↔ control account reconciles, plus the reconciliation orchestrator.
• Block 1.B — posting pipeline — full validation → Shariah → posting chain wrapped in one transaction.
• Block 1.C — NAV engine — price + FX + 12-step calculator producing dated immutable snapshots.
• Block 1.D — NAV-fund flows — subscriptions, redemptions, equity + sukuk trades. Parallel to the existing Mudarabah product; staff-driven for now.

Phase 1 is complete. Phase 2 architecture pages (purification, zakat, month-end close) land with that work.

Invariants we never break

• Journal entries are append-only. The only allowed mutation is setting metadata.reversedBy on an entry that has been reversed (see reversal API).
• Every posted entry's currentHash must reproduce from (reference, date, sourceModule, narration, lines, timestamp, previousHash) using the shared helper at ethica-api/src/finance/integrity/journal-hash.ts.
• Subledger sums must equal their GL control-account balance at end of day — exceptions are tracked, not hidden.
• DR = CR within 0.01 NGN tolerance for every entry.