Wiki structure map

This page explains how the wiki is organized, what each page type owns, and why some domains have fewer pages than others.

One domain, one story

Domains follow an outside-in path. Each page answers a distinct group of questions instead of repeating the full content of another page.

Layer	Main question	Content to include	Standard page
1. Overview	What is this domain and where does it fit?	Scope, actors, quick flow, links forward	index.md
2. End-user	What does the user do and see?	Actors, preconditions, happy path, UI states	end-user-view.md
3. Concepts	Which objects, states, and invariants matter?	Terms, lifecycle, rules, boundaries	concepts.md
4. Architecture	How do components and data work together?	UI/API/service, database, queue, external system	architecture.md
5. Codebase	Where does the execution flow live?	Routes, controllers, services, workers, sequences	codebase-flow.md
6. Data links	Where is data read, written, and synchronized?	Tables, projections, events, queues, blobs, providers	data-links.md
7. Common cases	What should I check for a concrete symptom?	Behavior, verification, source anchor, real-world example	common-cases.md
8. References	Which sources can I trace this back to?	Specs, classes, routes, tests, anchors	references.md where available

Reading paths by role

Role	Suggested path
New joiner / Product	System map → Overview → End-user → Concepts
Support / Operations	Overview → End-user → Common cases → Concepts
Engineer	Overview → Concepts → Architecture → Data links → Codebase → References
Architect / PM	System map → Overview → Architecture → References

For a concrete symptom, start with common-cases.md, then move back to Concepts or Architecture when you need the underlying reason.

Domain matrix and intentional exceptions

The exceptions below are content-organization decisions, not accidental gaps. When a domain does not have a separate page type, the information belongs in the closest page and is linked from the Overview.

Domain	Main structure	Exception / interpretation
Subscription	Full standard flow	Includes a codebase flow for lifecycle and billing schedules.
Booking	Full standard flow	Includes focused material for discounts, combined bookings, and reconciliation.
Communication	Full standard flow	Focuses on rendering, delivery, reminders, and campaigns.
Incident Management	Full standard flow	Workflow, permissions, acknowledgement, and signatures are explained through cases.
Platform	Full technical flow	Cross-cutting domain; End-user describes the observable surface while the focus is event/notification/history.
Finance	Overview → Concepts → Architecture → Data links → Common cases	Primarily internal/admin-facing, so it has no separate End-user view.
Payment	Overview → Concepts → Architecture → Data links → Common cases	Focuses on configuration, checkout, providers, and reconciliation; no separate End-user or Codebase page.
Master Data	Overview → Concepts → Architecture → Data links → Common cases	Setup/source-data domain; no separate End-user or Codebase page.
Customer Portal	Overview → End-user → Concepts → Architecture → Data links → Common cases	Customer-facing, but implementation details live in Architecture and Data links; no separate Codebase page.
Dashboard	Overview → End-user → Concepts → Architecture → Data links → Common cases	Read-only query/aggregate domain; no separate Codebase page.
Payroll	Overview → End-user → Concepts → Architecture → Data links → Common cases	Workflow details live in Architecture and Data links; no separate Codebase page.
Staff	Overview → End-user → concepts-architecture.md → Data links → Common cases	Concepts and Architecture are combined because they share one business boundary.
Foundation	Shared foundation documents	Not an independent business domain; covers apps, storage, timezone, database, and shared conventions.

Content rules for every page

• Each page has exactly one H1 and an opening paragraph that answers what it is, who it is for, and why to read it.
• Use H2 for major topics and H3 only for smaller branches or individual cases. Do not add headings for decoration.
• Keep class, route, enum, table, and anchor names in code formatting so engineers can trace them back to the repository.
• Every important business rule should have a Real-world example immediately after it, stating context → purpose → expected result.
• State whether the page describes current implementation, an OpenSpec contract, or a documentation-organization decision.
• When another page owns a topic, summarize it and link to that page instead of maintaining two explanations that can drift apart.
• Page/link catalogs for lookup (Reading path, Related, Pages in this section) should use an ordered list or table; use bullets for unordered facts, notes, and checklists.

Common-case page standard

Each case should use this order so readers can diagnose quickly:

1. Symptom / question — what is the user or support person seeing?
2. Expected behavior / rule — what should the system do, and what must it not do?
3. How to verify — which UI, API, data, queue, or code should be checked?
4. Source anchor — which spec, class, route, test, or related page supports it?
5. Real-world example — context → purpose → expected result.

Cases prioritize running behavior. When the original contract or implementation detail is needed, follow the source anchor linked from the case instead of inferring it from the example.