tegwick
101244bd1d
Each concern (identity, session protocol, workplan convention, stack, architecture, repo boundary) now lives in its own file with a single responsibility. CLAUDE.md becomes a thin @-import integrator. Removes Ralph Loop duplication — global ~/.claude/CLAUDE.md remains authoritative. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1.4 KiB
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 identity/credentials
- 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 (human operator vs. automation agent) is tracked per bridge for audit log traceability (FRS §5.7)
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