ops-bridge/.claude/rules/architecture.md

Architecture

OpsBridge has two logical components:

1. OpsBridge — tunnel lifecycle manager (this repo) Manages named SSH reverse tunnels defined in ~/.config/bridge/tunnels.yaml. Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked in ~/.local/state/bridge/. Bridge states: stopped → starting → connected → degraded → failed. The degraded state means SSH is up but the optional HTTP health check is failing.

2. OpsCatalog — operations knowledge repository (planned extension) A Git-backed YAML catalog of operations domains, targets, bridges, and actor classes. OpsBridge consumes this catalog to resolve bridge identifiers and orient operators. Schema examples are in wiki/OpsCatalogSpecification.md. The catalog layout follows: opscatalog/domains/<domain>/{domain.yaml, targets/, bridges/, docs/}.

Key design constraints:

• OpsBridge owns lifecycle management only; it does not own credential issuance or CA operations (those belong to ops-warden)
• Each tunnel is identified by name (e.g. state-hub-coulombcore); names used in config, CLI args, and log filenames must stay consistent
• Actor attribution is tracked per bridge using the three-actor vocabulary from the AccessManagementDirective: adm (human), agt (LLM agent), atm (automation); actor names must carry the matching prefix (adm-*, agt-*, atm-*) (FRS §5.7)
• Two credential modes are first-class and must remain independently functional:
  1. Static key mode (default) — ssh_key only; no TTL, no cert logic
  2. cert_command mode — a pluggable shell command that issues a CA-signed cert before each SSH launch; TTL parsed from the cert; pre-emptive refresh ~5 min before expiry; cert_identity logged in every BRIDGE_CONNECTED event

Specification docs are in wiki/: PRD (OpsBridgePrd.md), FRS (OpsBridgeFrs.md), and OpsCatalog spec (OpsCatalogSpecification.md).

Quick Reference

~/the-custodian/state-hub/mcp_server/TOOLS.md