Domains¶
The domains layer is the product spec for each system in Tomoda — one page per feature, written for the engineer who is about to make a change and needs to know the rules. It tells you what states a system can be in, what invariants hold, what cross-domain interactions exist, and what privacy / visibility rules apply.
It is not the story. For the why, see the matching page in Bible.
How to read a domain page¶
Every domain page follows the same skeleton:
- One-line purpose — what this domain is, in a sentence.
- Mental model — the 1–3 key shapes / lifecycles a reader needs to hold in their head before they read anything else.
- Rules / invariants — table form preferred.
- Lifecycle / state machine — prose description of the states a primary object passes through and the transitions between them.
- Cross-domain interactions — what this domain assumes about other domains, and what other domains assume about it.
- Privacy / visibility table — where applicable.
- See also — links to the bible page, the backend service, and (eventually) the UX page.
If a domain page is read out loud to a new engineer, they should come away with the rules they can't break before they touch the code.
Index¶
| Page | Spec for |
|---|---|
| Identity | Account states, sign-up methods, deletion, sessions, profile reads |
| Events | Phases, capacity, visibility, host vs. participant, event-items board |
| Plans | Plan canvas, item board, capture / triage, promotion to an event |
| Friends | Request states, mutual graph, block, location share |
| Discovery | Read aggregation: map, radar, search, location detail, profile card |
| Moments | Ephemeral vs. journaled, expiry, visibility |
| Chat | Room types, disappearing, reactions |
| Presence | Heartbeat, location-share opt-in, two-signal model |
| Payments | Tiers, gating |
| Locations | Place definition, dedup, geocoding tiers |
| Game Rules | Rule expression language — leaves, operators, triggers, scope |
| Stamps | Unlock kinds, scopes, earn path |
| Challenges | Cadence, tz mode, opt-in vs always-on, parent/child, lifecycle |
| Tomoda Collection | Earned curios + stamps surface, visibility, hidden tiers |
When to update a domain page¶
Update the domain when the rules change. New state, new transition, new invariant, new gate, new cross-domain assumption — update the domain page in the same change. Bible pages can lag a little; domain pages can't.
A good rule of thumb: if your PR diff touches a state name, an allowed-value enum, a TTL, a capacity rule, a visibility check, or a cross-domain call — the domain page is the doc that goes with it.