Three layers, one honest spine
AnKampung's architecture exists to enforce a single rule: the engine never invents facts. Business modules write verified events to an append-only log; a State Engine projects them into a disposable, rebuildable Digital Twin that every surface reads from; intelligence sits on top, optional and never load-bearing. This is how that one rule becomes an engineering contract.
The three layers
Only Layer 1 is authoritative. Layer 2 is a projection of it, and Layer 3 is a guest that reads Layer 2 through a gate and asks permission before it touches anything. The CQRS boundary is the whole design: writes on the left, reads on the right, and the only path between them is the event stream.
System of Record
The domain modules — living, guard, finance, maintenance, facility, device, connect, governance — and the platform services beneath them. Layer 1 owns every write and every audit ledger. It is the only place a fact becomes true, and nothing above it is ever allowed to quietly rewrite what it recorded.
Community Digital Twin
The read-model every surface actually shows. It is a deterministic projection of the append-only event log — disposable, rebuildable and hash-checkable, keyed by tenant so a community's rows never cross a shard. What the twin displays is exactly what the ledger proves; it has never invented a fact and structurally cannot.
QynQue Intelligence
The AI spine reads the twin only through a Permission Gateway, and it only proposes — a human approves anything consequential. Core community operations never depend on an LLM being reachable. Intelligence is additive and strictly non-authoritative; remove it entirely and the platform still runs the kampung.
curated events frozen in the contract v1.0 — the grammar of what a community's truth is allowed to look like
Each event has a single declared producer; a spoofed producer is rejected at the validation gate before it ever reaches the twin.
The log is append-only and tenant-partitioned — facts are added, never edited in place.
Five steps, one pass
The engine is a process, not a product: it turns the frozen event contract into the twin. Delivery is assumed at-least-once, out of order, and late — the pipeline is built so that projection is idempotent anyway, giving effectively-once effects without trusting the transport.
1. Ingest
from the transactional outbox — a record and its event commit in one DB transaction, so a crash never loses a fact
2. Validate
every event is checked against the envelope schema and its single-producer claim; a spoofed or malformed event is quarantined, never half-applied
3. Correlate
correlation and causation ids group one logical episode — invitation, pass issued, checked in — into a traceable chain
4. Project
a deterministic projector maps each event type to the twin; an event with no registered projection is ignored, never guessed
5. Reconcile
edge writes, re-deliveries and drift are folded back in so the twin matches the ledger exactly — by rebuild, never by hand-editing
Four invariants
Two-level idempotency
The twin dedupes by event id, so a re-delivered event changes nothing twice. But financial and security effects are also deduped at the authoritative ledger by an idempotency key — the critical rule that stops a duplicated payment event from ever double-crediting anyone.
Invalid transitions are quarantined
The engine owns the legal state machines and rejects an illegal jump at projection time — a maintenance order cannot skip from raised to closed, a pass issued is never treated as a person present. The offending event is quarantined with a reason; a human resolves it at Layer 1.
Bitemporal, as-of truth
Every event carries when it happened in the world and when it was recorded. That lets a committee ask two different honest questions: 'what was the state at T?' and 'what did we believe at T?' — both answered from the immutable ledger plus checkpoints, even after raw events are pruned.
Anti-entropy that rebuilds, never edits
Three cheap tiers detect drift between the twin and the record — a continuous lag check, an hourly xxh64 fingerprint sweep, and a determinism parity rebuild. A mismatch is pinpointed with BLAKE3 Merkle roots and repaired by targeted rebuild, because editing the twin directly would break rebuildability.
Reconciliation without loss
Offline is a state, not a lie. The hardest moment in the architecture is a visitor at the barrier with no network — and it is handled by preserving origin rather than faking sync.
Fail local, first
The gatehouse writes to a durable on-device outbox with the device sequence and a corrected wall-clock, so the guard keeps working with no network — and says so in plain words.
Three clocks, honestly kept
device_seq (order on the device), ingest_seq (order of arrival, assigned by the server) and occurred_at (order in the world). Ordering trusts the server sequence, never a device clock that drifts.
A conflict rule, not a merge
The System of Record wins on business facts; the edge wins on 'this physically happened at the gate at occurred_at.' Both are retained as facts and correlated — never overwritten, never lost, never duplicated.
A modular monolith, not a swarm
The honest architecture for a system whose whole value is transactional integrity: one Ktor service whose modules are namespaces, Postgres with row-level security as the authoritative store and event log, and Timescale for telemetry kept deliberately out of the operational ledger.
Ktor modular monolith
Business divisions are module namespaces inside one service, gated per community by edition and entitlement. Microservices are a premature tax on exactly the consistency the platform is selling.
Postgres + row-level security
Every operational table carries a tenant id; RLS enforces isolation at the database, not the app. A community is a shard, and its data cannot cross the boundary even by a careless query.
Timescale, kept separate
Sensor telemetry lands in hypertables and continuous aggregates, deliberately apart from the append-only event log — so a million temperature readings never bloat or blur the ledger of facts.
The engine's discipline has a floor in law and computer science, and a governance surface that turns those guarantees into something a committee can actually run.
Bring your community onto its own spine.
One gated enclave at a time — identity, money, gatehouse and governance that a committee can actually trust.