# dicklesworthstone/vibe_cockpit architecture

> Architecture diagram of the GitHub repository dicklesworthstone/vibe_cockpit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dicklesworthstone/vibe_cockpit
- Repository: https://github.com/dicklesworthstone/vibe_cockpit

## Overview

#### Purpose and entry points
Vibe Cockpit (`vc`) is a Rust fleet console for AI coding-agent telemetry across local and SSH-reachable machines. Its primary executable entry point is `src/main.rs`; command orchestration and machine-readable output live in `crates/vc_cli/src/lib.rs` and `crates/vc_cli/src/robot.rs`. Operators use CLI, daemon, TUI, web API, or MCP; all non-collection surfaces read persisted state.

#### Configuration and runtime boundary
`vc_config` defines the shared runtime configuration, including database location, enabled collectors, schedules, and machine definitions: `crates/vc_config/src/lib.rs`. Collection is explicitly the external-I/O boundary: it invokes installed tools, reads local files/databases, and opens SSH sessions. Cancellation-aware execution, remote access, and machine registration are separated in `crates/vc_collect/src/executor.rs`, `crates/vc_collect/src/ssh.rs`, and `crates/vc_collect/src/machine.rs`.

#### Collection pipeline
`vc_collect` runs a pluggable set of source adapters, normalizes their results, redacts sensitive values, and writes observations to storage. Collector implementations cover agent tools, GitHub, system probes, SQLite/JSONL sources, and HTTP benchmarking under `crates/vc_collect/src/collectors/mod.rs`, `crates/vc_collect/src/collectors/github.rs`, and `crates/vc_collect/src/collectors/sysmoni.rs`. Scheduling, adaptive polling, and per-collector execution are centered in `crates/vc_collect/src/scheduler.rs`, `crates/vc_collect/src/probe.rs`, and `crates/vc_collect/src/redact.rs`.

#### Durable data plane
`vc_store` is the system-of-record layer backed by DuckDB. It owns schema access and ordered migrations in `crates/vc_store/src/lib.rs`, `crates/vc_store/src/schema.rs`, and `crates/vc_store/src/migrations/001_initial_schema.sql`. Migrations establish tables for telemetry, machines, health, alerts, knowledge, experiments, commands, and retention. The documented DuckDB-to-FrankenSQLite export is one-way; DuckDB remains the read/write source for the application.

#### Analysis, scoring, and operational decisions
`vc_query` transforms stored telemetry into fleet views: health scores/factors, freshness, cost attribution, digests, guardrails, and natural-language query handling. Its architectural core is `crates/vc_query/src/health.rs`, `crates/vc_query/src/nl.rs`, and `crates/vc_query/src/cost.rs`. `vc_alert` evaluates and records alert rules/routes (`crates/vc_alert/src/lib.rs`, `crates/vc_alert/src/routing.rs`); threshold evaluation is the implemented alert condition. Higher-level automation and intelligence are isolated in `crates/vc_guardian/src/autopilot.rs`, `crates/vc_knowledge/src/mining.rs`, and `crates/vc_oracle/src/evolution.rs`.

#### Read and integration surfaces
The interactive terminal console is `vc_tui`, with store-backed data access and screen composition in `crates/vc_tui/src/data.rs`, `crates/vc_tui/src/lib.rs`, and `crates/vc_tui/src/screens/overview.rs`. The read-only HTTP/WebSocket and metrics-facing service is `vc_web` (`crates/vc_web/src/lib.rs`, `crates/vc_web/src/auth.rs`), with a separate Next.js frontend under `web/src/app/page.tsx` and `web/src/lib/api.ts`. Agent integration is provided by a stdio JSON-RPC MCP server in `crates/vc_mcp/src/lib.rs`; versioned robot envelopes and TOON output are handled by `crates/vc_cli/src/robot.rs` and `crates/vc_cli/src/toon.rs`.

#### Primary control flow
`vc daemon` repeatedly executes: load config → schedule local/remote collectors → normalize/redact → persist to DuckDB → derive health/freshness → evaluate threshold alerts. TUI, web, MCP, JSON CLI, and robot commands query the resulting store rather than querying external tools directly. JSON robot contracts are published in `docs/schemas/robot-envelope.json`, `docs/schemas/robot-health.json`, and `docs/schemas/robot-triage.json`.

Main entry points: [`crates/vc_store/src/lib.rs`](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_store/src/lib.rs) (DuckDB system of record), [`crates/vc_config/src/lib.rs`](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_config/src/lib.rs) (Shared configuration), [`crates/vc_cli/src/lib.rs`](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_cli/src/lib.rs) (CLI orchestration), [`crates/vc_collect/src/collectors/mod.rs`](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/collectors/mod.rs) (Source adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Operator Surfaces"]
  node_main["vc executable<br/>Rust entry point<br/>[main.rs]"]
  node_cli["CLI orchestration<br/>Rust CLI<br/>[lib.rs]"]
  node_robot["Robot contracts<br/>output protocol<br/>[robot.rs]"]
  node_tui["Terminal console<br/>TUI<br/>[lib.rs]"]
  node_web["Read-only web service<br/>HTTP/WebSocket API<br/>[lib.rs]"]
  node_frontend["Next.js frontend<br/>web client<br/>[page.tsx]"]
  node_mcp["MCP server<br/>stdio JSON-RPC<br/>[lib.rs]"]
end

subgraph group_collection["Collection Boundary"]
  node_scheduler["Collection scheduler<br/>[scheduler.rs]"]
  node_executor["Cancellation-aware executor<br/>execution runtime<br/>[executor.rs]"]
  node_machines["Machine registry<br/>machine access<br/>[machine.rs]"]
  node_ssh["SSH access<br/>remote I/O<br/>[ssh.rs]"]
  node_collectors["Source adapters<br/>collector plugins<br/>[mod.rs]"]
  node_redaction["Normalize and redact<br/>telemetry pipeline<br/>[redact.rs]"]
end

subgraph group_data["Data and Decisions"]
  node_store[("DuckDB system of record<br/>durable store<br/>[lib.rs]")]
  node_schema["Schema and migrations<br/>database schema<br/>[schema.rs]"]
  node_query["Fleet query layer<br/>derived views<br/>[health.rs]"]
  node_alerts["Threshold alerts<br/>alert evaluation<br/>[lib.rs]"]
end

subgraph group_automation["Automation"]
  node_guardian["Guardian autopilot<br/>automation<br/>[autopilot.rs]"]
  node_knowledge["Knowledge mining<br/>intelligence<br/>[mining.rs]"]
  node_oracle["Oracle evolution<br/>intelligence<br/>[evolution.rs]"]
end

node_config["Shared configuration<br/>runtime config<br/>[lib.rs]"]

node_main -->|"starts commands"| node_cli
node_cli -->|"emits"| node_robot
node_main -->|"loads"| node_config
node_config -->|"collector schedules"| node_scheduler
node_config -->|"machine definitions"| node_machines
node_scheduler -->|"dispatches probes"| node_executor
node_executor -->|"runs"| node_collectors
node_machines -->|"remote sessions"| node_ssh
node_ssh -->|"remote collection"| node_collectors
node_collectors -->|"observations"| node_redaction
node_redaction -->|"persist telemetry"| node_store
node_schema -->|"defines tables"| node_store
node_store -->|"stored telemetry"| node_query
node_query -->|"health and freshness"| node_alerts
node_store -->|"records alerts"| node_alerts
node_store -->|"operational state"| node_guardian
node_store -->|"telemetry history"| node_knowledge
node_store -->|"experiments and knowledge"| node_oracle
node_store -->|"query results"| node_cli
node_store -->|"read state"| node_tui
node_store -->|"read state"| node_web
node_web -->|"API and WebSocket"| node_frontend
node_store -->|"read state"| node_mcp

click node_main "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/src/main.rs"
click node_cli "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_cli/src/lib.rs"
click node_robot "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_cli/src/robot.rs"
click node_config "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_config/src/lib.rs"
click node_scheduler "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/scheduler.rs"
click node_executor "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/executor.rs"
click node_machines "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/machine.rs"
click node_ssh "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/ssh.rs"
click node_collectors "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/collectors/mod.rs"
click node_redaction "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/redact.rs"
click node_store "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_store/src/lib.rs"
click node_schema "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_store/src/schema.rs"
click node_query "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_query/src/health.rs"
click node_alerts "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_alert/src/lib.rs"
click node_guardian "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_guardian/src/autopilot.rs"
click node_knowledge "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_knowledge/src/mining.rs"
click node_oracle "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_oracle/src/evolution.rs"
click node_tui "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_tui/src/lib.rs"
click node_web "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_web/src/lib.rs"
click node_frontend "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/web/src/app/page.tsx"
click node_mcp "https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_mcp/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_robot,node_tui,node_web,node_frontend,node_mcp toneBlue
class node_scheduler,node_executor,node_machines,node_ssh,node_collectors,node_redaction toneAmber
class node_store,node_schema,node_query,node_alerts toneMint
class node_guardian,node_knowledge,node_oracle toneRose
class node_config toneNeutral
```

## Components

### Operator Surfaces

- [vc executable](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/src/main.rs): Rust entry point · `src/main.rs`
- [CLI orchestration](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_cli/src/lib.rs): Rust CLI · Commands and machine-readable output. · `crates/vc_cli/src/lib.rs`
- [Robot contracts](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_cli/src/robot.rs): output protocol · Versioned JSON envelopes and TOON output. · `crates/vc_cli/src/robot.rs`
- [Terminal console](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_tui/src/lib.rs): TUI · Store-backed interactive fleet views. · `crates/vc_tui/src/lib.rs`
- [Read-only web service](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_web/src/lib.rs): HTTP/WebSocket API · Also exposes metrics-facing endpoints. · `crates/vc_web/src/lib.rs`
- [Next.js frontend](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/web/src/app/page.tsx): web client · `web/src/app/page.tsx`
- [MCP server](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_mcp/src/lib.rs): stdio JSON-RPC · Agent integration surface. · `crates/vc_mcp/src/lib.rs`

### Collection Boundary

The only subsystem that performs external I/O.

- [Collection scheduler](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/scheduler.rs): scheduler · Schedules adaptive per-collector probes. · `crates/vc_collect/src/scheduler.rs`
- [Cancellation-aware executor](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/executor.rs): execution runtime · Runs local and remote collection work. · `crates/vc_collect/src/executor.rs`
- [Machine registry](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/machine.rs): machine access · Registers collection machines. · `crates/vc_collect/src/machine.rs`
- [SSH access](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/ssh.rs): remote I/O · `crates/vc_collect/src/ssh.rs`
- [Source adapters](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/collectors/mod.rs): collector plugins · Agent tools, GitHub, system, SQLite/JSONL, and HTTP sources. · `crates/vc_collect/src/collectors/mod.rs`
- [Normalize and redact](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_collect/src/redact.rs): telemetry pipeline · Normalizes observations and removes sensitive values. · `crates/vc_collect/src/redact.rs`

### Data and Decisions

- [DuckDB system of record](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_store/src/lib.rs): durable store · Application read/write source for telemetry and operational records. · `crates/vc_store/src/lib.rs`
- [Schema and migrations](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_store/src/schema.rs): database schema · Ordered migrations define durable domain tables. · `crates/vc_store/src/schema.rs`
- [Fleet query layer](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_query/src/health.rs): derived views · Builds health, freshness, cost, digests, guardrails, and NL queries. · `crates/vc_query/src/health.rs`
- [Threshold alerts](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_alert/src/lib.rs): alert evaluation · Evaluates and records alert rules and routes. · `crates/vc_alert/src/lib.rs`

### Automation

- [Guardian autopilot](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_guardian/src/autopilot.rs): automation · `crates/vc_guardian/src/autopilot.rs`
- [Knowledge mining](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_knowledge/src/mining.rs): intelligence · `crates/vc_knowledge/src/mining.rs`
- [Oracle evolution](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_oracle/src/evolution.rs): intelligence · `crates/vc_oracle/src/evolution.rs`

### Other components

- [Shared configuration](https://github.com/dicklesworthstone/vibe_cockpit/blob/main/crates/vc_config/src/lib.rs): runtime config · Defines database, collectors, schedules, and machines. · `crates/vc_config/src/lib.rs`

## Connections

- vc executable → CLI orchestration: starts commands
- CLI orchestration → Robot contracts: emits
- vc executable → Shared configuration: loads
- Shared configuration → Collection scheduler: collector schedules
- Shared configuration → Machine registry: machine definitions
- Collection scheduler → Cancellation-aware executor: dispatches probes
- Cancellation-aware executor → Source adapters: runs
- Machine registry → SSH access: remote sessions
- SSH access → Source adapters: remote collection
- Source adapters → Normalize and redact: observations
- Normalize and redact → DuckDB system of record: persist telemetry
- Schema and migrations → DuckDB system of record: defines tables
- DuckDB system of record → Fleet query layer: stored telemetry
- Fleet query layer → Threshold alerts: health and freshness
- DuckDB system of record → Threshold alerts: records alerts
- DuckDB system of record → Guardian autopilot: operational state
- DuckDB system of record → Knowledge mining: telemetry history
- DuckDB system of record → Oracle evolution: experiments and knowledge
- DuckDB system of record → CLI orchestration: query results
- DuckDB system of record → Terminal console: read state
- DuckDB system of record → Read-only web service: read state
- Read-only web service → Next.js frontend: API and WebSocket
- DuckDB system of record → MCP server: read state