05. Runtime Sequences

Why This Page Matters

Static diagrams are useful, but this system is ultimately about motion over time:

• a command starts work
• services coordinate asynchronous operations
• state updates ripple into the UI
• terminal summaries and diagnostics record what happened

That is why sequence-style explanations are especially valuable in this repo.

This page focuses on two sequences a newcomer should understand early:

1. start-run
2. fault and recovery

Sequence 1: Start-Run

The Start Run button may look simple in the UI, but the underlying sequence is deliberately structured.

At a high level:

1. the operator clicks Start Run
2. MainViewModel forwards the command to IWorkflowService
3. WorkflowService.StartRunAsync() checks current state and claims the active run slot
4. the service updates canonical app state into Preparing
5. the run loop begins on background work
6. motion, camera, telemetry, and defect-result behavior advance during the run
7. the service maps the termination reason to a terminal run summary
8. the summary updates LastRunSummary and RunHistory
9. the UI reprojects the new state automatically

Relevant files:

• src/InspectionPrototype.Presentation/ViewModels/MainViewModel.cs
• src/InspectionPrototype.Application/Services/WorkflowService.cs
• src/InspectionPrototype.Application/State/ActiveRunState.cs
• src/InspectionPrototype.Domain/Contracts/RunSummary.cs

Quick Start-Run Sketch

Operator
   |
   v
MainViewModel -> WorkflowService -> AppState(Preparing)
                         |
                         v
                    Run loop starts
                         |
         +---------------+----------------+
         |               |                |
         v               v                v
      Motion          Camera         Pipelines / Results
         \               |                /
          \              |               /
           +-------------+--------------+
                         |
                         v
                RunSummary + RunHistory
                         |
                         v
                    UI reprojects state

Why The Sequence Looks This Way

The code avoids a common mistake: leaving the workflow in a startable state while background work is only “about to” begin.

That is why the service claims the run slot and transitions state before the deeper runtime work unfolds. It reduces race conditions such as double-start behavior.

Sequence 2: Fault And Recovery

The fault path is equally important because it teaches the difference between:

• unsafe condition
• operator acknowledgment
• clearance of the underlying condition
• explicit recovery

At a high level:

1. the operator injects a fault
2. the fault injector raises an event
3. WorkflowService appends an alarm, transitions to Faulted, and cancels active work if needed
4. the UI shows the active alarm and blocked runtime state
5. the operator acknowledges the fault
6. the operator or engineer clears the underlying condition
7. recovery remains blocked until the explicit Recover action is used
8. WorkflowService.RecoverAsync() returns the system to a usable non-faulted state

Relevant files:

• src/InspectionPrototype.Infrastructure/Simulator/SimulatorFaultInjector.cs
• src/InspectionPrototype.Application/Services/WorkflowService.cs
• src/InspectionPrototype.Application/Guards/CommandGuards.cs
• src/InspectionPrototype.Presentation/ViewModels/AlarmViewModel.cs

Quick Fault-Recovery Sketch

Inject Fault
     |
     v
FaultInjector -> WorkflowService -> AppState(Faulted)
                        |
                        +--> Active alarm added
                        +--> Active work canceled
                        +--> Commands blocked

Acknowledge
     |
     v
Alarm marked seen
     |
     v
Unsafe condition may still be active

Clear Fault Condition
     |
     v
Critical fault removed
     |
     v
Recover
     |
     v
WorkflowService -> AppState(Idle or Ready)

Why These Sequences Matter Architecturally

These flows show the real value of the repo’s structure:

• the UI stays thin
• the application layer owns sequencing
• infrastructure raises events or satisfies abstractions
• the canonical app state remains the projection source

If these sequences were driven from the UI directly, the system would be much harder to test and much easier to desynchronize.

Trade-Offs

Benefits

• complex flows become inspectable
• concurrency issues are easier to reason about
• terminal behavior is centralized
• the system becomes more teachable

Costs

• runtime orchestration files grow in importance
• sequence reasoning requires learners to follow state plus async control flow

That complexity is worth showing, because it mirrors real production desktop systems more closely than a simplistic example would.

Suggested Hands-On Pairing

Read this page together with:

• Scenario 01: Happy Path Inspection Run
• Scenario 03: Fault Injection and Recovery

Those scenario pages let the learner see the sequence externally, while this page explains it internally.

Related Lessons

• 01. Async Await Deep Dive
• 04. CancellationToken in Production - Real World
• 11. Background Processing in .NET - Real World
• 12. Observability in .NET Systems - Real World

Diagram Brief: Start-Run Sequence

• Title: Start-run sequence
• Purpose: Show how a run starts, claims ownership, progresses, and ends with a persisted summary
• Audience: newcomer developer learning runtime orchestration
• Nodes: Operator, MainWindow, MainViewModel, WorkflowService, AppStateStore, MotionController, CameraController, TelemetryPipeline, FramePipeline, RunHistoryStore
• Edges: operator triggers command; view model calls workflow service; service claims run slot and updates state; motion/camera/pipelines produce runtime activity; terminal summary is created and stored; UI reprojects the new state
• Grouping: UI command path, application orchestration, background producers, persistence
• Caption: A run is a coordinated sequence across services, not a direct UI-to-device shortcut
• Destination file path: docs/diagrams/source/architecture-05-start-run-sequence.drawio

Diagram Brief: Fault And Recovery Sequence

• Title: Fault and recovery sequence
• Purpose: Show the transition from active fault to acknowledgment, clearance, and explicit recovery
• Audience: newcomer developer or automation engineer learning safety-oriented state handling
• Nodes: Operator, MainViewModel, FaultInjector, WorkflowService, AppStateStore, Alarm List UI, CommandGuards
• Edges: fault injection triggers event; workflow service appends active alarm and transitions to faulted; operator acknowledges; fault is cleared; command guards still block recovery-sensitive commands until explicit recover; recovery updates state and diagnostics
• Grouping: Fault occurrence, operator acknowledgment, condition clearance, recovery
• Caption: Recovery is intentionally stricter than acknowledgment so the system models unsafe conditions more honestly
• Destination file path: docs/diagrams/source/architecture-05-fault-recovery-sequence.drawio