# fitchmultz/ai-control-plane architecture

> Architecture diagram of the GitHub repository fitchmultz/ai-control-plane, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fitchmultz/ai-control-plane
- Repository: https://github.com/fitchmultz/ai-control-plane

## Overview

AI Control Plane is a host-first Docker reference implementation for governing an AI gateway, operated through typed workflows in acpctl. The principal operator journey is to configure and validate a deployment, inspect runtime readiness and health, then use day-two workflows for keys, certificates, database recovery, and upgrades. Separate governance and policy evaluation, telemetry/reporting, and evidence-generation capabilities support that operational loop. The excerpts show selected service calls; README capability links document additional workflows whose internal wiring was not sampled, so those connections are not inferred.

Main entry points: [`cmd/acpctl/main.go`](https://github.com/fitchmultz/ai-control-plane/blob/main/cmd/acpctl/main.go) (acpctl CLI), [`internal/upgrade/executor.go`](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/upgrade/executor.go) (Upgrade and rollback), [`internal/readiness/evidence.go`](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/readiness/evidence.go) (Readiness evidence), [`internal/validation/validation.go`](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/validation/validation.go) (Configuration validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator workflows"]
  node_cli["acpctl CLI<br/>[main.go]"]
  node_onboard["Onboarding<br/>[verify.go]"]
end

subgraph group_runtime["Runtime operations"]
  node_gateway["Gateway client<br/>[client.go]"]
  node_database["PostgreSQL services<br/>[runtime_service.go]"]
  node_dbadmin["Database recovery<br/>[admin_service.go]"]
  node_certs["Certificate lifecycle<br/>[storage.go]"]
  node_upgrade["Upgrade and rollback<br/>[executor.go]"]
  node_hostdeploy["Host deployment<br/>[runner.go]"]
  node_docker["Docker operations<br/>[compose.go]"]
end

subgraph group_governance["Governance and policy"]
  node_validation["Configuration validation<br/>[validation.go]"]
  node_contracts["Governance contracts<br/>[governance.go]"]
  node_policy["Policy evaluation<br/>[workflow.go]"]
  node_ingest["Evidence ingest<br/>[workflow.go]"]
  node_rbac["Role controls<br/>[package.go]"]
end

subgraph group_evidence["Evidence and reporting"]
  node_status["Runtime status<br/>[package.go]"]
  node_operatorreport["Operator reporting<br/>[render.go]"]
  node_performance["Performance baseline<br/>[baseline.go]"]
  node_readiness["Readiness evidence<br/>[evidence.go]"]
  node_assessor["Assessor packet<br/>[packet.go]"]
  node_closeout["Pilot closeout<br/>[bundle.go]"]
  node_chargeback["Chargeback reporting<br/>[input.go]"]
  node_bundle["Release bundles<br/>[builder.go]"]
end

subgraph group_foundation["Shared services"]
  node_config["Runtime configuration<br/>[database.go]"]
  node_process["Process execution<br/>[exec.go]"]
end

node_operator(("Operator"))

node_operator -->|"runs workflows"| node_cli
node_cli -.->|"starts onboarding"| node_onboard
node_cli -->|"runs validation"| node_validation
node_cli -->|"checks status"| node_status
node_cli -->|"evaluates policy"| node_policy
node_cli -->|"renders reports"| node_chargeback
node_cli -->|"runs recovery"| node_dbadmin
node_cli -->|"manages certificates"| node_certs
node_cli -->|"runs upgrades"| node_upgrade
node_cli -->|"builds evidence"| node_readiness
node_cli -->|"builds packets"| node_assessor
node_cli -->|"builds closeout"| node_closeout
node_cli -->|"builds bundles"| node_bundle
node_onboard -->|"verifies gateway"| node_gateway
node_onboard -->|"validates setup"| node_validation
node_gateway -->|"loads settings"| node_config
node_database -->|"resolves database mode"| node_config
node_dbadmin -->|"runs database commands"| node_process
node_certs -->|"executes in container"| node_docker
node_certs -->|"restarts container"| node_process
node_status -->|"collects database status"| node_database
node_policy -->|"uses evidence input"| node_ingest
node_policy -->|"loads role context"| node_rbac
node_contracts -->|"uses validation"| node_validation
node_operatorreport -->|"renders status"| node_status
node_readiness -->|"executes gates"| node_process
node_readiness -->|"verifies bundle"| node_bundle
node_upgrade -->|"checks runtime"| node_database
node_upgrade -->|"snapshots database"| node_dbadmin
node_upgrade -->|"applies deployment"| node_hostdeploy
node_upgrade -->|"validates config"| node_validation
node_performance -->|"loads settings"| node_config
node_assessor -->|"requires evidence"| node_readiness
node_closeout -->|"packages evidence"| node_readiness

click node_cli "https://github.com/fitchmultz/ai-control-plane/blob/main/cmd/acpctl/main.go"
click node_onboard "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/onboard/verify.go"
click node_validation "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/validation/validation.go"
click node_contracts "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/contracts/governance.go"
click node_policy "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/policyengine/workflow.go"
click node_ingest "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/ingest/workflow.go"
click node_rbac "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/rbac/package.go"
click node_gateway "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/gateway/client.go"
click node_database "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/db/runtime_service.go"
click node_dbadmin "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/db/admin_service.go"
click node_certs "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/certlifecycle/storage.go"
click node_upgrade "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/upgrade/executor.go"
click node_hostdeploy "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/hostdeploy/runner.go"
click node_docker "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/docker/compose.go"
click node_status "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/status/package.go"
click node_operatorreport "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/operatorreport/render.go"
click node_performance "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/performance/baseline.go"
click node_readiness "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/readiness/evidence.go"
click node_assessor "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/assessor/packet.go"
click node_closeout "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/closeout/bundle.go"
click node_chargeback "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/chargeback/input.go"
click node_bundle "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/bundle/builder.go"
click node_config "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/config/database.go"
click node_process "https://github.com/fitchmultz/ai-control-plane/blob/main/internal/proc/exec.go"

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_cli,node_onboard toneBlue
class node_gateway,node_database,node_dbadmin,node_certs,node_upgrade,node_hostdeploy,node_docker toneAmber
class node_validation,node_contracts,node_policy,node_ingest,node_rbac toneMint
class node_status,node_operatorreport,node_performance,node_readiness,node_assessor,node_closeout,node_chargeback,node_bundle toneRose
class node_config,node_process,node_operator toneIndigo
```

## Components

### Operator workflows

- [acpctl CLI](https://github.com/fitchmultz/ai-control-plane/blob/main/cmd/acpctl/main.go): `cmd/acpctl/main.go`
- [Onboarding](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/onboard/verify.go): `internal/onboard/verify.go`

### Runtime operations

- [Gateway client](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/gateway/client.go): `internal/gateway/client.go`
- [PostgreSQL services](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/db/runtime_service.go): `internal/db/runtime_service.go`
- [Database recovery](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/db/admin_service.go): `internal/db/admin_service.go`
- [Certificate lifecycle](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/certlifecycle/storage.go): `internal/certlifecycle/storage.go`
- [Upgrade and rollback](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/upgrade/executor.go): `internal/upgrade/executor.go`
- [Host deployment](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/hostdeploy/runner.go): `internal/hostdeploy/runner.go`
- [Docker operations](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/docker/compose.go): `internal/docker/compose.go`

### Governance and policy

- [Configuration validation](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/validation/validation.go): `internal/validation/validation.go`
- [Governance contracts](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/contracts/governance.go): `internal/contracts/governance.go`
- [Policy evaluation](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/policyengine/workflow.go): `internal/policyengine/workflow.go`
- [Evidence ingest](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/ingest/workflow.go): `internal/ingest/workflow.go`
- [Role controls](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/rbac/package.go): `internal/rbac/package.go`

### Evidence and reporting

- [Runtime status](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/status/package.go): `internal/status/package.go`
- [Operator reporting](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/operatorreport/render.go): `internal/operatorreport/render.go`
- [Performance baseline](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/performance/baseline.go): `internal/performance/baseline.go`
- [Readiness evidence](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/readiness/evidence.go): `internal/readiness/evidence.go`
- [Assessor packet](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/assessor/packet.go): `internal/assessor/packet.go`
- [Pilot closeout](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/closeout/bundle.go): `internal/closeout/bundle.go`
- [Chargeback reporting](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/chargeback/input.go): `internal/chargeback/input.go`
- [Release bundles](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/bundle/builder.go): `internal/bundle/builder.go`

### Shared services

- [Runtime configuration](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/config/database.go): `internal/config/database.go`
- [Process execution](https://github.com/fitchmultz/ai-control-plane/blob/main/internal/proc/exec.go): `internal/proc/exec.go`

### Other components

- **Operator**

## Connections

- Operator → acpctl CLI: runs workflows (evidence: `README.md`)
- acpctl CLI → Onboarding: starts onboarding
- acpctl CLI → Configuration validation: runs validation (evidence: `README.md`)
- acpctl CLI → Runtime status: checks status (evidence: `README.md`)
- acpctl CLI → Policy evaluation: evaluates policy (evidence: `README.md`)
- acpctl CLI → Chargeback reporting: renders reports (evidence: `README.md`)
- acpctl CLI → Database recovery: runs recovery (evidence: `README.md`)
- acpctl CLI → Certificate lifecycle: manages certificates (evidence: `README.md`)
- acpctl CLI → Upgrade and rollback: runs upgrades (evidence: `README.md`)
- acpctl CLI → Readiness evidence: builds evidence (evidence: `README.md`)
- acpctl CLI → Assessor packet: builds packets (evidence: `README.md`)
- acpctl CLI → Pilot closeout: builds closeout (evidence: `README.md`)
- acpctl CLI → Release bundles: builds bundles (evidence: `README.md`)
- Onboarding → Gateway client: verifies gateway (evidence: `internal/onboard/verify.go`)
- Onboarding → Configuration validation: validates setup (evidence: `internal/onboard/verify.go`)
- Gateway client → Runtime configuration: loads settings (evidence: `internal/gateway/client.go`)
- PostgreSQL services → Runtime configuration: resolves database mode (evidence: `internal/config/database.go`)
- Database recovery → Process execution: runs database commands (evidence: `internal/db/admin_service.go`)
- Certificate lifecycle → Docker operations: executes in container (evidence: `internal/certlifecycle/storage.go`)
- Certificate lifecycle → Process execution: restarts container (evidence: `internal/certlifecycle/storage.go`)
- Runtime status → PostgreSQL services: collects database status
- Policy evaluation → Evidence ingest: uses evidence input (evidence: `internal/policyengine/workflow.go`)
- Policy evaluation → Role controls: loads role context (evidence: `internal/policyengine/workflow.go`)
- Governance contracts → Configuration validation: uses validation (evidence: `internal/contracts/governance.go`)
- Operator reporting → Runtime status: renders status (evidence: `internal/operatorreport/render.go`)
- Readiness evidence → Process execution: executes gates (evidence: `internal/readiness/evidence.go`)
- Readiness evidence → Release bundles: verifies bundle (evidence: `internal/readiness/evidence.go`)
- Upgrade and rollback → PostgreSQL services: checks runtime (evidence: `internal/upgrade/executor.go`)
- Upgrade and rollback → Database recovery: snapshots database (evidence: `internal/upgrade/executor.go`)
- Upgrade and rollback → Host deployment: applies deployment (evidence: `internal/upgrade/executor.go`)
- Upgrade and rollback → Configuration validation: validates config (evidence: `internal/upgrade/executor.go`)
- Performance baseline → Runtime configuration: loads settings (evidence: `internal/performance/baseline.go`)
- Assessor packet → Readiness evidence: requires evidence (evidence: `internal/assessor/packet.go`)
- Pilot closeout → Readiness evidence: packages evidence (evidence: `internal/closeout/bundle.go`)