Skip to content
FractalOps

FractalOps C4 Model

FractalOps C4 Model

Section titled “FractalOps C4 Model”

This page is the canonical C4 map for FractalOps. It keeps architecture conversation at the right altitude before an engineer jumps into feature-sliced code, Kubernetes manifests, or runbooks.

Rendering Contract

Section titled “Rendering Contract”

The docs site is Starlight. Diagrams are checked in as Markdown mermaid fences and rendered by astro-mermaid; large screenshot or exported-image pages use starlight-image-zoom.

  • Prefer Mermaid C4 diagrams for system, container, and bounded-context maps.
  • Prefer normal Mermaid flowcharts for request lifecycles and state machines.
  • Keep C4 labels short. Mermaid C4 support is less broad than C4-PlantUML.
  • Do not paste PNG architecture diagrams when source-controlled Mermaid is enough.
  • Use zoomed images only for externally generated screenshots or dense rendered assets that cannot stay readable as code.

C4 Context

Section titled “C4 Context”
C4Context
title FractalOps system context

Person(operator, "Platform operator", "Human running product and infrastructure changes")
Person(agent, "AgentSquad agent", "Coding or test agent with a stable nickname and scoped tools")
Person(developer, "Developer", "Employee launching project workspaces and previews")

System_Boundary(fractalops, "FractalOps") {
  System(portal, "Portal", "Human entry point for projects, launches, Studio, and proof")
  System(studio, "Studio and Agent Execution", "AgentSquad orchestration, handoff, run state, and evidence")
  System(proposal, "Proposal Plane", "Only gate for non-read changes")
  System(semantics, "Semantics", "Ontology, lineage, and graph projection")
}

System_Ext(keycloak, "Keycloak and Pomerium", "Human SSO and protected routes")
System_Ext(cliproxy, "CLIProxy", "Model gateway, quota, and runtime credential binding")
System_Ext(openbao, "OpenBao and ESO", "Secret lifecycle and Kubernetes Secret sync")
System_Ext(spicedb, "SpiceDB", "Authorization graph and permission checks")
System_Ext(k8s, "Kubernetes platform", "Workloads, Headlamp, Gateway API, CNPG, Valkey, and object stores")
System_Ext(github, "GitHub", "Issues, pull requests, checks, and merge lifecycle")
System_Ext(temporal, "Temporal", "Durable workflow execution")
System_Ext(data, "DataHub, ClickHouse, Mimir, Chronicle", "Lineage, facts, metrics, and long-term evidence")

Rel(operator, portal, "Controls projects and reviews proof")
Rel(developer, portal, "Launches workspaces and previews")
Rel(agent, studio, "Executes lane work")
Rel(portal, keycloak, "Authenticates through", "OIDC")
Rel(portal, proposal, "Submits non-read changes")
Rel(studio, cliproxy, "Uses model credentials")
Rel(studio, github, "Creates issues, PRs, checks, and comments")
Rel(proposal, temporal, "Schedules approved work")
Rel(temporal, k8s, "Runs durable activities against")
Rel(portal, openbao, "Reads scoped secrets through controlled paths")
Rel(portal, spicedb, "Checks permissions")
Rel(semantics, data, "Projects lineage and proof")

C4 Container

Section titled “C4 Container”
C4Container
title FractalOps container view

Person(operator, "Platform operator")
Person(agent, "AgentSquad agent")
Person(developer, "Developer")

System_Boundary(fractalops, "FractalOps") {
  Container(portal, "Portal", "Astro/React", "Project navigation, launches, Studio UI, preview links")
  Container(api, "FractalOps API", "FastAPI", "Request contracts, read models, proposal entrypoints")
  Container(worker, "Temporal worker", "Python", "Durable activities and workflow callbacks")
  Container(agentExecution, "Agent Execution", "Python + provider adapters", "Provider policy, launch, takeover")
  Container(armory, "Armory", "Tool and skill catalog", "Per-agent MCP, skill, and hook assignment")
  Container(operationAssets, "Operation Asset Control", "Python/CUE", "Typed access to Headlamp, CLIProxy, DevPod, and platform surfaces")
  Container(semantics, "Semantics", "Python", "Ontology and lineage projection")
  Container(evidence, "Evidence", "Python", "Proof packs, Chronicle writes, and audit facts")
}

System_Ext(identity, "Keycloak/Pomerium", "OIDC edge")
System_Ext(secret, "OpenBao/ESO/SPIRE", "Secret and workload identity")
System_Ext(authz, "SpiceDB", "Authorization graph")
System_Ext(platform, "Kubernetes platform", "Headlamp, Gateway API, CNPG, Valkey, SeaweedFS")
System_Ext(model, "CLIProxy", "Model provider routing and quota")
System_Ext(source, "GitHub", "Issues, PRs, checks")
System_Ext(workspace, "DevPod workspace", "Employee/project execution workspace")
System_Ext(proofStores, "Proof stores", "DataHub, ClickHouse, Mimir, Chronicle")

Rel(operator, portal, "Uses")
Rel(developer, portal, "Launches")
Rel(agent, agentExecution, "Runs through")
Rel(portal, api, "Calls", "HTTP")
Rel(api, identity, "Validates session")
Rel(api, authz, "Checks permissions")
Rel(api, secret, "Requests scoped material")
Rel(api, operationAssets, "Resolves executable surfaces")
Rel(api, agentExecution, "Starts or resumes work")
Rel(agentExecution, armory, "Loads assigned tools and hooks")
Rel(agentExecution, model, "Calls coding model runtime")
Rel(agentExecution, source, "Writes issues, PRs, and review comments")
Rel(operationAssets, platform, "Uses Headlamp-first Kubernetes APIs")
Rel(operationAssets, workspace, "Creates and observes")
Rel(worker, platform, "Executes durable changes")
Rel(semantics, proofStores, "Writes lineage")
Rel(evidence, proofStores, "Writes proof")

C4 Component: Agent Execution

Section titled “C4 Component: Agent Execution”
C4Component
title Agent Execution component view

Container_Boundary(agentExecution, "Agent Execution") {
  Component(roster, "Agent Roster", "Domain service", "Stable nickname, role, lane, runtime, and replacement history")
  Component(worktreeLease, "Worktree Lease", "Domain service", "Owned repository workspace and write boundary")
  Component(runtimeAdapter, "Agent Process Adapter", "Adapter", "Codex, Claude, Antigravity, or future coding runtime")
  Component(toolContract, "MCP Tool Contract", "MCP", "Enumerated actions instead of final-answer parsing")
  Component(handoff, "Handoff Journal", "Application service", "Structured handoff before runtime swap or pause")
  Component(proofCollector, "Proof Collector", "Application service", "Diff, test, preview, issue, and PR evidence")
  Component(runMonitor, "Run Monitor", "Application service", "Detects waiting, responding, tool use, blocker, and stale states")
}

System_Ext(armory, "Armory", "Tool, skill, MCP, and hook assignment")
System_Ext(cliproxy, "CLIProxy", "Model routing and quota")
System_Ext(github, "GitHub", "Issue/PR lifecycle")
System_Ext(devpod, "DevPod", "Execution workspace")
System_Ext(preview, "Preview plane", "Monstore preview route")

Rel(roster, worktreeLease, "Binds agent to owned write surface")
Rel(roster, runtimeAdapter, "Selects replaceable runtime")
Rel(runtimeAdapter, cliproxy, "Uses model route")
Rel(runtimeAdapter, toolContract, "Must call tools for reports, handoff, PR, and status")
Rel(toolContract, github, "Writes structured issue/PR state")
Rel(toolContract, armory, "Loads tool grants")
Rel(worktreeLease, devpod, "Runs inside")
Rel(handoff, runtimeAdapter, "Transfers persona and current state")
Rel(proofCollector, github, "Links diff and checks")
Rel(proofCollector, preview, "Requires browser proof when UI changes")
Rel(runMonitor, runtimeAdapter, "Reconciles stalled or blocked work")

Reading Order

Section titled “Reading Order”