Current Stack, Solution, and IA Map

Current Stack, Solution, and IA Map

Last reviewed: 2026-05-10

This document supersedes older stack snapshots. It is the current routing document for FractalOps stack ownership, solution placement, information architecture, and external technology assumptions.

Non-Negotiable Product Boundary

FractalOps is the organization meta-control plane.

onboarding -> work -> proposal -> proof -> reflective improvement

FractalOps strongly owns the execution substrate required to operate that loop. Adjacent tools remain integration endpoints unless they directly provide runtime execution, identity, secret, proof, lineage, or delivery state.

Source Of Truth Order

1. Constitution and canonical architecture
2. Runtime topology and stack operation catalog
3. Kubernetes/Argo GitOps manifests
4. Package manifests and lockfiles
5. External official vendor documentation
6. Historical docs

Historical docs must not override this page. If a requirement conflicts with this page, update the older requirement page or link it back here.

Runtime Spine

Portal
  -> Proposal Plane
  -> Studio / Harness Runtime
  -> AgentSquad or Ouroboros run
  -> Daytona workspace / execution slot
  -> agent process adapter
  -> Armory MCP and skills
  -> GitHub App PR / issue evidence
  -> Semantics + DataHub + ClickHouse + Chronicle

Truth Planes

Plane	FractalOps Role	Not Allowed
Semantics	Ontology, identity, lineage meaning	Bulk telemetry store
DataHub	Catalog, searchable lineage, entity/aspect metadata	Mutation gate or proof authority
Mimir	Runtime metrics and build/cache time series	Proof facts or ontology
GlitchTip	Application error/performance tracking (Sentry-compatible)	Metrics TSDB, ontology, or proof authority
ClickHouse	Proof facts, event analytics, warehouse projections	Long-form wiki body store or metrics TSDB
Chronicle/WORM	Long-term evidence artifacts and provenance	UI state store
GitHub App	Issue, PR, review, merge identity	Human PAT fallback for agents
OpenBao	Secret and runtime credential authority	Plain env drift
OpenTelemetry	Trace/metric/log signal transport	Product ontology replacement

Current Package Baseline

Area	Current Baseline
Python	>=3.11, managed through uv
Backend	FastAPI, Pydantic v2, SQLAlchemy v2, Alembic
Agent runtime	LangGraph >=0.6, checkpoint-postgres, LangGraph CLI
Durable workflow	Temporal Python SDK
RDF/ontology	rdflib
Observability	OpenTelemetry API/SDK/OTLP HTTP, Mimir metrics store
Error tracking	GlitchTip 6.1.8 (Sentry-compatible), per-project DSN auto-provisioned by project_factory
Frontend package manager	pnpm@10.24.0
Portal	Astro >=6.4.0, React 19, Tailwind >=4.3.0, DaisyUI 5
Portal state	Nanostores plus route-local React state where needed
Flow UI	@xyflow/react; topology flows must share palette/node patterns
Browser automation	Playwright ^1.59.1, routed through PlaywrightGrid for runtime work

Stack Operation Catalog

Generated from the live FractalOps stack catalog on 2026-05-10.

Stack	Primary Operation	Ownership Class
argocd	bootstrap_argocd_identity_gitops	GitOps substrate
clickhouse	bootstrap_clickhouse	warehouse/proof fact plane
cloudflared	install_cloudflared_openbao	edge connector
daytona	create_project_daytona_workspace	execution workspace substrate
datahub	bootstrap_datahub	catalog/lineage plane
dokploy	configure_dokploy_git_transport	persistent backing services + static delivery endpoint
evidence	bootstrap_evidence_supabase	Chronicle/evidence storage
fractalops	bootstrap_fractalops_apps	product runtime
gitops	reconcile_connector_ssot	topology reconciliation
headlamp	bootstrap_headlamp	Kubernetes operator UI endpoint
k3s	reconcile_k3s_oidc	Kubernetes execution substrate
kafka	bootstrap_kafka	event/log stream substrate
langboard	create_project_daytona_workspace	project lifecycle and issue surface
openbao-secret-delivery	reconcile_connector_ssot	secret delivery chain
penpot	bootstrap_daytona_penpot_argocd	design endpoint
pomerium	bootstrap_pomerium_runtime	zero-trust access edge
runtime-storage	storage_surface_metrics	storage pressure and cleanup
nexus	reconcile_nexus_fractalops	internal package + docker/build cache registry (folds the former registry-cache LXC)
windmill	windmill_runbook_catalog	runbook and lightweight automation endpoint

Kubernetes And Infra Baseline

Layer	Current Direction
Cluster	k3s remains the near-term runtime cluster.
Networking	Cilium CNI is the target network/security substrate.
Ingress	Gateway API is the target Kubernetes ingress contract.
Policy	Default deny NetworkPolicy first; then explicit service egress/ingress.
Pod security	Kyverno enforces Pod Security Standards, Restricted where possible.
Secrets	External Secrets pulls from OpenBao/Vault-compatible scopes.
Image trust	Sigstore/Cosign for signatures and attestations.
Workload identity	SPIFFE/SPIRE for workload identity; no hard-coded local IP identity.
mTLS	Cilium mTLS or Istio Ambient only after SPIFFE identity is stable.
Build	Platform CI image builds are GitOps-pinned and use the Nexus build cache. There is no per-project or in-sandbox build pipeline; dev previews are bare processes (see Dev Preview Plane).
Cache	Single Nexus cache plane (npm/pypi/apt/docker-pull/buildcache) + workspace-level transparent turbo/cache surfaces.
Autoscaling	HPA exists for API/Portal/Worker; queue/resource metrics must drive future scale policy.

Solution Ownership Matrix

Solution	User Surface	Execution Surface	Truth Owner
Portal	yamonco/fractalops-frontend:portal Astro shell	FastAPI routes and generated API facade	Frontend repo + FractalOps GitOps
Project delivery	/projects/*, /work/*	AgentSquad on Daytona + LangGraph	GitHub App + Semantics
Research	/research/*, /domains/research/*	Research-mode AgentSquad on same runtime	Astro/Starlight repo + DataHub/wiki
Ouroboros	/admin/agents/ouroboros, CLI	Studio run for FractalOps self-improvement	FractalOps repo issues
Platform image build	CI release pipeline	GitOps-pinned image builds with the Nexus build cache	Build evidence + registry
Dev preview plane	Project workspace UI	Bare dev server in the Daytona sandbox + daytona-proxy signed URL; <slug>.monstore.io per project	Dev Preview Plane + project delivery guard
Persistent services	Project workspace UI	Dokploy (databases, static-site / vercel-sim hosting, big-facility compose)	Project delivery guard
Browser proof	Portal/Daytona/Agent HUD	PlaywrightGrid MCP	Chronicle evidence refs
Error tracking	Project apps + GlitchTip MCP triage	GlitchTip (Sentry-compatible) on fractalops-postgresql	Per-project DSN + GlitchTip org
Search/wiki	Research and AgentSquad tools	SearXNGgrid + Agent Memory Archive	Wiki body + DataHub catalog
Lineage	Portal lineage pages	RDF/OpenLineage/DataHub projection	Semantics/DataHub/ClickHouse
Secrets	Portal credential broker	OpenBao, External Secrets, SPIFFE where available	OpenBao

Agent Team Types

Reuse the same Studio, Daytona, LangGraph, mailbox, GitHub App, and DataHub lineage rails. Agent role order, handoff graph, MCP/skill loadout, write policy, repository scope, and PR submitter policy are owned by the Studio Team Contract. Template catalogs, Armory, project profile hydration, and generation reconciliation must render from that contract instead of carrying their own role maps.

Team Type	Purpose	Required Agents
ouroboros	FractalOps self-improvement	Core-8 plus explicit extension packs
agentsquad	Project delivery	planner, curator, backend, frontend, tester, committer, compactor, closer
research	Investigation and documentation	inquirer, curator, scout, auditor, actor, scribe, tester, committer, closer

Research is not a separate runtime. It creates one research request, one mono repo, one Daytona workspace, and one Astro/Starlight documentation surface. Each follow-up request is a ticket and PR in that research repo.

Portal IA

The Portal is not a landing page. It is the operating surface.

Primary Navigation

Group	Routes	Purpose
Home	/, /workspace, /work/*	operator daily work and launch path
Projects	/projects, /projects/:slug/*	project assets, team, studio, proof, operations
Research	/research, /research/*, /domains/research/*	search, wiki, evidence, lineage, experiments
Runtime	/runtimes, /admin/agents/*, /operations, /ops/*	runtime state and operator controls
Data	/data, /datasets, /domains, /glossary	catalog and domain graph navigation
Review	/review/*, /proposals/*, /proof/*	approvals, evidence gaps, proof closure
Packages	/packages/*, /repos/*, /credentials	package, repository, and credential surfaces
Admin	/admin/*	access workbench, templates, semantics, evidence renewal

Page Composition Rules

Layer	Rule
Template	PortalShell and PortalPageShell own persistent shell and copilot docking.
Organism	Page-specific business surfaces live under organisms.
Molecule	Reusable controls, flow nodes, tables, selectors, disclosure panels.
Atom	Badges, icons, brand mark, small chips.
Runtime state	Global shell/copilot state stays persistent; page state must not recreate global docks.

Data And Lineage Architecture

Current direction:

Agent action
  -> structured event
  -> OpenTelemetry signal
  -> ClickHouse fact
  -> Semantics RDF identity
  -> DataHub entity/aspect/search projection
  -> Chronicle evidence ref when proof artifact exists

OpenLineage should be used for portable run/job/dataset lineage events where its event model fits. FractalOps-specific agent, issue, PR, browser, and proof metadata should be custom facets/aspects rather than parallel ad hoc event shapes.

DataHub is already designed around entities and aspects. FractalOps should project:

• project
• repository
• agent squad generation
• run attempt
• workspace lease
• browser lease
• tool loadout
• issue and PR delivery
• evidence artifact
• wiki/search knowledge asset
• dataset/feature/API/route lineage

Search And Wiki Contract

SearXNGgrid must behave like an enriched search gateway:

1. Query web sources.
2. Query internal wiki/search index with higher priority.
3. Return merged results with source, freshness, confidence, and lineage refs.
4. Mark stale wiki results explicitly.
5. Let the agent create a wiki update proposal when a stale result is corrected.
6. Project the update to DataHub and ClickHouse.

The wiki body store and DataHub catalog must not split into two disconnected products. DataHub/Elasticsearch-like discovery should be reused for entity and lineage search; wiki content remains a body/source store.

External Reference Baseline

Official docs checked on 2026-05-10:

Stack	Current External Assumption	Official Source
Astro	Astro docs track latest and reported latest release as v6.3.0; FractalOps Portal currently pins ^6.1.10.	https://docs.astro.build/en/upgrade-astro/
Daytona	Workspaces, lifecycle, scheduling, and warm workspace reconciliation remain first-class Daytona concepts.	https://daytona.com/docs/
DataHub	Use entities/aspects and metadata graph, not custom one-off catalog tables.	https://docs.datahub.com/docs/metadata-modeling/metadata-model/
OpenLineage	Use JSON-schema/OpenAPI event model and custom facets for extension.	https://openlineage.io/docs/spec/
Pomerium	Identity-aware proxy for BeyondCorp/zero-trust access.	https://www.pomerium.com/docs
OpenBao	Secret generation and encryption service; keep it as secret authority.	https://openbao.org/
SPIFFE/SPIRE	Kubernetes PSAT node attestation and workload registration are the target identity model.	https://spiffe.io/docs/latest/deploying/configuring/
Cilium	Gateway API and policy integration are the target network model.	https://docs.cilium.io/en/latest/network/servicemesh/gateway-api/gateway-api.html
Kyverno	Pod Security Standards can be enforced as Kyverno policies.	https://kyverno.io/policies/pod-security/
Windmill	Use scripts/flows/apps/workers/MCP for lightweight runbooks, not as durable execution replacement.	https://www.windmill.dev/docs/core_concepts/mcp
Sigstore/Cosign	Prefer identity-based/keyless signing and attestation verification.	https://docs.sigstore.dev/cosign/signing/overview/
Cloudflare Tunnel	Outbound cloudflared tunnel is the edge connector; avoid inbound host exposure.	https://developers.cloudflare.com/tunnel/
GitHub App	Agents use GitHub App installation tokens for repo/issue/PR work.	https://docs.github.com/rest/reference/apps

Deprecation And Cleanup Rules

Legacy/Drift	Current Rule
alternate agent process adapters as product truth	Removed. LangGraph Harness Runtime owns Studio/AgentSquad execution state.
local browser fallback	Not canonical. Use PlaywrightGrid.
human PAT for agents	Not allowed. Use GitHub App.
local Docker daemon in Daytona	Forbidden. docker is hard-walled in the sandbox; dev previews are bare processes (see Dev Preview Plane) and persistent services live on Dokploy.
in-sandbox compose/build-and-ship plane	Removed. There is no per-project build pipeline; platform images are CI-built and GitOps-pinned.
raw local IP as identity	Not allowed. Use domain/runtime asset/SPIFFE identity.
full graph snapshots in high-frequency evidence rows	Not allowed. Store digest summaries and lineage refs.
OpenFGA/OPA as duplicated app auth mesh	Keep only where policy contract is explicit and value is proven.

Documentation Maintenance Rule

Every stack or IA change must update this page first, then update narrow per-stack pages.

Required update evidence:

fops stacks list --compact
gh repo clone yamonco/fractalops-frontend /tmp/fractalops_frontend && find /tmp/fractalops_frontend/portal/src/pages -maxdepth 4 -type f
package/lockfile delta
platform/k8s/argocd and platform/k8s/apps delta
official upstream docs link when behavior depends on a vendor feature