Skip to content

Limen — Project Principles & Architecture North Star

Version: 0.1
Status: Living document
Owner: Fordsworth / Limen Core Team
Last updated: 2026-08-08

1. Vision

Limen is the operating system for risk.

It is not another Policy Administration System.
It is the precise, high-performance layer on which modern insurance (life, credit life, short-term, and any insurable risk) will run.

Positioning - Company: Fordsworth - Platform / Product: Limen - Promise: Risk is just data. Run it on Limen.

Limen must feel inevitable — calm, precise, and superior to legacy insurance platforms.

2. Non-Negotiable Architectural Principles

These rules cannot be violated. Every design decision and every new capability must respect them.

  1. Stateless Compute
    No service holds business state in memory between requests. All state is explicitly read from or written to the stores.

  2. Append-Only Financial Ledger (Fluid-GL)
    Financial transactions are never updated or deleted. Corrections are new reversing or adjusting entries. This is the financial source of truth.

  3. Data Locality (Hydrated Contract State)
    A contract and its components exist as a fully hydrated document (primarily in Redis). We do not reconstruct a policy by joining many tables at runtime.

  4. Temporal / Bi-Temporal Versioning
    Every material change to a contract creates a new immutable version with effective time and system time. History is preserved. Back-dated changes create a new fork and financial deltas — they never rewrite the past.

  5. Idempotency by Default
    Every command that can create or change money or contract state carries an idempotency key. Exactly-once processing is a system property.

  6. DMN-Driven Business Logic
    Pricing, splits, eligibility, loadings, commission rules, amortization behaviour, and most decisioning live in DMN (Kogito). Actuaries and business analysts own the rules. Code does not hard-code insurance logic.

  7. CQRS
    The write path is optimised for correctness and speed. Read models (actuarial, financial, operational, search) are projected asynchronously and can be specialised.

  8. Cellular Multi-Tenancy & Data Residency
    Each major client or jurisdiction can run in an isolated data cell (for POPIA, Kenya Data Protection Act, etc.). Stateless code is deployed uniformly via GitOps.

  9. One Model for All Lines
    Life, credit life, short-term, and specialty risks use the same Contract + Component + Participation + Ledger primitives. Differences are configuration and DMN behaviour, not separate cores.

  10. Events Over Batch
    Month-end batch thinking is prohibited for core operations. Lifecycle events (escalations, expiries, collections, pre-alerts) are scheduled and executed continuously.

3. Core Engines (The Real Architecture)

Everything on the capability map is powered by a small set of engines.

3.1 Graph-E (Party & Hierarchy Engine)

  • Single party model (person or organisation)
  • Roles are edges, not separate databases
  • Supports complex broker hierarchies, commission overrides, co-insurance groups, and multi-party contracts
  • In-memory / graph-friendly access for speed

3.2 Quantum-Tree (Contract & Component Engine)

  • Contract is the root
  • Components are nested risk / cover / benefit items (life cover, building, credit life, flight strip, etc.)
  • Fully hydrated JSON document in Redis (with tiered storage)
  • Supports any insurable item through metadata + type
  • Temporal versions of the entire tree

3.3 Kinetic (Lifecycle & Amortization Engine)

  • Manages state transitions and time-based behaviour
  • UPP / EPP, linear or curve-based recognition
  • Escalations, benefit expiries, renewals, cover-on-demand start/stop
  • Calculates financial deltas when structure or terms change

3.4 Fluid-GL (Append-Only Sub-Ledger)

  • Immutable financial event store
  • Records premiums, splits, commissions, reinsurance shares, claims, reversals, adjustments
  • Zero row locking
  • Source of truth for all money movement
  • Feeds both operational views and external general ledgers

3.5 Decisioning Layer (DMN + Synapse)

  • Kogito DMN for deterministic, auditable rules
  • Synapse for AI-assisted underwriting, triage, and document understanding
  • AI proposes; DMN (or explicit policy) decides and records the outcome

3.6 Read Models (CQRS Projections)

  • Operational (Elasticsearch / search & 360 views)
  • Financial (normalised ledger views, trial balances)
  • Actuarial (cohort cashflows, experience, IFRS 17 feeds)
  • Powered by CDC / event streams from the write side

4. Mapping Capability Domains → Core Engines

This is the filter. New work must declare its primary engine(s).

Capability Domain Primary Engine(s) Secondary / Supporting
Product Engineering Quantum-Tree + DMN —
Quotes & Illustrations Quantum-Tree + DMN + Kinetic —
Sales / New Business Graph-E + Quantum-Tree + Fluid-GL —
Underwriting Synapse + DMN + Quantum-Tree —
Policy Maintenance Quantum-Tree (temporal) + Kinetic + Fluid-GL —
Reinsurance Quantum-Tree (participation) + Fluid-GL + DMN —
Finance / Transactions Fluid-GL Read models
Collections Fluid-GL + Adapters Kinetic (scheduling)
Commission Graph-E + Fluid-GL + DMN —
Claims Quantum-Tree + Fluid-GL + Synapse + Kinetic —
Customer Care / 360 Read Models Graph-E + Quantum-Tree
Documents Supporting service Linked to contract versions
Communications Event-driven side effects Triggered by state changes
Risk & Compliance DMN + Audit trail + Read models —
Data Lake / Reporting CQRS Read Models + CDC —
Business Processes DMN + BPMN (orchestration only) Never owns core state
Channels (USSD, Portals, WhatsApp, etc.) API Gateway + thin clients All talk to the same engines

Rule: We do not build independent “Reinsurance Service”, “Commission Service”, or “Claims Service” cores. We build capabilities that operate on the shared Contract + Ledger.

5. Data & Consistency Model (Summary)

  • Write path: Command → Idempotency check → Load hydrated state → DMN (if needed) → Create new temporal version (if structural) → Append ledger entries → Emit events.
  • Contract state: Redis (hot) + tiered storage. Full document per version.
  • Ledger: Distributed PostgreSQL / YugabyteDB (or equivalent), append-only, event-sourced style.
  • History: Bi-temporal (effective time + system time). Back-dated corrections create a new fork + compensating ledger entries.
  • Read path: Specialised projections. Never run heavy analytics on the write stores.

6. Multi-Tenancy, Compliance & Deployment

  • Cellular deployment model.
  • Each major client or regulated jurisdiction can have an isolated data cell (local Postgres + Redis).
  • Stateless application code and DMN models are deployed uniformly via GitOps (ArgoCD or equivalent).
  • Supports POPIA, Kenya Data Protection Act, and similar regimes by keeping PII inside the correct cell.
  • Branding and configuration are tenant-aware; the engines are not.

7. Delivery Phases & Milestones

Phase 0 — Foundation (Current)

  • [x] Brand & design system direction (Limen)
  • [ ] This principles document locked
  • [ ] Development standards, repo structure, CI skeleton
  • [ ] Local development environment (Quarkus + Redis + Postgres)

Phase 1 — Contract Core (First major milestone)

  • Party model (Graph-E foundation)
  • Contract + Component model (Quantum-Tree)
  • Temporal versioning (create, supersede, snapshot)
  • Basic lifecycle states
  • Simple DMN execution hook
  • Exit criteria: Can create a multi-component policy, version it, and retrieve any historical snapshot correctly.

Phase 2 — Financial Core

  • Fluid-GL append-only ledger
  • Premium receipt, basic split, reversal
  • Simple UPP/EPP recognition
  • Idempotent collection events
  • Exit criteria: Money can be recorded, split, and reversed without ever updating a ledger row. Running balance is correct.

Phase 3 — Decisioning & Automation

  • Full DMN integration for pricing, splits, eligibility
  • Timeline engine (visual + queryable)
  • Scheduled events (escalations, expiries, pre-alerts)
  • Basic commission calculation via Graph-E + DMN

Phase 4 — Expansion Capabilities

  • Reinsurance participation & recovery
  • Claims intake & payment
  • Richer collections adapters
  • Read models (operational + financial + actuarial feed)
  • Multi-tenant cell deployment

Phase 5 — Intelligence & Scale

  • Synapse AI-assisted flows
  • Advanced behavioural / telemetry products
  • Performance hardening and chaos testing
  • Full IFRS 17 data provision patterns

Start here and do not deviate until it is solid:

  1. Party (minimal viable Graph-E)
  2. Contract + Component (Quantum-Tree document shape)
  3. Temporal versioning mechanics
  4. Append-only Ledger skeleton (Fluid-GL)
  5. One simple end-to-end flow: Create policy → Version it → Record a premium → Reverse it

Only after this foundation is proven do we open the outer capability boxes.

9. Decision Log (Initial)

Decision Rationale Date
One core model for life and short-term Prevents architectural forks 2026-08
Append-only ledger is mandatory Financial integrity + audit + no locking 2026-08
DMN owns business logic Speed of change + actuary ownership 2026-08
Cellular multi-tenancy Data residency & isolation 2026-08
Start with Contract + Ledger core Highest leverage, hardest problems first 2026-08

10. How to Use This Document

  • Every significant design or ADR must reference which principles it upholds.
  • New capabilities must state their primary engine(s).
  • If a proposed design violates a non-negotiable, it is rejected or the principle is formally revised.
  • This file is the first thing a new engineer reads.

Next immediate actions 1. Review and lock this document. 2. Define the initial Contract + Component + Party JSON shapes. 3. Stand up the skeleton services and stores. 4. Implement the first vertical slice (create → version → premium → reverse).

We build the core first. Everything else is capability on top of a correct foundation.