Circuit Breaker

The docs/design/approved-ui/ directory contains the official implementation plans for the Circuit Breaker user interface. These plans serve as the record of design decisions and visual baselines for the ten core UI workflows.

Key architectural decisions include:

• Unified Navigator: A single overlay that replaces both the top-right Routes dropdown and the existing command palette, providing a unified keyboard/search experience.
• Theme Awareness: All approved surfaces must be theme-aware (e.g., supporting Gruvbox or other palettes) while preserving composition, density, and semantic status distinctions.
• Service Integration: New UI workflows must use existing services and components. Speculative frameworks or generic workflow engines are prohibited.
• Access Tokens: The redesign reuses the INC-14 admin API and route, focusing on presentation, search, risk framing, and HTTP auditing rather than creating a new credential subsystem.

The cb-agent production-readiness specification defines the criteria for a signed agent to be considered stable for deployment. Key operational requirements include:

Lifecycle Operations

An agent must be capable of being installed, enrolled, operated, upgraded, rolled back, revoked, and removed across supported host and network matrices.

Network and Scope Safety

• Network Scope Accuracy: The agent must respect network boundaries (multi-NIC, VLAN, bridge, VPN, Docker, IPv4/IPv6). Disallowed scopes must never be scanned or probed.
• Remote Site Resilience: The agent must function behind NAT (no inbound ports) using realistic DNS/TLS, handling packet loss, latency, DHCP changes, reboots, and intermittent WAN connectivity.

Resource Constraints

Agents must enforce ceilings for:

• Idle CPU/RAM
• Discovery load
• Disconnected-spool disk usage (must fail gracefully at bounds).

Operator Safety and UI

• State Visibility: The UI must clearly communicate last-seen freshness, clock skew, offline/revoked/disabled status, stale telemetry, pending config/updates, and degraded capability states.
• Actionable Errors: Installation and enrollment errors must be actionable without exposing sensitive keys or protocol internals.
• Explicit Confirmation: High-risk operations such as revocation, uninstallation, scope expansion, remote-probe/discovery grants, and update dispatch require explicit confirmation and audited records.

The project is organized as a modular monolith with the following primary directory structure:

• apps/backend/: FastAPI + SQLAlchemy + Pydantic (Python 3.12). Contains src/app/ (api, services, db, core, workers, schemas, integrations, middleware, jobs), tests/ (pytest), and migrations/ (Alembic).
• apps/frontend/: React + Vite + Tailwind (JSX/JS). Contains src/ (pages, components, hooks, api, lib, context, utils, __tests__).
• apps/agent/: Go cb-agent (cmd/, internal/, e2e/).
• docker/: Mono image, nginx, entrypoint, and supervisord configurations.
• tests/: Integration, build (repo-policy), and unit tests.
• docs/: User and ops documentation (MkDocs), design, and evidence.
• specs/: 1.0.0 release-control ledger and dated design specs.
• plans/: Indexed implementation plans.
• scripts/: CI tiers, install helpers, and version parity.
• packaging/: nfpm, native bundle, and rollback logic.
• .github/: CI workflows, CODEOWNERS, and PR/bug templates.
• SECURITY_REPORTS/ & SECURITY_PATCHES/: Historical audits.

Runtime Stack: PostgreSQL, Redis, NATS, and nginx. Deployment is via a mono container or native systemd using install.sh or the cb command.

The project is organized into three main areas:

Go Agent (apps/agent/)

• Entrypoint: cmd/cb-agent/main.go
• Core Logic: internal/{frame,link,capability,spool,netscope,hostinfo,status,tlsdial,update}
• Collection: internal/collect/{collect.go,payload.go,host/,probe/}

Backend (apps/backend/src/app/)

• Discovery Services: services/{discovery_service,discovery_profiles_service,discovery_scheduler,discovery_import_service,discovery_merge}.py
• Agent Services: services/{agent_link,agent_registry,agent_capabilities,agent_probe,agent_telemetry}.py
• Monitoring: services/monitoring/{probe_eligibility,probe_reconcile}.py and workers/monitor_probe_dispatch.py
• API & Schemas: api/ and schemas/ directories for discovery, agents, and agent frames.
• Core & DB: core/ (scope, ACL, scheduler, locks) and db/models.py.

Frontend (apps/frontend/src/)

• Pages: pages/{AgentDetailPage,AgentsPage,DiscoveryPage,DiscoveryHistoryPage}.jsx
• Components: components/agents/* and components/discovery/{ScanProfileForm,ScanDetailPanel,NewScanPage}.jsx
• Hooks & API: hooks/useDiscoveryStream.js and api/{agents.js,discovery.js}

The cbi-agent Cohesion Hardening plan (Slices 1-2) is a series of 21 test-first tasks designed to consolidate contracts and fix defects in the agent, backend, and frontend. This plan is a prerequisite for Slice 3 (probe.result) and Slice 4 (discovery.finding) because it establishes the core architectural patterns and data contracts they depend on.

Key objectives include:

• Normalizer Consolidation: Moving from multiple hand-rolled copies to a single shared normalizer function used by probe.result projections.
• Conformance Harness: Using a cross-language conformance corpus (JSON fixtures) as a mandatory gate for shipping new frame types.
• Testability Patterns: Implementing injected clocks and dialers (collector test seams) to allow for reliable testing of collectors.
• Readiness & Capability Semantics: Defining how capabilities report health and how per-capability grant isolation works.
• Data Observability: Ensuring bounded history, spool visibility, and complete Agent Detail views to support end-to-end testing of future slices.

The cb-agent is a Go-based daemon designed to enroll against a Circuit Breaker instance via an end-to-end-encrypted channel. It operates as an outbound-only agent, reporting heartbeats and appearing in the Circuit Breaker UI for administrator approval.

Core Components

• apps/agent/ (Go module): Implements key generation, Noise IK handshakes, a bounded data spool, and a capability gate.
• Backend Control Plane: A Python/FastAPI subsystem that terminates the Noise channel, manages agent state, and handles enrollment. It includes modules for crypto, registry, and link management.
• Frontend Agents Surface: A React-based UI following the MonitorsPage pattern for managing and viewing agent status.

Technical Specifications

• Encryption: Noise IK pattern using X25519 DH, ChaCha20-Poly1305 cipher, and SHA-256. Rekeying occurs every 15 minutes.
• Communication: Outbound-only frames via WSS (WebSockets). No network relay or tunneling is supported in the foundation version.
• Data Spooling: Uses /var/lib/cb-agent/spool/ with a default 64 MB cap. Only data frames are spooled; control frames are never spooled. When draining, the agent interleaves spooled frames with live traffic at a ratio of 1 spooled frame per 4 live frames.

The Server Contract Implementation Plan aims to align the server's operational contract with specific requirements (SRV-03, SRV-05, and SRV-06). The primary goals are to implement distinguishable health endpoints (liveness, readiness, and startup), introduce a configuration validator, and unify the divergent cb CLI tools into a single command-line interface.

Key Architectural Changes

• Health Probes: Health is split into three distinct endpoints backed by a shared probe function. This allows orchestrators (like systemd or Docker) to differentiate between a wedged process (requiring a restart) and a process waiting on a dependency (requiring a wait).
• Config Validation: Reuses the app.core.startup_validation module, exposed via a new app.cli entrypoint.
• CLI Unification: The two existing cb scripts will converge into a single CLI using mode dispatch.

Tech Stack

• FastAPI
• Python 3.12
• Bash
• systemd
• Docker HEALTHCHECK