How this property/fire demo scales to a real, multi-cloud backend behind a fixed
Vercelfrontend. It is organized around five business
flows and four shared services every flow uses (cross-cutting), with an event-sourced
core so the system is auditable and AI-ready by construction — not by a later ETL pipeline.
Tip: dashed-underlined terms show a ? on hover — click any of them (or any diagram box)
for a plain-language definition.
Looks complex? See the simplified, flow-by-flow view —
each flow as a standalone service (start with the smallest proven stack: Vercel + Cloud Run + Cloud SQL) that
a sealed black box to the others.
📦 How is a product versioned? A product (e.g. HO-3) is an
immutable, effective-dated (each edition applies from a stated date) edition; changing one option makes a new edition (V2) authored as a small diff — only the changed option is stored —, not a
full clone. See it worked end-to-end with real V1/V2 tables, copy-on-write (copy only the parts that change), bitemporal
storage, and a rating worksheet →
How product versioning works ↗
📖 = the full story of that section (what really happens) — opens over the diagram; close to keep exploring.
1 · System context
One platform, five flows, four external services, over a shared event spine.
Container view — actors, the platform, and the services it calls
actor platform flow external serviceclick any box for its definition
⚖️ Assumptions & Rationale — why one platform, not one databaseexpand ▼
Assumption: five flows, two trust boundaries (external customer vs. internal staff), very
different read/write profiles (how often each is read vs. updated).
Rationale: the flows do not share one database — they split by what each job needs from storage — fast updates, an unchangeable log, or analysis —
(transactional / append-only / analytical) and stay joined by the
event-contract spine, not a shared schema.
That is what keeps the system both decomposable and cloud-portable.
2 · Policy lifecycle
Quote → underwrite → price/bind → install → service — and every change appends, never overwrites.
Lifecycle pipeline with the underwriting decision states
approve refer decline async / external
A mid-term endorsement is re-priced using the policy's
boundproduct version
(not the newest), while renewal rolls onto the current one.
Cancellations and
reinstatements append to the same
ledger too.
3 · Data architecture — the event log is the spine
Traditional carriers overwrite a "current policy" row and reconcile nightly. Here the lifecycle is an append-only log; current state is computed from that log.
Event-sourced core with CQRS read models and a governed AI corpus
event / store immutable audit external anchor
⚖️ Assumptions & Rationale — "AI-ready by construction"expand ▼
Traditional: a mutable policy-admin database + nightly batch reconciliation; AI is bolted on later
by copying the analytics warehouse via ETL into a vector store — quarters of pipeline work.
This design: the event log is already the
record of every decision, so the audit trail is
native to it and the AI corpus is a
governed derivative built from it (redacted, with lineage back to event ids) — no separate
ETL. We apply this surgically (lifecycle only) — product drafts and intake scratch stay
plain CRUD (simple create/read/update/delete storage). Not over-engineered; future-proofed where it pays off.
4 · Cross-cutting services
Four contracts the flows depend on — swappable without touching business logic.
Property data prefill ("Groundwork") — pull assessor/parcel,
aerial-imagery AI, loss history, and
replacement cost from the address so the
customer only confirms and fills gaps (FCRA-disciplined).
Full integration spec ↗ — vendor APIs & costs,
call waterfall, storage + refresh criteria, field → provision mapping.
See it live ↗ — the Policy Design page
seeds its provision/option defaults from this service (the ⬡ prefill / 🔒 read-only icons on each field).
Climate cat-model — wildfire / flood / wind
scores per address; its version + as-of date are stored with the policy for reproducibility.
Vision-Language Model — later-stage: extract property
attributes from uploaded photos as suggestions (de-identified first; never added to the policy automatically).
RAG + AI agent — see AI governance below.
5 · AI governance — propose-only, with a hard audit boundary
The standout decision: the LLM never decides. It proposes; a fixed rule — filed with the state regulator — clears (same input, same answer).
RAG + agent loop with the governance boundary as the focal element
governance boundary deterministic rule human / applied
The LLM agent is strictly propose-only; any
auto-clear is a deterministic, filed rule (not model discretion), enabled per geography behind
an approval matrix (a table of who may approve what, per state) with a anti-discrimination monitor,
shadow-mode, and a kill switch. Every proposal and
clearance writes an immutable audit row.
6 · Cloud options & deployment
Same frontend + contracts; two clouds, two sub-options each; a proven blue/green release.
The backend runs on GCP or AWS, each in two production
deployment profiles (Elastic-Serverless
and High-Scale), sharing the event-contract spine,
Terraform IaC, and
keyless CI. Releases use
blue/green on
Cloud Run with seconds-level rollback,
Secret Manager, and multi-region serverless edge.