FractalOps Documentation

FractalOps에 오신 것을 환영합니다

FractalOps는 조직의 메타 컨트롤 플레인(organization meta-control plane) 입니다. 정체성(identity), 접근(access), 제안(proposal), 계보(lineage), 런타임 운영(runtime operations)을 하나의 정본(canonical) 제품 모델 위에서 다룹니다.

이 사이트는 그 제품을 운영하고 발전시키기 위한 정본 문서 모음이며, 이 페이지는 처음 들어온 사람을 위한 안내 데스크입니다. 천천히 따라오면 됩니다.

FractalOps란?

FractalOps는 한 스택의 홈페이지를 흉내 내거나, 일회성 IAM 동기화 잡을 돌리려고 존재하지 않습니다. 사람이든 에이전트든 온보딩에서 일로, 일에서 증명으로 이어지는 하나의 일관된 길을 만들기 위해 존재합니다.

핵심 성질은 세 가지입니다.

그래프 우선(graph-first) — 일, 정체성, 계보가 하나의 의미 그래프(Semantics) 위에서 연결됩니다.
제안 기반 통치(proposal-governed) — 모든 비읽기(non-read) 변경은 반드시 Proposal Plane을 통과합니다. 이것이 유일한 합법적 변경 게이트입니다.
증거 기반(evidence-backed) — 일은 코드 표면이 닿는 것으로 끝나지 않고, 그래프 계보 + 창고 사실 + 장기 증거가 모두 조회 가능할 때 비로소 “증명”됩니다.

FractalOps가 강하게 소유하는 것은 자기 자신의 런타임과 실행 기반(execution substrate) 입니다. Daytona, Nexus, Penpot 같은 이웃 스택은 대부분 integration endpoint(URL · auth · health 계약)로 취급하며, 별도의 자식 시스템처럼 통치하지 않습니다.

정본 정의의 전체 서사는 FractalOps Canonical Architecture에, 제품의 법(law)은 FractalOps Constitution에 있습니다. 시스템/컨테이너/컴포넌트 경계는 FractalOps C4 Model이 한눈에 보여줍니다.

한눈에 보는 시스템 지도

flowchart TB
  human["사람 / 에이전트"]
  portal["Portal<br/>(기본 인간 작업 표면)"]

  subgraph contexts["Layer-first slices (backend/src/fractalops/<layer>/<context>/features/)"]
    direction LR
    access["access<br/>RBAC · workbench"]
    identity["identity<br/>Dex federation · directory links"]
    policy["policy<br/>SpiceDB 결정"]
    harness["agent_execution<br/>Studio · AgentSquad"]
    semantics["semantics<br/>온톨로지 · 계보"]
    evidence["evidence<br/>Chronicle 증거"]
    connectors["connectors<br/>대상 어댑터"]
  end

  proposal["Proposal Plane<br/>(유일한 변경 게이트)"]
  temporal["Temporal<br/>(제안 기반 작업 실행)"]

  subgraph truth["Truth Planes (진실 평면)"]
    direction LR
    git["Git<br/>(desired 소스 진실)"]
    openbao["OpenBao<br/>(시크릿 진실)"]
    datahub["DataHub<br/>(카탈로그 · 계보)"]
    clickhouse["ClickHouse warehouse<br/>(창고 사실 · 증명)"]
    chronicle["Chronicle evidence<br/>(장기 증거)"]
  end

  human --> portal
  portal --> contexts
  contexts -->|"비읽기 변경"| proposal
  proposal --> temporal
  temporal -->|"적용 · 기록"| truth
  semantics --> datahub
  semantics --> clickhouse
  evidence --> chronicle
  access -.->|"시크릿 조회"| openbao

제품 흐름: 온보딩 → 일 → 제안 → 증명 → 반성적 개선

FractalOps의 안정적인 운영 문법은 단 한 줄입니다.

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

구체적인 프로젝트(new.yamon.io, sanmopia-modernization 등)는 제품을 더 좋게 만드는 강제 함수(forcing function) 일 뿐, 제품 정의를 바꾸지 않습니다.

flowchart LR
  onboarding["온보딩<br/>/ → /projects → /launch<br/>정체성 · 접근 정렬"]
  work["일(work)<br/>작업 표면 · AgentSquad 실행"]
  proposal["제안(proposal)<br/>Proposal Plane 리뷰 → 승인 → 적용"]
  proof["증명(proof)<br/>Semantics + ClickHouse + Chronicle"]
  improve["반성적 개선<br/>AgentSquad + Agent Control Surface"]

  onboarding --> work --> proposal --> proof --> improve
  improve -.->|"같은 Portal로 자기 개선"| work
  proposal -.->|"막힘 → access_recovery"| onboarding

각 단계가 의미하는 것:

온보딩 — /에서 /projects, /launch로 이어지는 진입로. 접근이 없으면 /me나 /credentials에서 정체성·자격을 고친 뒤 같은 작업 경로로 복귀합니다 (access_recovery).
일(work) — 사람과 에이전트가 실제로 작업하는 표면. 프로젝트 전달은 Daytona 워크스페이스 위에서 AgentSquad가 Studio의 direct execution path로 수행합니다.
제안(proposal) — 모든 변경은 Proposal Plane에서 리뷰·승인·게시·적용됩니다. API는 큐잉/검증만 하고, durable 실행은 Temporal이 맡습니다.
증명(proof) — Semantics/FractalOps 그래프의 의미 정체성, ClickHouse warehouse의 사실, Chronicle evidence의 장기 출처가 모두 조회 가능할 때만 증명이 닫힙니다. 어느 한 평면도 혼자 증명을 완결할 수 없습니다.
반성적 개선 — AgentSquad가 compact Agent Control Surface로 같은 Portal을 관찰하고, 개선을 같은 시스템으로 되먹입니다.

역할별 시작점

본인 상황에 맞는 진입로부터 읽으세요.

당신이 … 라면	먼저 읽을 문서
제품의 정체와 법부터 이해하고 싶다	Constitution → Canonical Architecture
시스템 경계를 C4로 보고 싶다	FractalOps C4 Model
지금 어떤 스택이 어떻게 배치돼 있는지 알고 싶다	Current Stack, Solution, and IA Map
운영자(배포 · 검증 · 시크릿 · 드리프트)다	운영 매뉴얼 (한글) → Engineering Handoff
AgentSquad/Studio 런을 돌린다	AgentSquad Operations → AgentSquad Current Implementation → AgentSquad Delivery Language
Build Plane 관찰성과 CI 증거 경계를 본다	Build Plane Observability
전체 문서가 어디 있는지 지도를 보고 싶다	Documentation Hub
스택별 요구사항/계약을 본다	Requirements Index

정본 용어 (Stable Terms)

문서 · 코드 · 에이전트 프롬프트 전반에서 아래 용어는 그대로 사용합니다. 임의로 풀어 쓰거나 동의어로 바꾸지 않습니다.

Portal
Proposal Plane
Semantics
DataHub
ClickHouse warehouse
Mimir metrics store
GlitchTip (Error Tracking Plane)
Chronicle evidence
AgentSquad
Studio
Armory
Agent Control Surface
Agent Execution
AgentSquad
execution substrate
integration endpoint
execution surface
execution workspace
agent process adapter
runtime asset
executor URL / public URL
fresh / resume
access_recovery

실행 명사는 의도적으로 좁게 씁니다.

Agent Execution = 생명주기, 재시도, 리플레이, next action.
Temporal workflow = durable 스케줄, 마감, 재시도 정책, activity 실행.
execution surface = 작업이 돌 수 있는 관리형 provider 표면.
execution workspace = 런별 워크스페이스 리스.
agent process adapter = 한 번의 시도를 실행하는 executor.

전체 용어 사전은 Execution Naming Glossary에 있습니다.

이 페이지는 안내(라우팅) 페이지입니다. 제품 법의 정본은 항상 Constitution에 있고, 전체 문서 지도는 Documentation Hub에 있습니다.