Architecture overview

Switchyard is a local-first modular monolith delivered primarily as one Go binary. The process hosts a daemon, CLI commands, local HTTP/WebSocket and IPC transports, and an MCP façade. A Vue application and thin Tauri desktop shell consume the same application behavior.

The durable operations and local transport note defines the command state machine, restart behavior, event replay, Unix IPC, and browser session handshake introduced by Phase 2.

The project onboarding and manifest resolution note defines the Phase 3 repository trust boundary, evidence pipeline, approval transaction, generated schema, and configuration precedence.

The Docker Compose runtime and native process runtime notes describe the two initial lifecycle drivers, their evidence models, and their ownership limits. The health, log, and resource observability note defines the redaction boundary, rotating storage, cursor replay, health scheduling, degraded-state derivation, metric tiers, and storage-attribution boundary introduced by Phases 7 and 12. The ports, source control, and trusted actions note defines Phase 8 port provenance and reservations, read-only Git observation, action authorization, working-directory containment, and audit recovery. The dashboard alpha note defines Phase 9 routes, server state ownership, command boundaries, degraded behavior, and browser evidence. The agent integration note defines Phase 10 MCP topology, least-privilege discovery, audit identity, provider installers, and failure isolation. The AI-assisted onboarding note defines Phase 11 evidence consent, provider isolation, schema-constrained output, deterministic merge authority, dry-run review, and human-only trust transitions. The workspace and worktree orchestration note defines Phase 13 dependency execution, failure policy, environment isolation, optional local routing, launch recipes, and restart reconciliation. The embedded terminal and agent sessions note defines Phase 14 PTY ownership, typed launch resolution, authenticated binary streams, detach persistence, bounded scrollback, and the user-visible agent metadata boundary. The native desktop shell note defines Phase 15 sidecar attachment, compatibility gates, native adapter ownership, capability isolation, notification transitions, and signed update behavior. The out-of-process plugin architecture note defines Phase 16 discovery, executable trust, JSON-RPC negotiation, capability enforcement, supervision, and local-user security boundaries. The public plugin SDK guide documents authoring and compatibility. The intelligent diagnostics and safe automation note defines Phase 17 bounded evidence, deterministic-first evaluation, provider validation, prompt-injection resistance, action authorization, rate-limited recipes, local feedback, and notification retention. The optional federation guide, signed team configuration guide, and ADR-0016 define Phase 19’s separate peer identity, mutual-TLS authorization, bounded inventory, signed portable policy, encrypted sync, curated metadata, and explicit anonymous-counter consent boundaries.

Process topology

CLI          Browser/Vue          Tauri          MCP clients
 |                |                 |                 |
 +---------- local IPC / loopback HTTP / stdio -------+
                              |
                   transport adapters
                              |
                   application use cases
                              |
                       domain modules
                              |
          focused infrastructure adapter interfaces
               /        |        |        \
           SQLite     Docker   processes   Git/OS

The daemon owns project truth. Clients never call Docker, SQL, or operating system process APIs directly. Tauri/Rust contains packaging and native-shell integration only.

Dependency direction

transport and UI adapters -> application -> domain
infrastructure adapters ----- implement ---> application ports

A domain owns its model, invariants, use cases, persistence interfaces, and adapter contracts. Domain code must not import transport, database, Docker, operating-system command, desktop, or AI-provider packages. A domain cannot read another domain’s tables. Cross-domain behavior uses an explicit application interface or a typed event.

Bounded contexts

Context	Responsibility
catalog	Projects, locations, tags, and trust/approval
manifest	Configuration, overlays, provenance, proposals, schema versions
operations	Durable operations, progress, cancellation, serialization
runtime	Driver contracts, runs, reconciliation, lifecycle execution
observability	Logs, health, events, metrics, and retention
ports	Declarations, reservations, bindings, conflicts, and leases
sourcecontrol	Git repository facts and worktrees
actions	Typed, risk-classified project actions
workspace	Multi-project graphs and coordinated lifecycle
agents	MCP, provider adapters, proposals, sessions, and agent audit
diagnostics	Bounded evidence, deterministic findings, reviewed suggestions, local feedback, alerts, and automation policy
terminal	Owned PTYs, bounded streams, typed interactive launches, and session audit
plugins	External package discovery, executable trust, scopes, supervision, and typed actions
fleet	Authenticated peer identities, bounded inventory, grants, remote operations, and audit
team	Publisher trust, signed portable bundles, restrictive policy, registry metadata, and encrypted sync
telemetry	Explicit consent, fixed anonymous counters, payload preview, delivery, and opt-out deletion
settings	Revisioned local preferences, safe project roots, adapter choices, and restart-effect reporting
platform	OS capabilities without product policy

foundation is limited to stable primitives such as clocks, IDs, event envelopes, pagination, and problem details. It is not a miscellaneous shared code layer. Root packages named utils, common, or helpers are forbidden.

Composition

Construct dependencies explicitly at a small composition root. Interfaces live with their consumer and exist only for a real boundary, alternate adapter, or test seam. Long-running work receives a context, has defined cancellation, and records progress and outcome. Architecture checks enforce dependency rules.

Accepted decisions and their consequences are indexed in docs/adr.