Skip to content
FractalOps

Architecture Overview

Architecture Overview

Section titled “Architecture Overview”

Read FractalOps Constitution first for product law. Then read FractalOps Canonical Architecture for product definition. Use Current Stack, Solution, and IA Map as the current stack/solution/navigation routing document. This page only describes runtime topology and execution flow.

Core Execution Chain

Section titled “Core Execution Chain”
Portal or API input
  -> request contract validation
  -> proposal / policy simulation when mutation is requested
  -> queue or workflow enqueue
  -> Temporal workflow / activity
  -> runtime asset control
  -> connector or executor
  -> audit / evidence / graph projection

Layer Placement

Section titled “Layer Placement”
  • L0
    • constitution and product law
  • L1
    • canonical contracts in platform/contracts/
  • domain
    • invariants, aggregate contracts, ontology meaning
  • application
    • use-case orchestration, HUD compilation, proposal routing
  • infrastructure
    • DB, OpenBao, Temporal, runtime asset control, connector, browser plane, graph adapters
  • interface
    • Portal pages, HTTP routes, CLI entrypoints

Runtime Boundaries

Section titled “Runtime Boundaries”
  • Portal
    • primary human workflow surface
  • api / worker / execution-runtime
    • FractalOps-owned runtime components
  • Temporal
    • queued execution and long-running orchestration
  • OpenBao
    • secret source of truth
  • DataHub
    • catalog and lineage accumulation plane fed by project RDF steward agents
  • ClickHouse warehouse
    • warehouse fact/proof plane that also stores the project RDF steward lifecycle as events and facts
  • PostHog / OpenTelemetry
    • distributed product-behavior and runtime event sources classified into the shared ontology before ClickHouse accumulation
  • Chronicle evidence
    • long-term proof plane
  • PlaywrightGrid
    • browser execution plane for Studio and Ouroboros; local browser fallback is not part of the runtime contract
  • runtime assets
    • typed execution surfaces selected by asset_id or role
  • LangBoard
    • lifecycle surface, knowledge wiki, and bot automation surface

Execution Substrate vs Integration Endpoints

Section titled “Execution Substrate vs Integration Endpoints”

FractalOps strongly owns only the execution substrate it needs to run and improve itself.

Strongly-owned substrate:

  • portal
  • api
  • worker
  • execution-runtime
  • Temporal
  • DB / Hasura / Supabase Realtime
  • Daytona
  • PlaywrightGrid

Ordinary adjacent tools are usually integration endpoints.

  • They are described by URL, auth, and health contracts.
  • They do not become product truth owners.
  • They should not require FractalOps to carry stack-local lifecycle logic unless the execution plane truly depends on them.

Runtime Asset Control

Section titled “Runtime Asset Control”

FractalOps does not treat raw vmid, raw namespace, or stack-specific provider keywords as canonical control nouns.

Canonical control flow:

operation or CLI request
  -> RuntimeAssetControlService
  -> RuntimeAssetController
  -> runtime asset

Current first-class runtime asset kinds:

  • lxc
  • kubernetes

Selector rules:

  • use asset_id when the target must be exact
  • use role when the operation binds to a canonical runtime responsibility

URL rules:

  • public URL is for humans and browser entry
  • executor URL is for machine control
  • the two must stay separate when edge protection or browser routing would corrupt automation

Validation and Generation

Section titled “Validation and Generation”
  • python -m fractalops.testing.unittest_runner is the canonical fail-only Python test runner
  • tach check --dependencies --interfaces is the canonical Python architecture boundary linter; use the cross-solution standard in Tach DDD / Feature Slice Boundary Standard
  • ops/testing/run_contract_suite.py is the curated contract suite entrypoint
  • shared integration validation runs through tests/integration/shared
  • local Docker-backed integration lanes are not canonical on this host
  • generated artifacts are codegen-owned and guarded by make codegen-check
  • synchronous outbound HTTP should prefer the foundation HttpClient unless the machine boundary belongs to runtime asset control

Operational Rules

Section titled “Operational Rules”
  • API never performs direct side effects for proposal-bound work
  • Temporal owns execution
  • policy uncertainty defaults to fail-closed
  • proof must remain queryable after mutation
  • live fanout uses portal_live_events; live UI reads harness-projection
  • Ouroboros public continuity stays fresh | resume
  • Studio is the shared agent execution boundary; project agent squads run through Studio, while Ouroboros is the FractalOps self-improvement workflow on top of Studio
  • Armory owns MCP/tool pack composition and per-agent initialization; browser execution is PlaywrightGrid-only unless a new Armory-managed MCP explicitly supersedes it
  • runtime control must stay behind typed runtime asset contracts
  • secondary tools must not redefine canonical control naming or become accidental truth owners
Section titled “Related Documents”