LibOps Control Plane

LibOps is an event-driven infrastructure orchestration system that manages GCP resources and VM configurations across organizations, projects, and sites. It uses event aggregation, debouncing, and fan-out patterns to efficiently reconcile infrastructure state changes.

Architecture

The system consists of several core components:

• API: The central management API (Go/ConnectRPC) serving the dashboard and handling API requests.
• Event Router: Polls the event queue and orchestrates reconciliations using go-workflows.
• Site Proxy: A Cloud Run service that fans out events to individual site controllers.
• Controller: Runs on site VMs to execute reconciliations (SSH keys, secrets, firewall, deployments).
• Databases: MariaDB (application data) and PostgreSQL (workflow state).
• Security: HashiCorp Vault for secret management.

Development Setup

Prerequisites

• Go 1.25+
• Docker & Docker Compose
• Node.js 22+ (for frontend)
• make

Quick Start

1. Install Tools:

   make install-tools

2. Start Services:

   docker compose up -d

   This starts MariaDB, Postgres, Vault, API, Event Router, and Traefik.

3. Run Tests:

   make test             # Unit tests
   make integration-test # Integration tests (requires Docker)

4. Access Dashboard: Open http://localhost (proxied via Traefik).

Key Commands

• make fmt: Format code.
• make lint: Run linters.
• make sqlc: Generate database code.
• make proto: Generate Protocol Buffers code.

Project Structure

• cmd/: Entry points for services (event-router, site-proxy, etc.).
• control-plane/: Core orchestration logic.
• db/: Database migrations and queries.
• internal/: Private application code.
• web/: Frontend React application.
• proto/: Protocol Buffer definitions.

Documentation

See CLAUDE.md for detailed architectural notes and internal workflows.