04. UI and Technical Requirements

Back to Requirements Hub

This page covers original Sections 8-10.

8. User Interface Requirements

The UI should prioritize operational clarity over visual polish.

8.1 Main Operator Screen

The system should provide a main screen showing:

• current machine state
• connection status
• current recipe
• stage position
• run progress
• defect count
• active alarms
• live preview area
• operator actions such as connect, home, start, stop, abort, acknowledge, and recover or reset

8.2 Diagnostics View

For the first slice, the system must provide a diagnostics-oriented surface showing:

• subsystem states
• recent log/timeline entries
• raw telemetry values
• injected fault controls
• pipeline or queue metrics later

A dedicated diagnostics screen is optional in the first slice. A docked pane or embedded diagnostics panel is acceptable.

8.3 Command Availability

UI commands must reflect machine state and workflow state.

Command guards must be derived from the canonical app state rather than duplicated ad hoc inside individual views.

Examples:

• Start should not be allowed when disconnected
• Move or run should not be allowed before homing
• Some commands should be disabled during active fault conditions

8.4 UI Responsiveness

The UI must remain responsive while:

• telemetry is streaming
• frames are being processed
• homing is running
• inspection workflow is active
• faults are raised or recovery occurs

9. Technical Requirements

9.1 Platform and Stack

The project must use:

• .NET 10
• WPF
• Microsoft.Extensions.Hosting
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging
• CommunityToolkit.Mvvm
• System.Threading.Channels
• xUnit for tests

9.2 Project Structure

The solution should follow these main projects:

• InspectionPrototype.App
• InspectionPrototype.Presentation
• InspectionPrototype.Application
• InspectionPrototype.Domain
• InspectionPrototype.Infrastructure
• InspectionPrototype.Tests

9.2.1 Project Dependency Rules

The intended dependency direction for the first slice is:

• InspectionPrototype.App composes WPF startup, host wiring, dependency injection, and logging
• InspectionPrototype.App may reference Presentation, Application, and Infrastructure
• InspectionPrototype.Presentation may reference Application and Domain, but must not reference Infrastructure
• InspectionPrototype.Application may reference Domain, but must not reference Presentation
• InspectionPrototype.Infrastructure may reference Application and Domain, but must not reference Presentation
• InspectionPrototype.Domain must not reference any other project layer
• InspectionPrototype.Tests may reference the layers needed for verification

9.3 Architectural Boundaries

The codebase must follow these principles:

• ViewModels stay thin
• UI does not orchestrate workflows
• UI does not call simulator internals directly
• application layer coordinates machine behavior
• domain layer contains core machine and run concepts
• infrastructure contains fake vendor SDK and simulator behavior
• state changes flow in a controlled way, not through ad hoc event spaghetti
• central application state has a single owned mutation path

9.4 Vendor SDK Boundary

The simulator must be presented as a vendor-like SDK behind interfaces.

The rest of the application should depend on abstractions, not simulator internals.

This boundary is important because it teaches real integration design and keeps the architecture believable.

9.5 App State Management

The system should use a central application state approach so that:

• UI projection is predictable
• state changes are observable
• multiple background producers do not update the UI directly
• behavior is easier to test and reason about

For the first slice:

• there must be one application-state service or store that owns mutation of the canonical app state
• reducers, commands, or equivalent state transition handlers must be explicit and testable
• command guards must be implemented against canonical state, not inferred separately in each ViewModel

9.6 Streaming Pipelines

Telemetry and frame streaming should be implemented using bounded channels or equivalent explicit buffering mechanisms.

The design must prevent:

• uncontrolled memory growth
• tight coupling between producer and consumer
• UI thread overload from raw event storms

The buffering policy for each stream must be explicit:

• telemetry may be coalesced to latest-value behavior when consumers lag
• frame preview streaming should prefer recent frames over stale backlog when consumers lag
• dropped or coalesced items should be measurable through counters, diagnostics, or logs

9.7 Async and Threading

The system must use async and cancellation correctly.

The design must make thread ownership clear:

• UI updates occur on the UI thread
• machine simulation and processing run off the UI thread
• blocking calls on the UI thread must be avoided

9.8 Cancellation

Long-running operations must support cancellation where appropriate, including:

• connection attempts
• homing
• moves
• inspection runs
• streaming loops

9.9 Logging

The system must use structured logging and produce meaningful operational messages.

9.10 Testability

Core logic must be testable without launching the full UI.

This includes:

• workflow transitions
• command guards
• fault handling
• simulator behaviors where practical
• cancellation and stop/abort behavior

For the first slice, automated tests must at minimum cover:

• start preconditions and command guards
• distinct terminal behavior for stop versus abort
• critical fault transition to Faulted
• bounded streaming behavior or explicit backpressure policy at the application boundary

10. Non-Functional Requirements

10.1 Responsiveness

The system should remain responsive during continuous telemetry, frame streaming, and long-running workflows.

10.2 Predictability

State transitions and command availability must be deterministic and understandable.

10.3 Observability

The system should expose enough information to understand what it is doing and why.

10.4 Maintainability

The codebase must be organized so that future feature slices can be added incrementally by AI tools and human review.

10.5 Realism

Even though it is a prototype, the simulator should include realistic delays, constraints, and failure modes.

10.6 Simplicity

The system should avoid unnecessary frameworks and abstraction layers. The architecture should be clean, but not overengineered.