Skip to content

Architecture.md

Latest commit

 

History

History
322 lines (282 loc) · 19.9 KB

Architecture.md

File metadata and controls

322 lines (282 loc) · 19.9 KB

Architecture Overview

Goal: give humans and agents a fast map of the active DotPilot solution, the current Uno Platform shell, the foundation contracts from epic #11, the workbench foundation for epic #13, the Toolchain Center for epic #14, and the local-first runtime foundation for epic #12.

This file is the required start-here architecture map for non-trivial tasks.

Summary

  • System: DotPilot is a .NET 10 Uno Platform desktop-first application that is evolving from a static prototype into a local-first control plane for agent operations.
  • Presentation boundary: ../DotPilot/ is now the presentation host only. It owns XAML, routing, desktop startup, and UI composition, while non-UI feature logic moves into separate DLLs.
  • Workbench boundary: epic #13 is landing as a Workbench slice that will provide repository navigation, file inspection, artifact and log inspection, and a unified settings shell without moving that behavior into page code-behind.
  • Toolchain Center boundary: epic #14 now lives as a ToolchainCenter slice. ../DotPilot.Core/Features/ToolchainCenter defines the readiness, diagnostics, configuration, action, and polling contracts; ../DotPilot.Runtime/Features/ToolchainCenter probes local provider CLIs for Codex, Claude Code, and GitHub Copilot; the Uno app surfaces the slice through the settings shell.
  • Foundation contract boundary: epic #11 is represented through ../DotPilot.Core/Features/ControlPlaneDomain and ../DotPilot.Core/Features/RuntimeCommunication. These slices define the shared agent/session/tool model and the ManagedCode.Communication result/problem language that later runtime work reuses.
  • Runtime foundation boundary: ../DotPilot.Core/ owns issue-aligned contracts, typed identifiers, grain interfaces, traffic-policy snapshots, and session-archive contracts; ../DotPilot.Runtime/ owns provider-independent runtime implementations such as the deterministic turn engine, Microsoft Agent Framework orchestration client, and local archive persistence; ../DotPilot.Runtime.Host/ owns the embedded Orleans host, explicit grain traffic policy, and initial grain implementations for desktop targets.
  • Domain slice boundary: issue #22 now lives in DotPilot.Core/Features/ControlPlaneDomain, which defines the shared agent, session, fleet, provider, runtime, approval, artifact, telemetry, and evaluation model that later slices reuse.
  • Communication slice boundary: issue #23 lives in DotPilot.Core/Features/RuntimeCommunication, which defines the shared ManagedCode.Communication result/problem language for runtime public boundaries.
  • Runtime-host slice boundary: epic #12 now builds on the epic #11 foundation contracts through the RuntimeFoundation slice, which sequences issues #22, #23, #24, #25, #26, and #27 behind a stable contract surface instead of mixing runtime work into the Uno app.
  • Automated verification: ../DotPilot.Tests/ covers API-style and contract flows through the new DLL boundaries; ../DotPilot.UITests/ covers the visible workbench flow, Toolchain Center, and runtime-foundation UI surface. Provider-independent flows must pass in CI through deterministic or environment-agnostic checks, while provider-specific checks can run only when the matching toolchain is available.

Scoping

  • In scope for the current repository state: the Uno workbench shell, the DotPilot.Core, DotPilot.Runtime, and DotPilot.Runtime.Host libraries, the epic #11 foundation-contract slices, the embedded Orleans host for local desktop runtime state, and the automated validation boundaries around them.
  • In scope for future implementation: provider adapters, durable persistence beyond the current local session archive, telemetry, evaluation, Git tooling, and local runtimes.
  • Out of scope in the current slice: remote workers, remote clustering, external durable storage providers, and cloud-only control-plane services.

Diagrams

Solution module map

flowchart LR
  Root["dotPilot repository root"]
  Governance["AGENTS.md"]
  Architecture["docs/Architecture.md"]
  Adr1["ADR-0001 control-plane direction"]
  Adr3["ADR-0003 vertical slices + UI-only app"]
  Feature["agent-control-plane-experience.md"]
  Toolchains["toolchain-center.md"]
  Ui["DotPilot Uno UI host"]
  Core["DotPilot.Core contracts"]
  Runtime["DotPilot.Runtime services"]
  Host["DotPilot.Runtime.Host Orleans silo"]
  Unit["DotPilot.Tests"]
  UiTests["DotPilot.UITests"]

  Root --> Governance
  Root --> Architecture
  Root --> Adr1
  Root --> Adr3
  Root --> Feature
  Root --> Toolchains
  Root --> Ui
  Root --> Core
  Root --> Runtime
  Root --> Host
  Root --> Unit
  Root --> UiTests
  Ui --> Core
  Ui --> Runtime
  Ui --> Host
  Host --> Core
  Unit --> Ui
  Unit --> Core
  Unit --> Runtime
  Unit --> Host
Loading

Workbench foundation slice for epic #13

flowchart TD
  Epic["#13 Desktop workbench"]
  Shell["#28 Primary workbench shell"]
  Tree["#29 Repository tree"]
  File["#30 File surface + diff review"]
  Dock["#31 Artifact dock + runtime console"]
  Settings["#32 Settings shell"]
  CoreSlice["DotPilot.Core/Features/Workbench"]
  RuntimeSlice["DotPilot.Runtime/Features/Workbench"]
  UiSlice["MainPage + SettingsPage + workbench controls"]

  Epic --> Shell
  Epic --> Tree
  Epic --> File
  Epic --> Dock
  Epic --> Settings
  Shell --> CoreSlice
  Tree --> CoreSlice
  File --> CoreSlice
  Dock --> CoreSlice
  Settings --> CoreSlice
  CoreSlice --> RuntimeSlice
  RuntimeSlice --> UiSlice
Loading

Toolchain Center slice for epic #14

flowchart TD
  Epic["#14 Provider toolchain center"]
  UiIssue["#33 Toolchain Center UI"]
  Codex["#34 Codex readiness"]
  Claude["#35 Claude Code readiness"]
  Copilot["#36 GitHub Copilot readiness"]
  Diagnostics["#37 Connection diagnostics"]
  Config["#38 Provider configuration"]
  Polling["#39 Background polling"]
  CoreSlice["DotPilot.Core/Features/ToolchainCenter"]
  RuntimeSlice["DotPilot.Runtime/Features/ToolchainCenter"]
  UiSlice["SettingsViewModel + ToolchainCenterPanel"]

  Epic --> UiIssue
  Epic --> Codex
  Epic --> Claude
  Epic --> Copilot
  Epic --> Diagnostics
  Epic --> Config
  Epic --> Polling
  UiIssue --> CoreSlice
  Codex --> CoreSlice
  Claude --> CoreSlice
  Copilot --> CoreSlice
  Diagnostics --> CoreSlice
  Config --> CoreSlice
  Polling --> CoreSlice
  CoreSlice --> RuntimeSlice
  RuntimeSlice --> UiSlice
Loading

Foundation contract slices for epic #11

flowchart TD
  Epic["#11 Desktop control-plane foundation"]
  Domain["#22 Domain contracts"]
  Comm["#23 Communication contracts"]
  DomainSlice["DotPilot.Core/Features/ControlPlaneDomain"]
  CommunicationSlice["DotPilot.Core/Features/RuntimeCommunication"]
  RuntimeContracts["DotPilot.Core/Features/RuntimeFoundation"]
  DeterministicClient["DotPilot.Runtime/Features/RuntimeFoundation/DeterministicAgentRuntimeClient"]
  Tests["DotPilot.Tests contract coverage"]

  Epic --> Domain
  Epic --> Comm
  Domain --> DomainSlice
  Comm --> CommunicationSlice
  DomainSlice --> RuntimeContracts
  CommunicationSlice --> RuntimeContracts
  CommunicationSlice --> DeterministicClient
  DomainSlice --> DeterministicClient
  DeterministicClient --> Tests
  RuntimeContracts --> Tests
Loading

Runtime foundation slice for epic #12

flowchart TD
  Epic["#12 Embedded agent runtime host"]
  Foundation["#11 Foundation contracts"]
  Domain["#22 Domain contracts"]
  Comm["#23 Communication contracts"]
  Host["#24 Embedded Orleans host"]
  MAF["#25 Agent Framework runtime"]
  Policy["#26 Grain traffic policy"]
  Sessions["#27 Session persistence and resume"]
  DomainSlice["DotPilot.Core/Features/ControlPlaneDomain"]
  CommunicationSlice["DotPilot.Core/Features/RuntimeCommunication"]
  CoreSlice["DotPilot.Core/Features/RuntimeFoundation"]
  RuntimeSlice["DotPilot.Runtime/Features/RuntimeFoundation"]
  HostSlice["DotPilot.Runtime.Host/Features/RuntimeFoundation"]
  UiSlice["DotPilot runtime panel + banner"]

  Foundation --> Domain
  Foundation --> Comm
  Domain --> DomainSlice
  Comm --> CommunicationSlice
  DomainSlice --> CommunicationSlice
  CommunicationSlice --> CoreSlice
  Epic --> Host
  Epic --> MAF
  Epic --> Policy
  Epic --> Sessions
  Host --> HostSlice
  Policy --> HostSlice
  Policy --> CoreSlice
  HostSlice --> CoreSlice
  MAF --> RuntimeSlice
  Sessions --> RuntimeSlice
  Sessions --> CoreSlice
  RuntimeSlice --> HostSlice
  CoreSlice --> UiSlice
  HostSlice --> UiSlice
  RuntimeSlice --> UiSlice
Loading

Current composition flow

flowchart LR
  App["DotPilot/App.xaml.cs"]
  Views["MainPage + SecondPage + SettingsShell + RuntimeFoundationPanel + ToolchainCenterPanel"]
  ViewModels["MainViewModel + SecondViewModel + SettingsViewModel"]
  Catalog["RuntimeFoundationCatalog"]
  Toolchains["ToolchainCenterCatalog"]
  BrowserClient["DeterministicAgentRuntimeClient"]
  DesktopClient["AgentFrameworkRuntimeClient"]
  Archive["RuntimeSessionArchiveStore"]
  Traffic["EmbeddedRuntimeTrafficPolicyCatalog"]
  ToolchainProbe["ToolchainCommandProbe + provider profiles"]
  EmbeddedHost["UseDotPilotEmbeddedRuntime + Orleans silo"]
  Contracts["Typed IDs + contracts"]
  Grains["Session / Workspace / Fleet / Policy / Artifact grains"]

  App --> ViewModels
  Views --> ViewModels
  ViewModels --> Catalog
  ViewModels --> Toolchains
  Catalog --> BrowserClient
  Catalog --> DesktopClient
  Catalog --> Contracts
  Toolchains --> ToolchainProbe
  Toolchains --> Contracts
  App --> EmbeddedHost
  DesktopClient --> Archive
  DesktopClient --> EmbeddedHost
  EmbeddedHost --> Traffic
  EmbeddedHost --> Grains
  EmbeddedHost --> Contracts
  Traffic --> Contracts
Loading

Navigation Index

Planning and decision docs

Modules

High-signal code paths

Dependency Rules

  • DotPilot owns XAML, routing, and startup composition only.
  • DotPilot.Core owns non-UI contracts and typed identifiers arranged by feature slice.
  • DotPilot.Runtime owns provider-independent runtime implementations and future integration seams, but not XAML or page logic.
  • DotPilot.Runtime.Host owns the embedded Orleans silo, localhost clustering, in-memory runtime state, and initial grain implementations for desktop targets only.
  • DotPilot.Tests validates contracts, composition, deterministic runtime behavior, and conditional provider-availability checks through public boundaries.
  • DotPilot.UITests validates the visible workbench shell, runtime-foundation panel, and agent-builder flow through the browser-hosted UI.

Key Decisions

  • The Uno app must remain a presentation-only host instead of becoming a dump for runtime logic.
  • Feature work should land as vertical slices with isolated contracts and implementations, not as shared horizontal folders.
  • Epic #11 establishes the reusable contract and communication foundation before epic #12 begins embedded runtime-host work.
  • Epic #12 now has a first local-first Orleans host cut in DotPilot.Runtime.Host, and it intentionally uses localhost clustering plus in-memory storage/reminders before any remote or durable runtime topology is introduced.
  • The desktop runtime path now uses Microsoft Agent Framework for orchestration, while the browser path keeps the deterministic in-repo client for CI-safe coverage.
  • #26 currently uses an explicit traffic-policy catalog plus Mermaid graph output instead of ManagedCode.Orleans.Graph, because the public ManagedCode.Orleans.Graph package is pinned to Orleans 9.x and is not compatible with this repository's Orleans 10.0.1 baseline.
  • Epic #14 makes external-provider toolchain readiness explicit before session creation, so install, auth, diagnostics, and configuration state stays visible instead of being inferred later.
  • CI must stay meaningful without external provider CLIs by using the in-repo deterministic runtime client.
  • Real provider checks may run only when the corresponding toolchain is present and discoverable.

Known Repository Risks

  • Provider-dependent validation for real Codex, Claude Code, and GitHub Copilot toolchains is intentionally environment-gated; the deterministic runtime client is the mandatory CI baseline for agent-flow verification.

Where To Go Next