#System architecture

TL;DR

• The Check is an append-only event log per Device with a pure deterministic fold — not a mutable row. Everything else (offline, audit, fiscal correction, replay-a-Friday support) falls out of that one decision. Document-level or field-level last-writer-wins silently loses 0.5–2% of check value at a multi-writer Site [estimate], and the operator blames staff theft before he blames us. The writer model, the numbering model, the tenancy key order and the PII split are schema-level: changing them after 20 live Sites costs 9–18 eng-months [estimate].
• One money engine, written once in Kotlin, compiled to JVM for the backend and to Android for the counter. This resolves the only direct contradiction in the research inputs (r05 wanted TypeScript everywhere, r08 wanted Kotlin at the counter). A second implementation is a permanent penny-mismatch bug farm; a TS runtime inside the Kotlin app re-imports the ~5.5 eng-month bridging tax the Kotlin decision exists to avoid [estimate].
• v1 is T0: one Station per Site, counter-service, Android-only. The Coordinator interface, the epoch fencing token and the conflict table all ship in MVP; the LAN peer transport does not. That is the difference between a 17–20 eng-month offline core and a 48–58 one [estimate] — see 07 — Roadmap, Team and Budget.
• Three number spaces, never one: cosmetic Ticket numbers (any Device), Check numbers (Coordinator-leased blocks, gaps legal), Fiscal Document numbers (allocated only by the certified fiscal component, never by our code). Business Day is leased, never stamped from a device wall clock.
• Printers are the only irreversible side effect in the system. Intent-log → send → verify, every job stamped with the Coordinator epoch, never a blind resend. A reconnect storm that double-fires across 200 Sites on one Friday is EUR 10–40k of comped food plus churn [estimate].

Scope of this document: how the system is put together and why. Hardware SKUs and printer/peripheral behaviour live in 03 — Hardware, peripherals and the device fleet; PSP, PCI and fiscal obligations in 04 — Payments, fiscalisation, privacy and security; CRM feature scope in 05 — The CRM Product and Scope Tiers; third-party connectors in 06 — Integrations; effort, sequencing and money in 07 — Roadmap, Team and Budget; the failure modes we accept in 08 — Pros, cons, difficulties and risks.

#1. The stack, stated exactly

Languages the company maintains: Kotlin and TypeScript. Nothing else, unless a Tauri site bridge is ever forced by a fiscal printer (not in CZ).

#2. Context and component map

Trust boundaries. The Device authenticates with a device-bound Keystore key plus a per-Device certificate that the cloud can revoke on next connect. The card never touches us — PAN lives inside the Stripe Reader, we hold only payment_intent_id, the acquirer transaction reference and a nullable par. Guest PII lives in a separate crypto-shreddable store; the financial event log holds guest_id only.

#2.1 Component map (backend modular monolith)

Boundaries are enforced by package visibility and an ArchUnit-style test, not by convention. :domain imports nothing. fiscal is a separately-versioned, slow-release module because certificates bind a named software version — it does not ride the fast app's release train.

#3. Offline-first design

#3.1 Network states and what must keep working

The sales claim is exactly: "orders, kitchen, cash and receipts keep working with no internet; card payments depend on your acquirer." Store-and-forward offline card auth is never built. See 04 — Payments, fiscalisation, privacy and security.

#3.2 Writer model for the Check aggregate

Every Device owns one append-only stream. There is no shared mutable row anywhere in the write path.

Event {
  event_id     UUIDv7        // client-generated, the primary idempotency key
  org_id       UUID          // leading key everywhere, including on the wire
  site_id      UUID
  device_id    UUID
  device_seq   u64           // strictly monotonic per Device, gapless — detects silent loss
  aggregate_id UUID          // check_id
  hlc          (u48 phys_ms, u16 counter, device_id)
  kind         enum
  payload      CBOR          // unknown fields preserved byte-identically
  actor_id     UUID          // Employee; required for audit and Comp authority
  schema_v     u16
}

• Total order across Devices = sort by (hlc.phys, hlc.counter, device_id). Deterministic on every platform.
• fold(events) → CheckState is pure. No clock, no RNG, no I/O. This is what makes the property suite possible and what makes production replay a support tool rather than an aspiration.
• Gap detection is free: a receiver seeing device_seq jump 41 → 43 knows event 42 exists and refuses to fold past it until it arrives.
• Snapshot on close. A 3-hour Check is 40–120 events [estimate]; fold cost is irrelevant. On CloseCheck + fiscal seal we write a frozen CheckSnapshot. On-device retention is 7 days of closed Checks plus all open Checks, hard alarm at 500 MB — a busy Site produces 100–170k events/day [estimate] and 90 days on a 2 GB RK3568 makes month 9 slow at your best customer.

Commands, all carrying a client-generated id: OpenCheck, AddLine, ChangeQty(delta), VoidLine, CompLine, AddOption, ApplyDiscount, RecordPayment, FireTicket, CloseCheck, ReopenCheck. Table-service commands (SetSeat, SplitCheck, MergeChecks, TransferCheck, FireCourse) are v3 — but their conflict rules are written into the fold in MVP, because retro-fitting commutativity into a shipped fold means re-deriving the whole table.

#3.3 Conflict rules — this table is the spec

Two-writer convergence, drawn. In v1/T0 the two writers are the till and a cloud-side action (a manager voiding from back office while the till is offline). In v2 core/T2 they are two Stations on the LAN (two waiters on handhelds only once v3 ships). Same fold, same rules — which is why the rules ship now.

Property P4 — fold(π(events)) == fold(events) for every permutation π respecting per-Device device_seq — is the single most important test in the codebase. It is written by a human before the fold exists, and the fold is accepted only by the property suite, never by review. An AI-written fold that iterates a hash map passes P1–P3 and violates P4 [known, observed].

#3.4 Sync protocol and the idempotency ladder

#3.5 Numbering, Business Day, and the clock

Business Day is leased from the Coordinator, never stamped from a device wall clock. A cheap Android AIO with a dead RTC cell boots with a wrong date; every Check that shift lands in the wrong Daily Close and — in a signing market — on the wrong fiscal day. Rule: |device_wall − coordinator_hlc_phys| > 5 min ⇒ the Device may take orders but may not close or tender, and the fiscal adapter refuses to sign outside its trusted-time threshold. Ordering never uses wall clock (HLC only); durations use SystemClock.elapsedRealtime(); every event carries both occurred_at_wall (for humans and Receipts) and hlc (for ordering), and the server flags deltas >5 min.

#3.6 Exactly-once at the printer

Printers are the only irreversible effect. A duplicate row is fixable; a duplicate ribeye is EUR 3–15 of food [estimate] and a chef who stops trusting the tickets — after which the product is decorative.

Rules that make the diagram true: one print Coordinator per printer; epoch is derived from (persisted_epoch, boot_id, monotonic_start) so a lost fsync after a whole-Site power cut cannot resurrect a duplicate epoch; a claim needs majority ack from reachable peers or cloud confirmation, and in a two-Device venue with no WAN the election loser freezes print dispatch for 60 s; kitchen printers prefer CloudPRNT pull, where the printer acks a specific job id and genuine at-least-once-with-dedupe is achievable; failback is manual or at a service boundary, never automatic; a station failover prints backlogged tickets in fire order with a cap and a "print all / print summary?" prompt, not in queue-drain order. fsync honesty on the certified SKUs is tested in week 3 with a smart PDU at 1,000 random power-cut offsets — not in month 14.

Terminal ownership uses the same fencing epoch: a second collectPaymentMethod arriving at a reader that already has a card presented can cancel the first after the tap and before our result, leaving an authorisation at the PSP with no local Payment. Nightly reconciliation pulls PSP transactions by idempotency key and surfaces orphans. This is base scope.

#4. Canonical data model

Terminology is binding: Customer pays us, Guest eats, Check is the financial container, Ticket is a kitchen instruction, Order is an inbound external order (v2 core onwards). Banned synonyms do not appear in schema, API or UI strings.

#4.1 Architecture invariants (non-negotiable)

#5. Menu and pricing engine

The Menu Snapshot is an immutable, content-hashed, compiled artefact. Editors mutate a draft graph; publish validates, then compiles one denormalised document per (brand, site_group, channel_set, locale_set) with Option trees, price lists, tax rules, availability, layout and image manifest fully resolved. Devices download by content hash and swap atomically. The Device performs zero resolution logic.

A POS screen layout is a separate versioned artefact from the catalog, and a layout must survive its referenced Item being 86'd, unpriced or deleted — the cell renders disabled with a reason. This is the single most common crash class in POS software [known].

#6. Realtime, KDS delivery, and liveness

#7. Analytics pipeline

device events → ws-gateway → api (ingest, projections) → outbox (same txn)
   → worker publishes versioned DOMAIN EVENTS: check_closed, payment_captured,
     daily_close_written, menu_published, voucher_redeemed, campaign_sent
   → [≤200 Sites]  read replica + materialised views, 5–15 min refresh
   → [>200 Sites]  self-hosted ClickHouse, batched 5 s, AggregatingMergeTree pre-aggregates

Domain events, never CDC. Debezium-style logical replication couples the analytics schema to the OLTP schema and replays every column rename as an outage. The outbox already exists for sync; analytics is a second consumer of it.

Everything user-facing reads a metric layer: named, parameterised, tenant-scoped SQL functions with a typed (dimensions, filters, period) signature. The 10 canonical reports are calls into it, not 10 hand-written endpoints — and the same layer is the only surface the NL-analytics agent may touch. Daily Close is the reconciliation anchor: P7 — Daily Close total == Σ closed Check totals == Σ Fiscal Document amounts, to the cent — asserted in CI and monitored in production.

#8. The AI layer and where it plugs in

One ai-gateway. Nothing else in the codebase imports the Anthropic SDK. It owns model routing, prompt versioning + eval harness, request/response logging with PII scrubbing, per-tenant caps, per-feature global spend caps that require a human to raise them, and a global kill switch.

Cost levers in order: prompt caching (Menu Snapshot and metric catalogue as a stable prefix; reads ~0.1×, writes 1.25× [known]; minimum cacheable prefix 512 tokens on claude-opus-5 [verified]), Batch API, effort tuning. Steady state EUR 0.30–1.50/Site/month plus EUR 0.50–3.00 one-off per onboarding [estimate]. Menu ingestion is ~USD 0.53/menu at Opus rates for a ~6-page menu [estimate on token counts, model prices verified] against EUR 200–1,200 of human menu-build labour. AI cost is not a risk; AI correctness is. There is no EU inference pin on the first-party Anthropic API today (us or global only) [known] — mitigation is aggregates and pseudonymous IDs only, DPA + SCCs, and a per-tenant AI kill switch.

#9. Environments, CI, release

CI stages, in order, all blocking: compile → :domain property suite (P1–P11, 10⁵ randomised scenarios per run, seed printed on failure) → golden Menu Snapshot corpus → golden CZ Receipt renderings (byte-diffed) → 500-case promo-rule corpus → tenancy lint (no query outside a transaction, no raw SQL without org_id) → API contract diff → deutan/protan screenshot check on KDS → nightly on-rig soak (4 h, 6 Stations, 3 injected WAN outages, 1 hard power cut, 1 paper-out; pass = all invariants hold, zero duplicate PRINTED, zero divergent CheckState).

Release. Signed build pipeline → cohorts lab → 3 friendly Sites → 10% → 40% → 100%, minimum 24 h soak spanning a dinner service at each step, never advancing Fri/Sat. Freeze Thursday 12:00 → Monday 10:00. Android has no rollback (INSTALL_FAILED_VERSION_DOWNGRADE; uninstall wipes the offline journal), so every risky path ships behind a flag evaluated locally from the signed, monotonically-versioned config bundle — a Device that reconnects to a stale edge must refuse to downgrade the bundle, or your kill switch silently reverts mid-service and you spend two hours believing it didn't work. Forced updates degrade, not block: below min_supported the Device enters grace mode (local order entry and printing continue, sync pauses, non-modal banner); hard block only after min_supported_hard and only outside configured service hours. A recovery build channel (export journal, install a named version, show device ID) is installed at provisioning and updated twice a year.

Support tooling is not optional and lands by M5, before pilot Sites: event-log export → replay into the simulator, force-resync, audited surgical repair, and automatic pseudonymised bundle upload when the divergence detector fires. A divergence alarm without forensics is an alarm you cannot act on.

#10. Decision records

ADR-001 — The Check is an event-sourced aggregate with a deterministic fold. Context: multiple writers (Device + cloud in v1, Devices in v2 core/T2), partitions, and a fiscal requirement that a sealed Check is immutable with corrections as new documents. Alternatives: single-writer + handoff (needs a lock service, needs a leader, circular, and "the manager is in the walk-in holding the lock" is fatal); CRDT (converges but cannot express "void is absorbing" or "payments are additive"; merging two valid documents can produce an invalid one); document/field-level LWW (Firestore/Realm shape). Consequences: the log is the audit journal; conflict semantics are ours and are the product; fold changes are gated by fold_version; every developer must think in commutativity. LWW costs 0.5–2% of check value at a busy Site [estimate] and the operator fires a server before he blames the software.

ADR-002 — One money engine, Kotlin :domain, compiled to JVM and Android. Context: the two research inputs mandated mutually exclusive things (a single TypeScript pricing engine; Kotlin at the counter with zero bridging). Writing the engine twice guarantees permanent penny mismatches at close. Alternatives: run a JS runtime inside the Kotlin app (re-imports ~5.5 eng-months of bridging tax plus a second GC on a 2 GB device — rejected); Rust → WASM with FFI on both sides (+3.5–5.0 eng-months, a third language). Consequences: the backend is JVM/Ktor; the back office is React against a generated OpenAPI client rather than sharing a domain package; AI-assist on backend CRUD drops ~10% [estimate]; hiring shifts to Kotlin, which is fine in Kyiv/Lviv/Prague.

ADR-003 — Android-only Kotlin/Compose at the counter; no browser, no WebView, no iPad in v1. Context: every peripheral and payment SDK in the certified matrix is a Java/Kotlin AAR; the beachhead's hardware is EUR 579–639 Android AIOs. Alternatives: React Native (+~5.5 eng-months of TurboModules and 0.15–0.25/quarter forever); Flutter (same tax, smaller CEE pool, Impeller on Rockchip GPUs unvalidated); PWA (no TCP socket, ever). Consequences: iPad is excluded from v1 through v3; the CMP module seam stays inert (+6–10 eng-months to activate); the reversal trigger is a beachhead move or a failed Kotlin hire in 8 weeks.

ADR-004 — Bespoke device↔cloud sync over HTTPS + WebSocket with our own event envelopes. Context: every managed sync product ships LWW or server-rebase defaults and none does venue-LAN peer sync; MongoDB Atlas Device Sync's deprecation is the cautionary tale. A POS must outlive any sync vendor by 10 years because tax retention says so. Alternatives: PowerSync as pure opaque transport (licence resolved: FSL → Apache-2.0 [verified], saves 2 eng-months); ElectricSQL (read-path only); Firestore/Realm (LWW — disqualified). Consequences: we own resume, backfill, snapshot horizon, tombstones and purge (3.5 eng-months [estimate]). PowerSync remains adoptable later only if the event log stays the wire format.

ADR-005 — T0 single-Station in v1. The Coordinator is an interface, not a box. Context: LAN multi-station is a ~9 eng-month delta and a market question, not an engineering one — it hinges on assumption A8 (under 40% of the CZ beachhead runs 2+ Stations). Alternatives: T2 elected leader in v1 (+9.0 eng-months, election/fencing on the critical path); T3 dedicated Pi hub (cancelled — a Pi with NVMe in a 45 °C cabinet is a truck roll, and correctness must never depend on it). Consequences: the epoch, the lease and the conflict table ship in MVP so T2 is additive; if A8 is false, MVP slips ~3 months.

ADR-006 — Three number spaces; Business Day and Check numbers are leased; Fiscal Document numbers are never ours. Context: conflating these creates a compliance incident, not a bug. Gapless fiscal sequences are a hard requirement in PL/RO/IT/HU [known]. Alternatives: one global sequence (impossible offline); server-allocated on close (breaks N1); wall-clock Business Day (a dead RTC cell puts a whole shift in the wrong Daily Close). Consequences: leases carry epochs and burn unused numbers; the >5 min skew rule blocks tender; ReassignBusinessDay exists as an audited repair but is not the primary mechanism.

ADR-007 — Raster-only printing; raw TCP 9100 at the till, CloudPRNT pull in the kitchen; intent-log + verify queue. Context: CEE bleeds on code pages (CP852/1250/866/1251); the text fast path doubles per-model bugs; a lost HTTP response on a push printer is genuinely ambiguous. Alternatives: text fast path (2–4× faster per ticket, a 40-line kitchen ticket goes ~0.8 s → ~2.5 s [estimate] — reinstate for the first customer who measures it); browser printing (rejected on the socket argument alone). Consequences: one rendering path; every ticket carries a 4-hex job id and a per-Station monotonic ticket number on paper; ambiguity is resolved by a human reading *** POSSIBLE REPRINT ***, which is a legitimate part of an exactly-once protocol when the alternative is silence.

ADR-008 — Semi-integrated payments behind a PaymentTerminal port; explicit unknown state. Context: Stripe/Adyen hold EMV L2/L3 for their whole reader estate; we do zero certification, forever. Alternatives: fully-integrated or app-on-reader (drags PCI scope up to SAQ C and needs a QSA opinion — Apps-on-Devices is v3 at the earliest); building a payfac (~EUR 333M TPV break-even). Consequences: the tip prompt is rendered by the reader, not by us — the CFD shows the total and our ticket reconciles; terminal ownership is epoch-fenced; nightly PSP reconciliation by idempotency key is base scope, not a phase-3 nicety.

ADR-009 — Shared-schema multi-tenancy, org_id leading, RLS as a backstop only. Context: 10,000 Postgres databases is an ops project, not a product; schema-per-tenant makes migration time scale linearly with tenants. Alternatives: DB-per-tenant, schema-per-tenant (both rejected); RLS as the primary mechanism (rejected — SET LOCAL is transaction-scoped, so any query outside a transaction gets whatever the pooled connection last had). Consequences: org_id is the leading column of every composite PK and index, which also makes future app-level sharding mechanical and makes the horizontal-only Hetzner rule cheap; a lint rule enforces both TenantContext and "no query outside a transaction"; accept 3–8% planner overhead on complex joins [estimate], exempt the analytics replica.

ADR-010 — The Menu Snapshot is an immutable, content-hashed, compiled artefact. Context: offline pricing must be bit-identical to server pricing, and the operator must be able to see a diff and roll back. Alternatives: Device-side resolution of the catalog graph (guarantees drift); server-side pricing per keystroke (violates N1). Consequences: publish is a fan-out job; the Device does zero resolution except the time-of-day price-list selection, which is bounded by the Coordinator's price-list epoch; menu correctness becomes testable via golden snapshots.

ADR-011 — Guest PII lives in a separate crypto-shreddable store; the financial log holds guest_id only. Context: GDPR Art. 17 erasure versus tax retention (Art. 17(3)(b) [known]), against an immutable event log. Retrofitting erasure into an immutable log is a 3-month nightmare [estimate]. Alternatives: PII inline in events (unfixable); delete-the-receipt (illegal). Consequences: erasure = crypto-shred the PII record + tombstone guest_id; tombstones replicate over the sync channel with per-Device ack and per-Device revocable keys; rendered ticket bitmaps containing a Guest name are never persisted beyond a 24 h retry window; on-device Guest cache is capped at today's Checks plus loyalty balances for Guests seen today.

ADR-012 — Postgres is the whole job and messaging substrate until 200 Sites. Context: four long-running flows (Daily Close, PSP capture/refund sagas, menu ingestion, nightly exports) do not justify Temporal's operational surface or its USD 100/mo Essentials floor [verified], and LISTEN/NOTIFY genuinely carries fanout to 200 Sites. Alternatives: Temporal/Restate/DBOS; NATS JetStream; ClickHouse from day one. Consequences: transactional outbox + FOR UPDATE SKIP LOCKED workers, the four flows written as explicit state machines (3 eng-weeks [estimate]); each deferred component has a numeric reinstatement trigger rather than a feeling.

#11. What we deliberately do NOT build

#12. Where the architecture is load-bearing on unresolved assumptions

Full assumption register, owners and deadlines: 08 — Pros, cons, difficulties and risks. Effort by domain and the phase gates that consume it: 07 — Roadmap, Team and Budget.