ADR-001: Use Central App State Store

• Status: Accepted
• Date: 2026-04-11

Context

This application will have multiple background producers:

• simulated machine connection and subsystem state
• telemetry streams
• frame streams
• workflow orchestration
• alarms and recovery actions

If each subsystem pushes updates directly into ViewModels, the result will be hard to test, hard to reason about, and prone to cross-thread UI issues. That failure mode is especially likely in a WPF app with async workflows, channels, and a simulator that continuously emits state.

The requirements also need one shared language for:

• command availability
• machine readiness
• workflow transitions
• diagnostics and review
• future AI-generated implementation slices

Decision

Adopt one canonical central AppState model as the source of truth for runtime state.

For the first slice:

• the application layer owns state transitions
• simulator services and background workers do not update ViewModels directly
• ViewModels project read models from the canonical app state
• command guards are derived from canonical state rather than duplicated per screen
• aggregate labels such as "Machine Ready" are derived projections, not separate mutable state

The central state must include, at minimum:

• connection state
• workflow state
• motion state
• camera state
• safety and readiness signals
• current recipe state
• active run state and recent run summary
• active alarms and diagnostics

Consequences

Positive

• UI behavior becomes more predictable.
• Cross-thread update rules become easier to enforce.
• Workflow and command-guard logic can be tested without launching the full UI.
• Future specs and tasks can refer to a stable state vocabulary.

Trade-Offs

• State transition code must be explicit instead of ad hoc.
• Some updates may need projection or reducer-style handlers instead of direct mutation.
• The team must resist adding parallel mutable state in individual ViewModels.

First-Slice Implications

This ADR aligns with the requirements in:

• Section 6.8 Canonical App State Model
• Section 9.3 Architectural Boundaries
• Section 9.5 App State Management
• Section 12 Workflow Requirements

Any implementation slice that changes command guards, readiness rules, or workflow transitions should reference this ADR.