Skip to content

Architecture.md

Latest commit

 

History

History
177 lines (149 loc) · 10 KB

Architecture.md

File metadata and controls

177 lines (149 loc) · 10 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 explicit shared roots such as Identifiers, Contracts, Models, Policies, 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.
  • Release website rule: the desktop release path owns the GitHub Pages publish for ../gh-pages/; the site version badge and release download links must resolve from the same CI-derived release version and assets as the GitHub Release.

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"]
  Site["gh-pages static website"]
  Ui["DotPilot Uno desktop shell"]
  Core["DotPilot.Core contracts + shared application code"]
  Unit["DotPilot.Tests"]
  UiTests["DotPilot.UITests"]

  Root --> Governance
  Root --> Architecture
  Root --> Site
  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