The Big Picture

Before you read any single file, build a mental map of where things live. This codebase follows Clean Architecture — a deliberate set of dependency rules that keeps business logic independent of frameworks. We'll cover what each layer owns, the rules that govern them, and the "where does X live?" lookup table you'll come back to often.

Clean Architecture in one paragraph

The codebase is divided into four concentric layers. Domain at the center knows nothing about frameworks, databases, or HTTP. Application wraps Domain with use-cases (commands, queries, interfaces) but still imports nothing concrete. Infrastructure provides concrete implementations of Application interfaces — Azure OpenAI clients, MCP servers, file system access. Presentation is the entry point — console UI, SignalR hub, REST API, MCP server — that wires everything together. Dependencies point only inward.

The most important distinction: .Common vs .Core

Before we get to the layers, there's one naming convention you have to internalize early or you'll spend weeks confused. Every layer has projects whose names end in .Common (and sometimes .AI.Common) — and at least one project that is something else, like Application.Core. They mean very different things.

Throughout this guide, when we say "you'll edit this" we usually mean a .Core project, an infrastructure.<your-domain> project, or a Markdown file in skills/ or agents/. When we say "the harness does X" we mean code in a .Common project that you should treat as a black box — understand it, but don't fork it unless you have a very good reason.

The four layers

Domain

Pure C#. No NuGet dependencies beyond System.*. Defines the language of the problem: AgentManifest, SkillDefinition, ToolDeclaration, WorkflowState, AgentCard, Result<T>, all the strongly-typed config classes. If you can describe a concept on a whiteboard without mentioning a vendor or framework, it lives here.

Application

The "what should happen" layer. CQRS commands like ExecuteAgentTurnCommand, interfaces like IAgentFactory and ISkillMetadataRegistry, FluentValidation validators, MediatR pipeline behaviors, the AIToolConverter that bridges internal tools to Microsoft.Extensions.AI. Application can depend on Domain, but it must never depend on Infrastructure — it only knows interfaces.

Infrastructure

The "how it actually happens" layer. ChatClientFactory talks to Azure OpenAI. FileSystemService reads disk under sandbox rules. RagPipeline coordinates ingestion and retrieval. McpClient connects to external MCP servers. Each Infrastructure project implements one or more interfaces declared in Application.

Presentation

Where execution starts. A "Presentation host" is just a runnable program with a Program.cs. The harness ships several — the full set is in the layer diagram above — and each is a different way of getting a request into the same engine. The four you are most likely to run first:

• Presentation.ConsoleUI — you type at a terminal menu. The simplest entry point, and the one to reach for when debugging.
• Presentation.AgentHub — a SignalR (WebSocket) server, so a browser can stream a conversation token-by-token.
• Presentation.ExecutionApi — a plain REST API. Another system uploads a zipped agent and runs it over HTTP, with no UI involved. See Chapter 17.
• Infrastructure.AI.MCPServer — exposes the harness's own tools to other MCP clients over HTTP. (It lives in an Infrastructure folder for historical reasons, but it behaves as a Presentation host.)

Every one of these runs the same composition root — services.GetServices(...) in Presentation.Common — which calls every layer's Add*Dependencies() extension. That is why a feature you add once shows up in all of them.

The dependency rule, illustrated

Solid arrows are "depends on." The arrow always points inward:

Presentation ──▶ Application ──▶ Domain
     │                ▲
     │                │
     └──▶ Infrastructure ──▶ Application interfaces
                       └────▶ Domain (read-only)

Two things to internalize:

• Infrastructure depends on Application, not the other way around. Infrastructure.AI references Application.AI.Common to get the IChatClientFactory interface — and then provides the concrete class. Application never knows the concrete exists.
• Presentation is the only layer that touches everything. It does the wiring — calls AddDomainDependencies(), AddApplicationDependencies(), AddInfrastructureDependencies(), then builds the service provider.

Where to find anything

Use this table when you know what but not where:

DI registration: the composition root

Every project has its own DependencyInjection.cs with an Add{Layer}Dependencies() extension method. The Presentation layer's services.GetServices(...) calls them in order:

// In Presentation.Common — every Presentation host calls this
services
    .AddDomainCommonDependencies(appConfig)
    .AddDomainAIDependencies(appConfig)
    .AddApplicationCommonDependencies(appConfig)
    .AddApplicationAICommonDependencies(appConfig)
    .AddApplicationCoreDependencies(appConfig)
    .AddInfrastructureCommonDependencies(appConfig)
    .AddInfrastructureAIDependencies(appConfig)
    .AddInfrastructureMCPDependencies(appConfig)
    .AddInfrastructureRAGDependencies(appConfig)
    .AddInfrastructureObservabilityDependencies(appConfig);

When you add a new service, you don't touch the composition root — you add the registration to the relevant layer's DependencyInjection.cs. It gets picked up the next time the host boots.

What's in each Infrastructure project

Infrastructure has the most projects. Here's a quick mental map:

Two rules to internalize

1 · Direction of the arrow

Before you add a project reference, ask: does this point inward? Application → Domain ✓. Infrastructure → Application ✓. Domain → anything ✗. Application → Infrastructure ✗.

The litmus: open .csproj, look at the <ProjectReference> lines. They should always point at a layer the same color or further left (Domain) than the current project's color in the stack diagram above.

2 · Interfaces live with the consumer

If Application.AI.Common needs a chat client, it defines IChatClientFactory in its own Interfaces/ folder. Infrastructure.AI provides the implementation. Don't put the interface in Infrastructure "near the implementation" — that breaks the dependency rule.

Where to go from here