Current Stack, Solution, and IA Map

현재 스택 · 솔루션 · IA 맵 (Current Stack, Solution, and IA Map)

마지막 검토: 2026-05-10

이 문서는 더 오래된 스택 스냅샷을 대체합니다. FractalOps 스택 소유권, 솔루션 배치, 정보 구조(IA), 외부 기술 가정의 현재 라우팅 문서이자 단일 원천(SSOT)입니다.

협상 불가 제품 경계 (Non-Negotiable Product Boundary)

FractalOps는 조직의 메타 컨트롤 플레인입니다.

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

이 루프를 운영하는 데 필요한 실행 substrate는 강하게 소유합니다. 인접 도구는 런타임 실행·identity·secret·proof·lineage·delivery 상태를 직접 제공하지 않는 한 통합 endpoint로 남습니다.

진실 순서 (Source Of Truth Order)

Constitution 및 canonical architecture
런타임 토폴로지 및 스택 운영 카탈로그
Kubernetes/Argo GitOps 매니페스트
패키지 매니페스트 및 lockfile
외부 공식 벤더 문서
역사적 문서

역사적 문서는 이 페이지를 덮어쓸 수 없습니다. 요구사항이 이 페이지와 충돌하면, 오래된 요구사항 페이지를 갱신하거나 여기로 다시 연결하세요.

런타임 척추 (Runtime Spine)

flowchart TB
  portal["Portal"] --> proposal["Proposal Plane"]
  proposal --> studio["Studio / Agent Execution"]
  studio --> run["AgentSquad 또는 AgentSquad run"]
  run --> ws["Daytona workspace / execution slot"]
  ws --> adapter["agent process adapter"]
  adapter --> armory["Armory MCP & skills"]
  armory --> gh["GitHub App PR / issue 증거"]
  gh --> proof["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 route 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, Supabase SQL migrations
Agent process	Codex, Claude, and Antigravity CLI adapters
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

도구는 모두 repo-local입니다. make uv-bootstrap이 uv를 ./.tools/uv에만 설치하고, 모든 명령은 make 타깃 또는 ./.tools/uv/uv run으로 실행합니다(전역 pip install 금지).

스택 운영 카탈로그 (Stack Operation Catalog)

라이브 FractalOps 스택 카탈로그(2026-05-10 생성)에서 가져왔습니다. 현재 목록은 CLI로 직접 확인할 수 있습니다.

fops stacks list --compact
# stack_list_command (backend/src/fractalops/cli_commands/operations.py) →
# {"count": N, "stacks": [{"stackId": ..., "primaryOperationId": ..., "operationCount": ...}, ...]}

fops stacks operations <stack-id>   # 한 스택의 연산 목록
fops stacks validate                # 스택 운영 카탈로그 검증

Stack	Primary Operation	Ownership Class
`argocd`	`argocd/fractalops-argocd-self.application.yaml`	GitOps substrate
`clickhouse`	`bootstrap_clickhouse`	warehouse/proof fact plane
`cloudflared`	`install_cloudflared_openbao`	edge connector
`daytona`	`create_project_daytona_workspace`	execution workspace substrate
`datahub`	`argocd/runtime/resources/datahub.application.yaml`	catalog/lineage plane
`dokploy`	`configure_dokploy_git_transport`	persistent backing services + static delivery endpoint
`evidence`	`bootstrap_supabase`	Supabase Storage backed by SeaweedFS evidence storage
`fractalops`	`argocd/runtime/resources/fractalops-*.application.yaml`	product runtime
`gitops`	`reconcile_connector_ssot`	topology reconciliation
`headlamp`	`argocd/runtime/resources/headlamp.application.yaml`	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`	`argocd/runtime/resources/pomerium.application.yaml`	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 및 인프라 베이스라인

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; seed material is written to OpenBao by a SPIRE-authenticated issuer, not static defaults.
Image trust	Sigstore/Cosign for signatures and attestations.
Workload identity	SPIFFE/SPIRE SVIDs bound to per-workload ServiceAccounts; OpenBao JWT auth checks the SPIFFE subject before runtime read or seed issuance.
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	Nexus owns package/OCI/build cache distribution; `cache-plane` owns Redis-compatible ephemeral app cache through Valkey Operator.
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 + Assembly GitOps
Project delivery	`/projects/`, `/work/`	AgentSquad on Daytona + Temporal/Studio	GitHub App + Semantics
Research	`/research/`, `/domains/research/`	Research-mode AgentSquad on same runtime	Astro/Starlight repo + DataHub/wiki
AgentSquad	`/admin/agents/agentsquad`, 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 Control Surface	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

프런트엔드 소스/빌드 소유권은 비공개 repo yamonco/fractalops-frontend에 있습니다. 이 repo는 백엔드 계약, 런타임 자동화, GitOps 원하는 상태만 유지합니다.

에이전트 팀 타입 (Agent Team Types)

동일한 Studio, Temporal, Daytona, mailbox, GitHub App, DataHub 계보 레일을 재사용합니다. 에이전트 역할 순서, handoff 그래프, MCP/skill 적재, write 정책, repository scope, PR 제출자 정책은 Studio Team Contract가 소유합니다. 템플릿 카탈로그, Armory, 프로젝트 프로필 하이드레이션, 생성 reconciliation은 자체 역할 맵을 들지 말고 그 계약으로부터 렌더링해야 합니다.

Team Type	Purpose	Required Agents
`agentsquad`	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는 별도 런타임이 아닙니다. 하나의 research request, 하나의 mono repo, 하나의 Daytona workspace, 하나의 Astro/Starlight 문서 표면을 만듭니다. 후속 요청마다 그 research repo에 ticket과 PR이 생깁니다.

Portal IA

Portal은 랜딩 페이지가 아니라 운영 표면입니다.

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)

현재 방향:

flowchart LR
  action["Agent action"] --> event["structured event"]
  event --> otel["OpenTelemetry signal"]
  otel --> ch["ClickHouse fact"]
  ch --> rdf["Semantics RDF identity"]
  rdf --> dh["DataHub entity/aspect/search projection"]
  dh --> chr["Chronicle evidence ref\n(증거 산출물 존재 시)"]

OpenLineage는 이벤트 모델이 맞는 곳에서 portable run/job/dataset 계보 이벤트에 사용해야 합니다. FractalOps 고유의 agent/issue/PR/browser/proof 메타데이터는 병렬 ad hoc 이벤트 모양이 아니라 custom facet/aspect로 표현해야 합니다.

DataHub는 이미 entity와 aspect 중심으로 설계되어 있으므로, FractalOps는 다음을 투영합니다: 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. (투영 함수 근거: tach.toml의 semantics.domain.datahub 인터페이스 — fops_project_projection, fops_run_attempt_projection, fops_workspace_lease_projection, fops_proof_closure_projection 등.)

검색 및 위키 계약 (Search And Wiki Contract)

SearXNGgrid는 풍부화된 검색 게이트웨이처럼 동작해야 합니다.

웹 소스를 질의한다.
내부 위키/검색 인덱스를 더 높은 우선순위로 질의한다.
source, freshness, confidence, lineage ref와 함께 병합된 결과를 반환한다.
stale 위키 결과를 명시적으로 표시한다.
stale 결과가 교정되면 에이전트가 위키 갱신 proposal을 만들게 한다.
갱신을 DataHub와 ClickHouse로 투영한다.

위키 본문 저장소와 DataHub 카탈로그는 두 개의 단절된 제품으로 갈라지면 안 됩니다. DataHub/Elasticsearch류 발견은 entity/계보 검색에 재사용하고, 위키 콘텐츠는 본문/소스 저장소로 남깁니다.

외부 참조 베이스라인 (External Reference Baseline)

공식 문서 확인일 2026-05-10:

Stack	Current External Assumption	Official Source
Astro	Astro docs track latest; FractalOps Portal pins `>=6.4.0`.	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 및 정리 규칙 (Deprecation And Cleanup Rules)

Retired/Drift	Current Rule
alternate orchestration engines as product truth	Removed. Studio owns execution state and Temporal owns durable cadence.
local browser alternate path	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.
dagger / buildx-dev / mutagen / `fops project-dev` / `proxy.daytona`	Removed. Preview = bare dev server + daytona-proxy signed URL on `monstore.io`.
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 duplicated app auth mesh~~ (removed)	Cut over to SpiceDB (Zanzibar ReBAC) as the single application-resource permission SSOT.

문서 유지 규칙 (Documentation Maintenance Rule)

스택이나 IA 변경은 이 페이지를 먼저 갱신한 다음, 좁은 per-stack 페이지를 갱신합니다.

필요한 갱신 증거:

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