API architecture diagrams
A visual map of Coven's local socket API: route topology, compatibility handshake, errors, event cursors, live control, launch lifecycle, and daemon authority.
1 min read
Last updated: 2026-05-24
This page collects the API architecture diagrams that live across the Coven source docs and makes them visible from the docs website in one place. Use it as the visual companion to Coven Local API, Client Integration, Session Lifecycle, Authentication and local access, and Safety Model.
| Diagram | Source doc | Purpose |
|---|---|---|
| API route topology | docs/API.md | Shows the local Unix socket, /api/v1 router, and current endpoint families. |
| Compatibility handshake | docs/CLIENT-INTEGRATION.md | Shows how clients fail closed before using sessions, events, or actions. |
| Structured error envelope | docs/API-CONTRACT.md | Shows how parse, routing, validation, lookup, and runtime failures become stable error codes. |
| Incremental event reads | docs/API-CONTRACT.md | Shows afterSeq cursor pagination and crash-safe resume behavior. |
| Session launch lifecycle | docs/SESSION-LIFECYCLE.md | Shows daemon validation, PTY spawn, event persistence, and terminal status updates. |
| Daemon authority boundary | docs/ARCHITECTURE.md / docs/SAFETY-MODEL.md | Shows why clients are UX layers and the Rust daemon owns enforcement. |
Route Topology
The public v0 contract is local HTTP over the user's Unix socket. The route prefix is /api/v1; legacy unversioned aliases are early-MVP compatibility only.
Compatibility Handshake
Clients should use GET /api/v1/health before assuming response shapes from any other route. apiVersion: "coven.daemon.v1" is the contract guard; covenVersion is diagnostics metadata.
Structured Error Envelope
All failures return a structured envelope. Clients should branch on error.code, not on message text.
Incremental Event Reads
Events are append-only and use monotonic seq values. Persisting nextCursor.afterSeq lets clients resume event reads after a client crash or daemon restart.
Live Session Control
Live input and kill are accepted only for daemon-verified live sessions. Completed, failed, killed, archived, or orphaned sessions are replay/log surfaces.
Session Launch Lifecycle
Launches are project-scoped. The daemon canonicalizes the project root and working directory, validates the harness id, inserts the session record, spawns the harness with argv APIs, then persists output and exit events.
Daemon Authority Boundary
Clients may validate for UX, but daemon validation is the enforcement boundary. Unknown API versions, unsupported harness ids, invalid session ids, unknown action ids, and outside-root working directories fail closed.
Last updated on