Architecture decisions

An Architecture Decision Record (ADR) captures one decision that is expensive to reverse: its context, the choice, and the consequences. ADRs are never edited after acceptance except to mark them Superseded by NNNN; a changed mind is a new ADR.

Create one with /new-adr or by copying the template to the next free number.

#	Decision	Status
0001	One monorepo; games independent through a contract	Accepted
0002	Games run in a sandboxed iframe on their own origin	Accepted; in production on games.toheplay.io.vn since 0039, 0040
0003	Backend: .NET 10 modular monolith + PostgreSQL	Accepted
0004	Identity: households, adult accounts and child profiles	Superseded by 0023
0005	Offline first: games keep working without the API	Accepted; a ranked run needs the network to start, since 0030
0006	Docs as code, rendered by Starlight, written for humans and agents	Accepted
0007	Immutable versioned game builds + a catalog indexed by the API	Accepted
0008	Technology baseline	Accepted; game default amended by 0012
0009	Local environment: 47xx ports, compose, isolation	Accepted
0010	Environments: development and UAT on the homelab	Accepted; production decided by 0021; UAT deploys a uat- tag since 0041
0011	Sign in with username and password first; OAuth later	Accepted; invites removed by 0023; email sign-in by 0024; manage PIN and step-up by 0025; OAuth by 0026
0012	Phaser 4 and the game kit are the default way to build games	Accepted
0013	Light and dark themes from shared design tokens	Accepted
0014	Live scores for runs that last across sittings	Accepted; boards follow the server’s clock and trust since 0029; ranked runs verified when they end since 0030
0015	Collect technical telemetry from players’ devices, first-party and visible	Accepted; the switch is the account’s since 0023
0016	Online rooms for turn-based games, refereed by the API with the game’s own rules	Accepted; the seed’s secrecy amended by 0017; household tables are account tables since 0023; calendar weeks and the two-people rule since 0029; invitations reach beyond the account by ID since 0033
0017	Replay finished online hands with the game’s own rules module	Accepted; a deleted player’s seat shows as such since 0034
0018	Every game opens on its own main menu and has one menu button	Accepted; the screens amended by 0019 and 0020
0019	Give every game a title screen, a HUD and a pause that holds, from the kit	Accepted; stages amended by 0020
0020	Give every game a menu stage and a play stage	Accepted
0021	Release production through the Tò He Helm chart; one set of images configured at run time	Accepted; promotion follows a prod- tag since 0041; HSTS for subdomains and the site to serve only the docs by 0042
0022	Send transactional email through an outbox and an SMTP relay	Accepted
0023	Accounts own their profiles; every profile has a public ID and a free name	Accepted; inviting by ID since 0033; deletion and retired IDs since 0034; the name filter since 0035
0024	Email identifies an account; a code opens only the attempt it was sent for	Accepted; email change behind step-up by 0025; signing up may need an invite code, or be closed, by 0028
0025	Step up in two levels; sign up at 16 or older, accepting the terms	Accepted
0026	Sign in with Google, GitHub or an OpenID Connect issuer; link a provider by its subject, after proof	Accepted; a configured provider can be switched off by 0028
0027	Run the platform from an admin console on the hub’s origin; roles grant permissions; a setup token makes the first owner	Accepted; the console frames the games origin to watch a ranked run since 0032; the audit log keeps a year since 0034; the console moved to its own host, with a sign-in of its own, by 0042
0028	Switch sign-in methods and registration at run time; communities join by invite code	Accepted; the proof-of-work switch since 0037
0029	One integrity engine gives every result a trust level from its evidence; boards read by trust	Accepted; a result left to people keeps its value since 0031; a deleted profile’s results go with their decisions since 0034
0030	Ranked runs: the server deals the seed, the game hands in its moves, the server replays them	Accepted; a ranked game also plays a run back to watch since 0032
0031	People decide what the engine held: the console’s review, and profiles hidden from public boards	Accepted
0032	Watch a ranked run in the game itself, in the admin console	Accepted
0033	Invite a profile to a table by its ID, as its owner allows; a child is never found from outside	Accepted
0034	Delete a profile at once and an account after seven days, with everything of them; the append-only logs get one way out each	Accepted; after its seven days an account waits for an admin since 0038
0035	Refuse names with an offensive word, matched as people write it; an owner renames a profile five times a day	Accepted
0036	Export metrics for Prometheus with prometheus-net, on a port of the API’s own	Accepted
0037	A self-hosted proof-of-work before a code by email, behind a switch of the console	Accepted
0038	After its seven days, an account waits for an admin to delete it; nothing deletes it by itself	Accepted
0039	Serve games from a registrable domain of their own	Accepted; all of Tò He on toheplay.io.vn since 0040
0040	Run all of Tò He on toheplay.io.vn, the games one level below the hub	Accepted; hosts and paths laid out by 0042
0041	Promote one build through the environments by tag; production runs only what ran on UAT	Accepted
0042	Lay out Tò He by trust: one domain, a host per trust boundary, a path per component	Accepted
0043	Every player is a profile of this device or of an account; the highest level any source needs is asked for	Accepted; arrives in steps (I1, I2)