03. Architecture Walkthrough

Why This Page Matters

After you understand the product story and the runtime vocabulary, the next question is:

• where does each kind of responsibility live?

This page is the newcomer bridge into the repo structure.

The Five Main Projects

The solution is split into:

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

Each project has a different role.

App

Owns startup composition:

• host startup
• dependency injection
• WPF application bootstrap
• app settings

Presentation

Owns UI projection:

• view models
• observable collections
• UI-facing display values
• command wiring from the UI into application services

Application

Owns behavior and coordination:

• canonical app state
• workflow orchestration
• command guards
• hosted background services
• abstractions for infrastructure seams

Infrastructure

Owns the outside-world details:

• simulator implementations
• file-backed recipe catalog
• file-backed run history store
• sample recipe provisioning
• simulator profile hydration

Domain

Owns stable contracts:

• recipes
• frames
• alarms
• summaries

The Dependency Story

The dependency direction matters:

• App composes everything
• Presentation depends on Application and Domain
• Application depends on Domain
• Infrastructure depends on Application and Domain
• Domain stays at the bottom

That is a clean, teachable structure because:

• the UI does not control the workflow directly
• infrastructure does not define the runtime rules
• domain remains the shared language layer

Quick Layer Map

App
 |
 +--> Presentation
 |      |
 |      +--> Application
 |              |
 |              +--> Domain
 |
 +--> Infrastructure
        |
        +--> Application
        +--> Domain

Read this diagram from top to bottom as “who composes whom” and from bottom to top as “which layer stays stable enough to be reused.”

The Most Important Cross-Cutting Design Choice

The most important architectural rule is:

• the application layer owns canonical state transitions

This comes from ADR-001 and is visible in:

• AppState
• AppStateStore
• WorkflowService
• CommandGuards
• MainViewModel

This one decision explains much of the rest of the code structure.

How To Walk The Code

A good newcomer walkthrough is:

1. open MainWindow.xaml
2. open MainViewModel.cs
3. open WorkflowService.cs
4. open AppState.cs
5. open ApplicationServiceCollectionExtensions.cs
6. open InfrastructureServiceCollectionExtensions.cs

This path shows:

• what the UI exposes
• how the UI forwards commands
• where the runtime rules live
• where state lives
• how the app is composed
• which infrastructure pieces are plugged in

Why This Architecture Works For Teaching

This repo is particularly good for teaching because it does not hide its architecture behind too much framework magic.

You can see:

• where runtime truth lives
• where abstractions are introduced
• where file-backed boundaries are applied
• where simulation begins
• where tests attach

That makes the system easier to learn and easier to explain.

Related Pages

• Architecture Pack
• 02. Project and Layer Map
• 04. Workflow and Async Runtime
• 05. Design Patterns and .NET Techniques

Read Next

The best next page is:

• 04. Workflow and Async Runtime

Diagram Brief

• Title: Newcomer architecture walkthrough
• Purpose: Show the five projects and the reading path a newcomer should take through them
• Audience: newcomer software engineer
• Nodes: App, Presentation, Application, Infrastructure, Domain, MainWindow, MainViewModel, WorkflowService, AppState, JsonRecipeCatalog, JsonRunHistoryStore
• Edges: App composes the rest; Presentation projects Application state; Application coordinates Infrastructure through abstractions; Domain contracts are shared beneath them
• Grouping: Project layers, representative files, recommended reading path
• Caption: The repo becomes readable once you know which project owns startup, projection, orchestration, infrastructure, and contracts
• Destination file path: docs/diagrams/source/course-03-architecture-walkthrough.drawio