Architectural Brief: Compliance Document Substrate
Klevar Docs is the internal document substrate for the Klevar Group. It renders legal documents, records audit state, signs and archives compliance outputs, and keeps entity boundaries visible at every layer.
The main constraint is legal shape. FZE is a Nigerian free-zone entity. LLC is a United States entity. Ltd is a Nigerian dormant private company limited by shares under CAMA 2020. The architecture cannot treat those as branding variants. They are policy boundaries.
System Topology
Infrastructure Decisions
- Headless Fastify API plus CLI: Chose this over a Docs-owned client UI because the Client Portal owns user workflow, while Docs owns issuance, proof, reports, and operator validation.
- Single-tenant, multi-entity schema: Chose this over a public tenant abstraction because Klevar is one group with separate FZE, LLC, and Ltd legal boundaries.
entity_id, nottenant_id, is the invariant. - Specialized compose dispatch: Chose this over sending all 14 document types through the generic renderer because invoices, pro-forma invoices, credit notes, and board resolutions create domain rows and legal state.
- Frozen entity snapshots: Chose this over live entity lookup because an archived document must keep the identity, banking, officer, and policy state it had at issuance.
- Java sidecars behind Unix sockets: Chose this over reimplementing EN16931, XRechnung, and PAdES in TypeScript because mustangproject and EU DSS own those compliance surfaces.
- Per-entity hash chain: Chose this over one operational event log because proof has to be ordered and tamper-evident inside each legal entity.
- Shared engines for fanout and schedules: Chose this over local email, webhook, and cron code because Docs should produce durable document state, then delegate delivery and orchestration.
Core Constraints
| Invariant | Enforcement |
|---|---|
| Every data-bearing row belongs to an entity | Schema review and scoped DB helpers require entity_id. |
| Entity identity is data, not code | Seed files and database rows feed frozen snapshots. |
| Dormant Nigerian Ltd cannot issue active trading documents | Entity/type matrix allows only letterhead, compliance letters, and board resolutions. |
| Compliance paths fail closed | XML, PDF/A, signing, and chain errors stop finalization. |
| Document history is immutable | Corrections supersede documents instead of editing issued rows. |
| Numbering is gap-aware | Pending allocations, sequence gaps, and a reaper keep sequences defensible. |
| External engines do not own issuance | Notification, webhook, and workflow calls occur after internal state is durable. |
Compose Boundary
The API has a single umbrella command for operators:
documents compose --type <document_type> --body ./payload.json
The server does not blindly render every type through the generic composer. It checks a specialized dispatch map first.
export const COMPOSE_SPECIALIZED_DISPATCH: Partial<Record<TemplateType, ComposeDispatcher>> = {
invoice: invoiceDispatcher,
pro_forma_invoice: proFormaDispatcher,
credit_note: creditNoteDispatcher,
board_resolution: boardResolutionDispatcher,
};
That boundary was added after CLI validation showed a failure mode: a credit note could be composed as a PDF while bypassing createCreditNote(), which meant it skipped inherited payment terms from the source invoice. The CLI was doing its job. It made the wrong server path visible.
Entity Matrix
The matrix is not only documentation. Integration tests enumerate allowed and blocked cells, including a Ltd sanity check that asserts the exact three allowed types.
Compliance Pipeline
Data Boundaries
Decision Log
| Decision | Tradeoff |
|---|---|
| Keep Docs headless | The Client Portal owns UI, while Docs owns issuance and proof. |
| Use one compose surface | Operators get one command, but the server still preserves specialized domain paths. |
| Store entity snapshots on documents | Historical correctness beats small row size. |
| Put Java compliance libraries in a sidecar | Node stays lean, while mustangproject and EU DSS run in their native runtime. |
| Anchor hash chains per entity | Verification remains narrow and legal-entity specific. |
| Delegate notifications and webhooks | Docs stays focused on issuance, then hands durable events to shared engines. |
| Test the entity/type matrix | Missing coverage becomes a failing test instead of a spreadsheet comment. |
Failure Modes Covered
| Failure | Guard |
|---|---|
| Ltd invoice issued while dormant | Entity/type matrix blocks the request. |
| FZE identity leaks into LLC output | Snapshot-driven templates and entity-neutral regression tests catch it. |
| Credit note loses source invoice terms | Shared propagation helper and specialized dispatch keep inheritance inside domain services. |
| PDF renders but XML is invalid | Factur-X and XRechnung validation stop finalization. |
| Number reservation dies mid-request | Pending allocation reaper returns the number to the gap pool. |
| External delivery engine is down | Durable document state exists before fanout. |
Operational Surface
The CLI is not a thin demo tool. The package exposes command modules for document creation, compliance checks, reports, hash-chain verification, and admin workflows. It also has a coverage gate against OpenAPI so new API routes cannot hide from operators.
That matters because this system was improved by operator evidence. The most valuable bugs were not discovered by reading diagrams. They appeared when Brain used the CLI like a real back-office operator: generate every reachable document, send what can be sent, run reports, verify hash-chain state, then compare the observed output with the PRD.