The Document System Behind a Multi-Entity Company
The Situation
Klevar Docs is proprietary internal infrastructure for the Klevar Group. It exists because the group is not one legal body with one stationery template. The system has to issue documents for Klevar FZE in Nigeria, Klevar LLC in the United States, and Klevar Ltd in Nigeria.
That last entity matters. Klevar Ltd is a Nigerian private company limited by shares, registered under CAMA 2020, currently dormant. Its allowed document set is intentionally narrow: letterhead, compliance letters, and board resolutions. It must not issue invoices, contracts, proposals, receipts, statements, or credit notes while dormant.
The business problem was not "make PDFs." The business problem was proof. If a client receives an invoice, the company must prove which entity issued it, which number was allocated, which bank details were shown, which compliance XML was attached, which hash chain entry locked it, and which events were emitted after the fact.
The internal CLI became part of that proof. Brain operator runs used @klevar/docs-cli to generate documents, exercise reports, verify hash chains, and expose places where the API looked reachable but skipped deeper business rules.
The Cost of Doing Nothing
Scattered document generation looks cheap until the first wrong document leaves the company.
An FZE invoice with LLC banking details is not a rendering bug. A dormant Nigerian Ltd invoice is not a template bug. A credit note that fails to inherit payment terms is not a PDF bug. Each is a control failure that can wake tax exposure, delay filings, break client trust, or consume days of finance and engineering review.
The Nigerian Ltd seed captures the risk in plain terms: the dormant entity should not invoice while FZE is active, because doing so triggers corporate compliance and possible tax exposure. The PRD also calls out concrete penalties around entity compliance, including Nigerian filing penalties and a $25,000 Form 5472 disclosure penalty for the US entity context.
The substrate exists to remove the habit that creates those failures: every team making its own small document generator.
What I Built
Klevar Docs is a TypeScript, Fastify 5, PostgreSQL 16, Redis, Supabase Storage, Puppeteer, Ghostscript, veraPDF, mustangproject, and EU DSS service. It exposes a headless REST API and a first-party CLI. The client-facing UI stays in the Client Portal.
The service covers 14 document families:
- letterhead
- invoice
- pro-forma invoice
- credit note
- board resolution
- contract cover
- proposal
- engagement letter
- receipt
- statement
- quote
- reference letter
- minutes
- compliance letter
FZE and LLC can use the full set. Nigerian Ltd can use only the dormant-safe subset. That matrix is tested instead of described in comments.
The core rule is simple: all documents share one rendering system, but not all documents share one business path. A quote can be schema-gated and rendered. An invoice must allocate a number, create invoice state, branch into Factur-X or XRechnung, pass PDF/A checks, sign when required, enter the hash chain, and emit events. A credit note must inherit fields from its source invoice unless the request explicitly overrides them.
System Flow
Data Model
Architecture Layers
Decision Log
| Decision | Alternative Rejected | Why |
|---|---|---|
| Single-tenant, multi-entity model | Public SaaS tenant model | Klevar has one group context, but FZE, LLC, and Nigerian Ltd need separate legal identities and audit trails. |
entity_id on data-bearing rows |
Generic tenant_id middleware |
Entity scope is a primary invariant in the schema and DB helpers, not a filter added after queries. |
| Config-driven legal identity | Template literals per entity | FZE, LLC, and Nigerian Ltd identity comes from seed files and database state, then renders through snapshots. |
| Frozen entity snapshot per document | Live entity lookup on re-render | A document must keep the legal, banking, officer, and policy state it rendered with, even if the entity row changes later. |
| Compose dispatch before generic render | One generic renderer for every type | Invoices, pro-forma invoices, credit notes, and resolutions need domain services before rendering. |
| Per-entity hash chain | One global audit log | Chain verification has to prove ordered tamper evidence inside each legal entity. |
| Sidecar split for Java compliance tools | Rebuild EN16931 and PAdES inside Node | Node owns the API, while mustangproject and EU DSS run behind Unix sockets in their native runtime. |
| CLI coverage gates | Treat the CLI as a manual helper | The operator surface is tested against OpenAPI so hidden endpoints and body-shape drift do not rot. |
Ecosystem Integration
Klevar Docs does not try to own every cross-cutting concern. It delegates notification delivery to the Event-Driven Notification Hub, external fanout to the Webhook Ingestion Engine, and recurring automation to the Workflow Automation Engine. The hot compliance path stays inside Docs: sequence allocation, entity snapshots, specialized document creation, signing, and hash-chain insertion.
That boundary keeps the document transaction small enough to reason about. External engines can fail or retry without changing the issued document. The document row, specialization row, object storage key, and hash-chain entry remain the source of truth.
Results
The project now has a CLI and API surface that can prove more than "the route returned 200." The Phase M and Phase N validation work generated all reachable document types, checked the entity/type coverage matrix, ran CLI E2E suites, exercised reports, verified hash chains, and exposed a compose routing bug that would have stayed hidden in ordinary unit tests.
The highest-value result was the correction to how I think about coverage. A command that creates a PDF is not enough. The right question is whether the command reached the service that owns the legal rule.
For this system, the answer is now encoded in the architecture:
- Nigerian Ltd is blocked from documents that would violate dormancy.
- Specialized document types enter specialized services even through the umbrella compose endpoint.
- Entity identity is captured from seed and database state into immutable snapshots.
- Compliance artifacts fail closed instead of producing valid-looking replacements.
- Hash-chain verification can be run by an operator through the CLI.
Klevar Docs turned document generation from an application feature into company infrastructure.