Architecture Decisions.

Status — Live. The 12 accepted ADRs in the chapter below are binding for v1 delivery. New decisions land as new ADRs; existing ones change only by a superseding ADR.

This document records the architecture decisions that are binding for v1 delivery. It is derived from the Stack Specification and the Product Brief; where wording differs, the locked decisions in /spec/ win.

Document
Binding architecture rules for v1

Version
1.0

Updated
2026-05-20

Owner
Yayra - Jude (with engineering)

Audience
Orchestrator agent · engineering · architecture reviewers

ADRs at a glance

The chapter below carries 12 accepted ADRs covering canvas architecture, identity, the data model, monetisation, cultural review, accessibility, the bundle format, and the Phase 0 feasibility gates. Each ADR records its own status, decision, rationale, and consequences.

• ADR-001 — Adopt a Flutter thin-client mobile architecture
• ADR-002 — Standardise the app on feature-first clean architecture
• ADR-003 — Make the canvas engine a single-surface renderer
• ADR-004 — Keep progress local-first and represent fills as bitsets
• ADR-005 — Use anonymous-first identity with server-side promotion
• ADR-006 — Centralise trust-sensitive operations on InsForge
• ADR-007 — Gate premium assets with entitlements and signed URLs
• ADR-008 — Launch with one-off content packs only
• ADR-009 — Treat cultural review as a technical publish gate
• ADR-010 — Use Phase 0 performance gates to decide whether v1 is feasible
• ADR-011 — Adopt the CLRX v1 binary artwork bundle format
• ADR-012 — Bake accessibility into the colouring engine

How to use this doc

These rules are normative for engineering, product, and content-pipeline implementation choices in v1. Any change that affects system boundaries, trust boundaries, the data model, approved dependencies, offline guarantees, monetisation model, or cultural review flow requires a new ADR. After the v1 feature freeze lands, post-freeze architecture changes also run through the Six-Dimension Change Exception process recorded alongside the freeze packet.