Architecture — Phase 1¶
Purpose. Define how the new framework is built: real C# signatures and diagrams, not policy statements. Where a design departs from legacy behaviour, cite the ADR or defect that justifies it.
Responsibilities. - The layer diagram and dependency rule every module is built against. - The concrete contract for every cross-cutting concern: modules, services, events, configuration, persistence, networking. - The concrete shape of the core gameplay data: characters, items, inventories, ownership. - The generic frameworks gameplay systems are built on: items, interaction, UI.
Dependencies. 00_CONSTITUTION.md and 01_VISION.md for the principles these documents implement; Legacy/ for the behaviour being preserved or deliberately departed from; ADR/ for the decisions being made concrete.
Public API. N/A (documentation only). Code/ now exists, so per
Standards/02_DOCUMENTATION_STANDARDS.md §1
the XML docs in source are the authority on the exact signature of any member, and these
documents are the authority on the design — what the contract is for, what it guarantees,
and why it has that shape. A code sample here that no longer compiles against Code/ is a
bug in one of the two, to be resolved deliberately: neither has been compiled yet, so the
source is not automatically the winner. See
ROADMAP.md § Verification debt.
Future improvements. Per-gameplay-module documents (Economy, Jobs, Crime, Law, Chat,
World, ...) are not part of this folder — they get a README.md in their own
Code/<Module>/, per
Standards/02_DOCUMENTATION_STANDARDS.md §2.
Every module in Code/ now has one. This folder covers the framework layer only: the parts
every gameplay module is built on top of.
Contents¶
| Doc | Answers |
|---|---|
| 00_OVERVIEW.md | The layer diagram, the dependency rule, the verified engine baseline |
| 01_PROJECT_LAYOUT.md | Where does a new file go? |
| 02_MODULE_MODEL.md [KEY] | What is a module, and how does it boot? |
| 03_SERVICE_REGISTRY.md | How does one module call another? |
| 04_EVENT_BUS.md | How does one module observe another without depending on it? |
| 05_CONFIGURATION.md | How does an operator change a number without recompiling? |
| 06_PERSISTENCE.md [KEY] | How is anything saved, and how does it survive a schema change? |
| 07_NETWORKING.md [KEY] | What may a client tell the host, and who is trusted? |
| 08_DATA_MODEL.md | What is a Character, an Item, a Container, a wallet, Ownership, a Door? |
| 09_ITEM_FRAMEWORK.md [KEY] | How is an item defined, and how does it get a behaviour? |
| 10_INTERACTION_FRAMEWORK.md | How does a timed player action work, generically? |
| 11_UI_ARCHITECTURE.md | How does a panel get built and registered? |
| 12_LOGGING_AND_DIAGNOSTICS.md | How does an operator find out what happened? |
| 13_ERROR_HANDLING.md | Exception or result? When does the game refuse to boot? |
| 21_EXTENSION_SURFACE.md | What counts as the extension surface, for ADR-0002's stability revisit trigger? |
[KEY] marks the four documents worth reading before any other: the module contract every gameplay system attaches to, the persistence contract everything saves through, the networking rules every client-facing feature must follow, and the item framework the entire content pipeline is built on.
How to read these¶
Every document carries real C# signatures — interfaces, base classes, worked examples — not prose describing intent. Where an example references a type defined in another document, it's linked rather than redefined, so there is exactly one canonical shape for each concept in this folder.
Citations follow one convention throughout: [D-NN] points to
Legacy/12_DEFECTS_AND_LESSONS.md, [ADR-NNNN] points
to ADR/, and a bare sbox.game link is a verified engine fact — see
00_OVERVIEW.md §4 for the baseline date and the full
verified API index.