System maps

System Maps

These maps are a navigation aid, not a second architecture. The assembly definitions, scene composition, and tests are authoritative. When a map and code disagree, correct the map in the same change that establishes the intended boundary.

The diagrams use Mermaid: their source stays reviewable in Markdown, renders in the wiki, and can also be read as text in GitHub. Solid arrows mean an existing compile-time or runtime hand-off; dashed arrows mark a deliberately missing MVP connection.

1. Assembly dependency map

The arrows point from an assembly to an assembly it references. Dependencies only point downward: domain logic must not depend on Unity presentation, and the Chemistry core stays headless so it can be tested and later shared by server tooling.

flowchart LR
    Core[Core\ncomposition and shared contracts]
    Chemistry[Chemistry\nheadless simulation]
    Data[Data\ncatalogues and authored definitions]
    World[World\nterrain, chunks, saves, presentation]
    Inventory[Inventory\nbatches and discrete items]
    Industry[Industry\nvessels, machines, networks]
    Player[Player\ninput, movement, interaction]
    UI[UI\nHUD, menus, notebook surfaces]
    Workshop[Voxel Workshop\neditor-only tools]

    Data --> Core
    Data --> Chemistry
    World --> Core
    World --> Data
    Inventory --> Core
    Inventory --> Chemistry
    Inventory --> Data
    Industry --> Core
    Industry --> Chemistry
    Industry --> Data
    Industry --> Inventory
    Industry --> World
    Player --> Core
    Player --> Data
    Player --> Inventory
    Player --> World
    UI --> Core
    UI --> Data
    UI --> Inventory
    UI --> Player
    UI --> World
    Workshop --> Core
    Workshop --> Chemistry
    Workshop --> Data
    Workshop --> World
    Workshop --> Inventory
    Workshop --> Player
    Workshop --> UI

    classDef headless fill:#183c39,stroke:#78dac9,color:#fff
    class Chemistry headless

Industry deliberately has no arrow from Player today. An in-world vessel interaction needs a coordinated player-to-industry seam; it is an explicit MVP decision, not a convenience reference to add casually.

2. The playable matter loop

The chemistry MVP is not a menu simulator. Matter must travel through the world, a player’s hands, and apparatus while retaining enough provenance to explain what happened.

flowchart LR
    Explore[Explore geology] --> Mine[Mine a block]
    Mine --> Grade[Query deterministic\nore grade]
    Grade --> Batch[Material batch\nmass + composition + origin]
    Batch --> Assay[Assay sample\nuncertainty shown]
    Batch --> Charge[Charge apparatus]
    Charge --> Vessel[Vessel solver\nconserved reactions]
    Vessel --> Product[Product, waste, heat, gas]
    Product --> Build[Build better apparatus]
    Build --> Explore

    Assay -. evidence informs .-> Charge
    Vessel -. event facts .-> Journal[After-action journal]
    Journal -. next question .-> Explore

The dashed links are information flows. They must remain truthful: assay uncertainty cannot become false certainty, and a journal sentence may only claim causes supported by recorded observations and event facts.

3. Science must be seen before it is explained

Accurate equations alone do not create discovery. Each consequential run needs a visible change, an instrument reading, or a bounded failure signal before the notebook offers its explanation.

sequenceDiagram
    participant P as Player
    participant A as Apparatus and world
    participant S as Solver
    participant I as Instruments and cues
    participant J as Notebook

    P->>A: Set inputs and run an experiment
    A->>S: Charge, conditions, elapsed time
    S-->>A: Conserved state change and ScienceEvent facts
    A-->>I: Heat, colour, pressure, gas, mass, output
    I-->>P: Player can observe a result
    S-->>J: Bounded facts, uncertainty, significance
    I-->>J: What was actually observable
    J-->>P: "What just happened?" and first-use definitions

Non-negotiable journal rules

1. Observation precedes interpretation. “The vessel glowed orange and pressure rose” is valid after those signals are observable. “An exothermic reaction occurred” requires evidence that supports that inference.
2. Show the limit. A source, model range, calibration, and uncertainty belong beside claims that depend on them. An approximation is useful when it is named and bounded.
3. Expose the next controllable variable. A useful entry turns surprise into a new experiment: temperature, reagent mass, vessel material, pressure relief, or separation method.
4. Never reveal solver-only secrets. The game may compute hidden state, but the player earns knowledge through instruments and repeatable observations.

4. Build evidence map

A build is a chain of evidence, not merely an executable. The relevant gate depends on what has changed; use the narrowest meaningful check during iteration and the full gate before release.

flowchart TD
    Change[Intentional change] --> Scope{What changed?}
    Scope -->|Pure domain logic| Unit[Focused EditMode tests]
    Scope -->|Unity integration| Doctor[Project Doctor]
    Scope -->|Generated assets| Determinism[Generator self-test and golden hashes]
    Scope -->|Server host| Server[dotnet build or publish]
    Unit --> Full[Full EditMode suite]
    Doctor --> Full
    Determinism --> Full
    Server --> Smoke[Server smoke run and status endpoint]
    Full --> PlayerBuild[Platform player build]
    PlayerBuild --> Smoke
    Smoke --> Evidence[Record result, version, known limits]

See BUILD_AND_TEST.md for exact commands and the distinction between a development check and a release gate.