02. Domain and State Model

Why This Page Matters

This repo is much easier to understand once you separate two kinds of truth:

• stable domain concepts
• live runtime state

Newcomers often mix them together. The codebase is clearer when you do not.

Stable Domain Concepts

The InspectionPrototype.Domain project holds the core nouns:

• Recipe
• ScanPoint
• Frame
• InspectionResult
• Alarm
• RunSummary
• RunTerminalStatus

These are the stable words the rest of the system shares.

That is why they live in their own project. The repo wants one vocabulary for specs, code, and tests.

Live Runtime State

The InspectionPrototype.Application.State namespace holds the current operational snapshot:

• AppState
• ActiveRunState
• WorkflowState
• ConnectionState
• MotionState
• CameraState
• SafetySignals
• DiagnosticsEntry
• SimulatorProfile

This is the runtime truth needed to coordinate the workstation.

Why The Split Exists

The split is a practical design choice:

• domain contracts model business nouns and durable outcomes
• application state models the live machine session

For example:

• RunSummary is the durable story of a completed run
• ActiveRunState is the live, changing snapshot while work is still in progress

That distinction matters because the UI and orchestration need both:

• what is happening right now
• what happened after the run ended

Quick Split Sketch

Domain Contracts                     Application State
----------------                     -----------------
Recipe                               AppState
ScanPoint                            ActiveRunState
Alarm                                WorkflowState
RunSummary                           SafetySignals
RunTerminalStatus                    DiagnosticsEntry
                                     SimulatorProfile

ActiveRunState  ----terminal outcome---->  RunSummary

Read this as:

• the left side holds stable nouns
• the right side holds live runtime truth
• one active run eventually becomes one durable run summary

AppState Is The Canonical Runtime Snapshot

The most important runtime model is:

• src/InspectionPrototype.Application/State/AppState.cs

It includes:

• connection, motion, workflow, and camera state
• safety signals
• stage position
• loaded recipe and recipe catalog
• active run, last run summary, and run history
• active alarms and diagnostics
• latest telemetry and latest frame
• pipeline and operational counters
• simulator profile catalog and selected profile

This is the practical implementation of ADR-001: Use Central App State Store.

Why This Helps A Newcomer

Once you know the split, the repo becomes easier to read:

• if you want the stable nouns, look in Domain
• if you want the current machine truth, look in Application.State
• if you want the rules that act on that truth, look in Application.Services and Application.Guards

This is a much better entry point than reading services first and guessing what the data means.

Practical Reading Order

Read these files in order:

1. src/InspectionPrototype.Domain/Contracts/Recipe.cs
2. src/InspectionPrototype.Domain/Contracts/Alarm.cs
3. src/InspectionPrototype.Domain/Contracts/RunSummary.cs
4. src/InspectionPrototype.Application/State/ActiveRunState.cs
5. src/InspectionPrototype.Application/State/AppState.cs
6. src/InspectionPrototype.Application/State/WorkflowState.cs

That sequence takes you from stable nouns to live runtime truth.

Trade-Offs

What This Design Gets Right

• one shared vocabulary
• clear separation between durable contracts and live state
• easier testing and docs alignment

What It Costs

• newcomers must learn both layers
• AppState becomes broad
• some concepts appear in both a live and terminal form

That cost is acceptable because the app is explicitly about stateful runtime coordination.

Related Pages

• 03. Domain Model
• 04. Workflow and State Model
• Requirements: 02. Domain and State Model

Read Next

The best next page is:

• 03. Architecture Walkthrough

Diagram Brief

• Title: Domain concepts versus runtime state
• Purpose: Show the difference between stable domain contracts and live canonical application state
• Audience: newcomer developer learning the repo vocabulary
• Nodes: Recipe, ScanPoint, Alarm, RunSummary, ActiveRunState, AppState, WorkflowState
• Edges: domain contracts describe stable concepts; AppState aggregates live runtime partitions; ActiveRunState eventually becomes RunSummary
• Grouping: Stable domain concepts, live runtime state, terminal outcomes
• Caption: The repo is easier to learn when you separate what the system is from what the system is currently doing
• Destination file path: docs/diagrams/source/course-02-domain-and-state-model.drawio