LCN Wafer Inspection

Appearance

05. Code Tour, Mistakes, and Exercises ​

If you want to study the runtime in the best order, use this path:

  1. src/InspectionPrototype.Application/State/AppState.cs Start here to understand the full runtime snapshot.
  2. src/InspectionPrototype.Application/Guards/CommandGuards.cs This turns state into command semantics.
  3. src/InspectionPrototype.Application/Services/AppStateStore.cs This shows who owns mutation.
  4. src/InspectionPrototype.Application/Services/WorkflowService.cs This is the center of orchestration.
  5. src/InspectionPrototype.Application/Services/TelemetryPipelineService.cs This explains telemetry coalescing and background consumption.
  6. src/InspectionPrototype.Application/Services/FramePipelineService.cs This explains frame drops, fake defect generation, and active-run updates.
  7. src/InspectionPrototype.Presentation/ViewModels/MainViewModel.cs This shows how the UI projects runtime state safely.

That reading order mirrors the actual runtime story:

  • state
  • guards
  • mutation owner
  • orchestration
  • background pipelines
  • UI projection

Common Mistakes Newcomers Might Make ​

1. Adding Parallel Mutable UI State ​

It is tempting to add a new view-model property and treat it as the real source of truth for a feature.

In this repo, new runtime truth belongs in canonical AppState, then gets projected into the UI.

2. Putting Command Rules In The UI ​

It is tempting to decide button availability with ad hoc conditions in the presentation layer.

In this repo, command legality belongs in CommandGuards, derived from canonical state.

3. Blurring Stop, Abort, and Fault ​

These semantics are intentionally distinct:

  • stop is graceful
  • abort is immediate
  • fault is unsafe and recovery-gated

If a change blurs those meanings, the runtime becomes less believable and less teachable.

4. Ignoring Backpressure ​

Telemetry and frames are not infinite. If a newcomer adds another stream without thinking about bounded channels or drop policy, the design will degrade quickly.

5. Updating WPF Objects From Background Threads ​

The runtime has several background producers. Direct UI updates from those producers would create thread-affinity problems and intermittent bugs.

The dispatch-and-project pattern exists to prevent that.

Exercises For Newcomers ​

  1. Run the app and compare Stop and Abort. Keep WorkflowService.cs open and trace which path produces Stopped versus Aborted.

  2. Inject a critical fault during an active run. Then trace how OnFaultInjected(), AcknowledgeFault(), OnFaultCleared(), and RecoverAsync() cooperate.

  3. Watch pipeline counters during repeated runs. Then inspect TelemetryPipelineService and FramePipelineService to see why drops and coalescing happen.

  4. Read AppState.cs and list which properties are durable outcomes versus live runtime observations. This helps separate coordination state from reporting state.

  5. Pick one command, such as Start Run. Trace it from MainWindow.xaml to MainViewModel, then to CommandGuards, then to WorkflowService.

Diagram Brief ​

  • Title: Runtime study map
  • Purpose: Show a recommended reading and investigation path through the runtime code
  • Audience: newcomer studying the codebase
  • Nodes: AppState, CommandGuards, AppStateStore, WorkflowService, TelemetryPipelineService, FramePipelineService, MainViewModel
  • Edges: each file leads naturally to the next in the study order because it builds on the previous runtime concept
  • Grouping: State, coordination, streaming, projection
  • Caption: A good runtime study path follows responsibility flow, not file-system order
  • Destination file path: docs/diagrams/source/course-04-05-runtime-study-map.drawio

Docs-first project memory for AI-assisted implementation.

LCN Wafer Inspection Prototype