Skip to content

Latest commit

 

History

History
174 lines (146 loc) · 9.42 KB

Architecture.md

File metadata and controls

174 lines (146 loc) · 9.42 KB

Architecture Overview

Goal: give humans and agents a fast map of the shipped DotPilot direction: a local-first desktop chat app for agent sessions.

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

Summary

  • Product shape: DotPilot is a desktop chat client for local agent sessions. The default operator flow is: open settings, verify providers, create or edit an agent profile, start or resume a session, send a message, and watch streaming status/tool output in the transcript while the chat info panel surfaces a compact fleet board for live-session visibility and provider health.
  • Presentation boundary: ../DotPilot/ is the Uno Platform shell only. It owns desktop startup, routes, XAML composition, MVUX screen models plus generated view-model proxies, and visible operator flows such as session list, transcript, agent creation, and provider settings.
  • Core boundary: ../DotPilot.Core/ is the shared non-UI contract and application layer. It owns contract-shaped folders such as ControlPlaneDomain and Workspace, plus operational slices such as AgentBuilder, ChatSessions, Providers, and HttpDiagnostics, including the local session runtime and persistence paths used by the desktop app.
  • Startup hydration rule: app startup is allowed to perform one splash-time provider/CLI hydration pass and reuse that provider snapshot for ordinary workspace reads until the operator explicitly refreshes readiness or changes provider preferences.
  • Live-session desktop rule: while a session is actively generating, DotPilot.Core owns the live-session signal and the desktop host may hold a bounded sleep-prevention lock; the shell must show that state so the operator knows why the machine is being kept awake.
  • Extraction rule: large non-UI features start in DotPilot.Core, but once a slice becomes big enough to need its own boundary, it should move into a dedicated DLL that references DotPilot.Core, while the desktop app references that feature DLL directly.
  • Solution-shape rule: solution folders may group projects by stable categories such as libraries and tests, but extracted subsystems must still keep their own files, namespaces, and project-local rules inside their real project directory.
  • Verification boundary: ../DotPilot.Tests/ covers caller-visible runtime, persistence, contract, and view-model flows through public boundaries. ../DotPilot.UITests/ covers the desktop operator journey from provider setup to streaming chat.

Scoping

  • In scope for the active rewrite: chat-first session UX, provider readiness/settings, agent creation, local persistence via SQLite, local folder-backed AgentSession and chat-history storage, deterministic debug provider, transcript/tool streaming, and optional repo/git utilities inside a session.
  • In scope for later slices: multi-agent sessions, richer workflow composition, provider-specific live execution, session export/replay, and deeper git/worktree utilities.
  • Out of scope in the current repository slice: remote workers, distributed runtime topology, cloud persistence, multi-user identity, and external durable stores.

Diagrams

Solution module map

flowchart LR
  Root["dotPilot repository root"]
  Governance["AGENTS.md"]
  Architecture["docs/Architecture.md"]
  Ui["DotPilot Uno desktop shell"]
  Core["DotPilot.Core contracts + shared application code"]
  Unit["DotPilot.Tests"]
  UiTests["DotPilot.UITests"]

  Root --> Governance
  Root --> Architecture
  Root --> Ui
  Root --> Core
  Root --> Unit
  Root --> UiTests
  Ui --> Core
  Unit --> Ui
  Unit --> Core
  UiTests --> Ui
Loading

Operator flow

flowchart LR
  Settings["Settings"]
  Providers["Provider readiness + install actions"]
  AgentCreate["Create or edit agent profile"]
  SessionList["Session list"]
  Session["Active session"]
  Stream["Streaming transcript + status + tool activity"]
  Fleet["Fleet board + live session monitor"]
  Git["Optional repo/git actions"]

  Settings --> Providers
  Providers --> AgentCreate
  AgentCreate --> SessionList
  SessionList --> Session
  Session --> Stream
  Session --> Fleet
  Session --> Git
Loading

Runtime flow

flowchart TD
  Ui["Uno shell"]
  Splash["Startup splash + shell overlay"]
  ViewModels["MVUX screen models + generated view-model proxies"]
  Service["IAgentSessionService"]
  Hydration["Startup workspace hydration"]
  LiveActivity["Session activity monitor"]
  WakeLock["Desktop sleep prevention host"]
  ProjectionStore["EF Core + SQLite projections"]
  SessionStore["Folder AgentSession + chat history"]
  ProviderCatalog["Provider catalog + readiness probe"]
  ProviderSnapshot["Startup-owned provider snapshot"]
  ProviderClient["Provider SDK / IChatClient or debug client"]
  Stream["SessionStreamEntry updates"]

  Ui --> ViewModels
  Ui --> Splash
  Splash --> Hydration
  Hydration --> Service
  Hydration --> ProviderCatalog
  ViewModels --> Service
  Service --> ProjectionStore
  Service --> SessionStore
  Service --> LiveActivity
  Service --> ProviderCatalog
  Service --> ProviderSnapshot
  LiveActivity --> WakeLock
  LiveActivity --> ViewModels
  WakeLock --> ViewModels
  ProviderCatalog --> ProviderSnapshot
  ProviderCatalog --> ProviderClient
  Service --> ProviderClient
  ProviderClient --> Stream
  Stream --> ViewModels
Loading

Persistence and resume shape

sequenceDiagram
  participant UI as Uno UI
  participant Service as AgentSessionService
  participant DB as SQLite projections
  participant FS as Local folder AgentSession/history store
  participant Provider as Provider SDK / Debug Client

  UI->>Service: CreateAgentAsync(...) or UpdateAgentAsync(...)
  Service->>DB: Save or update agent profile
  UI->>Service: CreateSessionAsync(...)
  Service->>DB: Save session + initial status entry
  Service->>FS: Create/persist opaque AgentSession
  UI->>Service: SendMessageAsync(...)
  Service->>DB: Save user message
  Service->>Provider: Run / stream
  Provider-->>Service: Streaming updates
  Service->>DB: Persist transcript entries
  Service->>FS: Persist ChatHistoryProvider state + serialized AgentSession
  Service-->>UI: SessionStreamEntry updates
Loading

Navigation Index

Planning and governance

Modules

High-signal code paths

Review Focus

  • Keep the product framed as a chat-first local-agent client, not as a backlog-shaped workbench.
  • Replace seed-data assumptions with real provider, agent, session, transcript, and durable runtime state.
  • Keep repo/git operations as optional tools inside a session, not as the app's primary information architecture.
  • Keep presentation models long-lived and projection-only so desktop navigation stays memory-hot instead of rehydrating each screen from scratch.
  • Prefer provider SDKs and IChatClient-style abstractions over custom parallel request/result wrappers unless a concrete gap forces an adapter layer.
  • Keep the persistence split explicit:
    • SQLite for operator-facing projections and settings
    • local folder-backed AgentSession plus chat history for agent continuity