FractalOps Canonical Architecture

FractalOps Canonical Architecture

Constitutional law lives in FractalOps Constitution. This document is the canonical product narrative under that law.

Canonical Summary

FractalOps is the organization meta-control plane. It does not exist to mirror one stack homepage or one IAM sync job. It exists to let a human or agent move from onboarding to work to proof through one canonical product model:

• Portal is the primary human workflow surface.
• Proposal Plane is the only allowed non-read mutation gate.
• Semantics holds graph and lineage truth.
• DataHub accumulates project RDF steward reports for catalog search, lineage discovery, and impact navigation.
• ClickHouse warehouse stores the same steward lifecycle as queryable warehouse events/facts and holds warehouse proof.
• PostHog and OpenTelemetry are distributed behavior/runtime event sources that must be classified into the shared ontology before they accumulate in ClickHouse.
• FeaturePlane turns lineage and warehouse facts into Feast-backed compact agent features.
• Chronicle evidence holds long-term proof and provenance.
• Ouroboros observes the same product through compact Agent HUD and feeds improvements back into the same system.

FractalOps owns the control contract across these planes. It does not try to replace every execution surface.

What Is FractalOps?

FractalOps is a graph-first, proposal-governed, evidence-backed meta-control plane for organization work.

Its primary jobs are:

1. make the work path explicit
2. make the mutation path proposal-bound
3. make the proof path visible
4. keep secondary tools consistent with the same truth
5. let Ouroboros improve the product through the same Portal

FractalOps is not a generic website builder, not a one-off portal shell, and not a bag of stack integrations.

What FractalOps Owns

• canonical Portal workflow and command-center UX
• proposal lifecycle, approval boundary, publish/apply follow-up
• ontology, semantic contracts, and graph read models
• access topology, identity linking, and recovery surfaces
• runtime asset control contract and runtime asset selection for owned execution substrate
• evidence indexing and Chronicle proof metadata
• Ouroboros scheduling, Agent HUD compilation, and self-improvement routing
• Harness Runtime orchestration for LangGraph, CLI, workspace, and browser agent process adapters
• the FractalOps runtime itself:
  • portal
  • api
  • worker
  • langgraph-agent-server
  • Temporal
  • DB / Hasura / Supabase Realtime
  • Daytona
  • PlaywrightGrid

What FractalOps Does Not Own

• Daytona does not become the work authority; it is a workspace execution surface
• Penpot does not become the work authority; it is a design collaboration surface
• Nexus does not own identity or approval; it is a package distribution surface
• PlaywrightGrid does not own product logic; it is a browser execution plane
• LangBoard does not own identity truth or proof truth; it is a lifecycle, knowledge, access, and bot execution surface
• ClickHouse warehouse does not own semantics; it is the warehouse fact and warehouse proof plane
• DataHub does not own mutations, identity, SCIM/JIT, or proof; it accumulates RDF steward reports from projects for catalog search, metadata joins, and lineage discovery

Execution Substrate vs Integration Endpoints

FractalOps should not behave as if every neighboring stack is a child system under product governance.

Two rules keep the boundary sharp:

1. execution substrate
   • systems FractalOps must directly run, observe, or schedule because the product or Ouroboros execution plane depends on them
2. integration endpoint
   • systems FractalOps reaches through URL, auth, and health contracts

Endpoint-first examples:

• Nexus
• Penpot
• Dokploy
• Headlamp
• many connector targets

These remain important, but they are not default lifecycle or truth owners inside FractalOps.

Bounded Contexts

Constitution

Canonical standards, approval classes, authority ceilings, and secret-ref discipline.

Proposal Plane

Proposal lifecycle, approval review, publish/apply follow-up, and assignment visibility.

Identity

Principal identity, group-path mapping, IdP/SCIM integration, and developer GitHub linking.

Access

Portal launch, project factory, connector execution, stack entry, and read models that help people move into work. Runtime asset control keeps machine execution behind typed runtime selectors instead of stack-local infra nouns.

Semantics

Ontology, lineage, graph projection, and project spine meaning. DataHub refs are catalog and lineage discovery projections reported by project RDF steward agents, not semantic authority. Project isolation may add local vocabulary, but every local term must map back to the global ontology before it becomes reusable knowledge.

Evidence

Chronicle evidence, proof metadata, WORM pointers, and evidence query surfaces.

Portal Experience

Graph-first human interface, command-center pages, and operations surfaces.

Orchestration

Temporal workflows, retries, schedules, and queued execution.

Control-Plane Reconciliation

CUE/Helm GitOps is the infrastructure reconciliation authority for namespace policy, resource limits, placement, storage, and reconciliation metadata. Routes, authorization policy, ExternalSecret delivery, HPA/autoscaling, feature-plane runtime, and service inventory stay in dedicated charts/controllers. It does not absorb execution engines.

Delegation stays explicit:

• Temporal: durable jobs, schedules, retries, and activity execution
• LangGraph: agent graph fanout, frontier, checkpoints, threads, and HITL state
• execution-runtime-daemon: live Portal projection and session/control events
• ArgoCD: Helm/GitOps application sync that applies platform and workload apps

Rule: engines may consume generated runtime contracts, but they must not patch GitOps-owned objects except through CUE values or chart changes.

Harness Runtime

LangGraph Agent Server-backed runtime orchestration for Studio, Ouroboros, and project Agent Squad execution. It can run native LangGraph agents and can also coordinate agent process adapters such as Codex CLI, Claude CLI, ZAI CLI, workspace-backed CLI agents, and PlaywrightGrid browser agents through Armory-bound adapter policy. Studio and Ouroboros are product flows on top of this kernel, not separate runtime engines.

Policy

OPA decisions, workbench topology, and approval or access policy inputs.

Truth Planes

Git

Normative source of desired code and product change.

OpenBao

Secret source of truth. Connector-scoped secret mediation is CLI-first: fractalops connectors reconcile-ssot is the canonical reconciliation path, while shell scripts remain implementation detail wrappers.

Runtime Assets

Typed execution surfaces selected by canonical asset_id or role. They are the only allowed application-layer control path for concrete machine execution.

DataHub

Catalog and lineage accumulation plane. Each project should have an RDF steward agent that reports datasets, owners, schemas, domain terms, and impact paths into DataHub. The same report lifecycle must emit normalized events/facts into ClickHouse so catalog discovery, impact analysis, metrics, and warehouse proof stay queryable from SQL. DataHub makes reports searchable and navigable, ClickHouse stores the analytical and proof-facing event/fact history, and neither plane owns graph truth, SCIM/JIT, identity, or mutation authority.

FeaturePlane

Feast-backed feature serving plane for compact agent context. It references FractalOps lineage, DataHub catalog and lineage reports, ClickHouse feature marts, Redpanda event topics, and OpenBao secret refs without becoming the truth owner for any of them.

ClickHouse warehouse

Warehouse fact plane and warehouse proof plane. It stores normalized RDF steward, DataHub, PostHog, OpenTelemetry, and agent events under shared global concept ids so cross-project behavior and runtime facts can be analyzed without splitting the domain.

Mimir metrics store

Central metrics store for OpenTelemetry metrics routed by the cluster collector. It owns build duration, cache, runtime health, and resource time series. It does not own proof facts, event lineage, ontology, or long-form evidence.

PostHog and OpenTelemetry

Distributed product-behavior and runtime telemetry sources. They are not proof or ontology authorities. Events and spans must be classified into global ontology ids, keep project-local detail as attributes, and land in ClickHouse for cross-project analysis, proof facts, and feature materialization. Metrics land in Mimir first. Derived metrics facts may be projected into ClickHouse only when they are needed for proof, feature materialization, or cross-project analysis.

Bug replay closes through PlaywrightGrid:

PostHog session/event + OpenTelemetry trace_id
  -> verify_wave / PlaywrightGrid replay
  -> trace.zip, video.webm, screenshot.png
  -> Chronicle/WORM/Supabase Storage artifact refs or owned-domain public evidence URLs
  -> issue, Slack, and dashboard references

Visual artifacts must not be uploaded to GitHub issues or external CDNs. GitHub receives only FractalOps-owned artifact URLs/refs and compact evidence summaries. Public image URLs are accepted only from FRACTALOPS_EVIDENCE_PUBLIC_BASE_URL, FRACTALOPS_SUPABASE_STORAGE_PUBLIC_URL, or FRACTALOPS_PORTAL_PUBLIC_URL hosts.

GlitchTip

Sentry-compatible error-tracking plane for runtime and preview-app exceptions and performance issues. It is not a metrics, ontology, or proof authority; it sits alongside Mimir metrics and OpenTelemetry traces as the application error surface. GlitchTip runs in its own glitchtip namespace against a database on the shared fractalops-postgresql cluster, exposes a public ingest ingress (per-project DSN public key is the auth), and ships an official built-in MCP server registered in the armory for tester/compactor triage. project_factory auto-provisions a per-project DSN into every scaffolded project’s starter .env (fail-open). See Build Plane Observability.

Chronicle evidence

Long-term proof plane.

Portal

Primary human workflow surface.

Ouroboros

Reflective improvement loop operating on the same product through compact Agent HUD.

Primary User Journeys

Onboarding to work

/ -> /projects -> /launch -> /me or /credentials when access is missing -> work surface

Proposal-governed change

proposal review -> approval -> publish -> apply follow-up -> operations visibility -> evidence lookup

Proof path

project spine -> FractalOps graph lineage -> ClickHouse warehouse fact -> Chronicle evidence

Recovery path

blocked route -> access_recovery -> identity/credential fix -> return to the same work path

Ouroboros and Agent HUD

Ouroboros is not “many agents” by itself. It is the reflective loop that lets FractalOps observe, route, and improve itself through the same Portal.

Its canonical agent-facing interface is the compact Agent HUD.

The HUD carries:

• one intent
• one route
• one launch action
• one proof path
• one recovery rule
• one completion proof
• one live signal line

Live UI truth follows one path:

• outbox: portal_live_events
• canonical live projection: harness-projection

Public continuity is intentionally small:

• fresh
• resume

Detailed launch diagnostics such as continuity_reason, first_tool_family, or launch_contract_status explain quality and fallback, but they are not extra public modes.

The default squad shape is Core-8:

• atlas
• mercury
• forge
• relay
• sentinel
• ontos
• ledger
• signal

Extension packs are opt-in:

• design pack: aether, prism, quill
• IA/PM pack: cartographer, conductor
• QA/support pack: compass, beacon
• deep lineage pack: scribe

Proof Path: FractalOps graph + ClickHouse warehouse + Chronicle

FractalOps proof is not a single table or a single graph node.

The proof path is closed only when:

1. semantic identity is visible in Semantics / FractalOps graph
2. warehouse fact or delivery evidence is visible in ClickHouse warehouse
3. long-term provenance is visible in Chronicle evidence

DataHub should accumulate the project RDF reports that make the same objects searchable and navigable. ClickHouse should accumulate the same lifecycle as normalized events/facts for analysis, metrics, and warehouse proof. DataHub cannot close proof by itself.

This is why lineage roles and project roles must both care about proof visibility. Work is not complete when only the coding surface is reachable.

Extension Surfaces

Daytona

Workspace execution surface reached through project-scoped entry.

Penpot

Project-scoped design collaboration surface.

LangBoard

Project-scoped LangBoard lifecycle surface, knowledge wiki, and bot automation surface. For FractalOps, LangBoard is a first-class extension surface but not a truth owner.

Nexus

Package distribution surface for developer stacks.

PlaywrightGrid

Browser execution plane used when local browser contention would corrupt Ouroboros behavior.

Stable Product Rule

Concrete projects such as new.yamon.io are forcing functions. They are useful only when they improve FractalOps itself.

The stable product anchor remains:

organization meta-control plane -> onboarding -> work -> proposal -> proof -> reflective improvement

The canonical contract layer under this narrative is platform/contracts/.