01. System Context

Why This Page Matters

Before a newcomer can reason about classes, services, or state transitions, they need a mental picture of what kind of system this actually is.

This repository is not a generic CRUD desktop app. It is a training-oriented simulation of an industrial inspection workstation. That context explains many later design choices:

• the UI is command-driven rather than document-driven
• the runtime has explicit operational states
• diagnostics and recovery matter as much as happy-path success
• simulator behavior is treated as an infrastructure boundary rather than scattered helper code

What The System Is Simulating

At a high level, the app simulates a wafer-inspection workstation where an operator:

1. connects to a machine
2. loads a recipe
3. homes the stage
4. runs an inspection over ordered scan points
5. watches telemetry, preview frames, and defect counts
6. handles stop, abort, or fault cases
7. reviews run summaries and recent history

That flow is described first in SLICE-001, then extended by:

• SLICE-002 for durable run history
• SLICE-003 for file-backed recipes
• SLICE-004 for diagnostics, recovery, profiles, and richer results

Main Actors

The easiest way to understand system context is to identify the main actors and their responsibilities.

Operator

The operator uses the WPF interface to:

• connect and disconnect
• refresh and load recipes
• home the stage
• start, stop, or abort a run
• acknowledge and recover from faults
• inspect run history and diagnostics

Presentation Layer

The WPF app and view models translate canonical runtime state into something visible and clickable. The UI does not own machine workflow logic.

Relevant files:

• src/InspectionPrototype.App/MainWindow.xaml
• src/InspectionPrototype.Presentation/ViewModels/MainViewModel.cs

Application Layer

This is the real center of the system. It owns:

• command handling
• workflow orchestration
• state transitions
• runtime coordination
• startup hydration
• application abstractions for infrastructure seams

Relevant files:

• src/InspectionPrototype.Application/Services/WorkflowService.cs
• src/InspectionPrototype.Application/Services/AppStateStore.cs
• src/InspectionPrototype.Application/Guards/CommandGuards.cs

Infrastructure Layer

Infrastructure simulates the machine-facing world and file-backed system boundaries:

• machine connection
• motion
• camera streaming
• fault injection
• recipe catalog file access
• run history persistence

This is where the code behaves like a small vendor SDK adapter layer, even though the current implementation is still a prototype simulator.

Domain Layer

The domain project carries the stable nouns used across layers:

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

These types are intentionally small and stable. They give the rest of the system a shared language.

Why The Repo Uses This Shape

The core architectural decision is stated in ADR-001: the application should have one canonical AppState instead of allowing each background component to push state directly into view models.

That choice fits the system context:

• the app has multiple background producers
• the UI is sensitive to cross-thread updates
• machine and workflow semantics must stay consistent
• command availability should be derived from one shared state vocabulary

If this were only a single-screen toy app, that structure would be overkill. In this repo, it is what keeps the simulation understandable.

Design Trade-Offs

What This Design Gets Right

• it keeps runtime truth centralized
• it keeps the UI thinner and easier to reason about
• it creates testable seams around workflow logic and persistence
• it makes the docs-first workflow easier because specs and code share the same state vocabulary

What It Costs

• more explicit state-transition code
• more projection code in the view model
• more up-front structure than a quick demo might seem to need

That trade is reasonable for a teaching repo. The structure is part of what the learner is supposed to study.

Where To Look In Code Next

After this page, a good next step is:

1. read 02. Project and Layer Map
2. open MainViewModel.cs
3. open WorkflowService.cs
4. compare what the UI shows with what the application layer actually owns

Related Lessons

• 11. End-to-End Machine Architecture
• 04. High-Level Machine Architecture
• 14. Architecture Trade-offs in .NET - Real World

Diagram Brief

• Title: Wafer inspection workstation system context
• Purpose: Show the repo as an operator-facing workstation sitting between a human user and simulated machine subsystems plus persistence/configuration boundaries
• Audience: newcomer developer or automation engineer
• Nodes: Operator, WPF App, Presentation Layer, Application Layer, Infrastructure Layer, Domain Contracts, Recipe Files, Run History Store, Simulator Profiles Config, Simulated Machine Subsystems
• Edges: operator interacts with WPF app; WPF uses presentation layer; presentation depends on application state and commands; application uses infrastructure through abstractions; infrastructure reads recipe/config/history files and simulates machine devices; domain contracts are shared vocabulary
• Grouping: Human actor, UI boundary, Core application, Externalized assets, Simulated device world
• Caption: The app is a stateful workstation, not a passive viewer; the application layer sits between the operator and a set of infrastructure-backed machine seams
• Destination file path: docs/diagrams/source/architecture-01-system-context.drawio