Architecture Overview

아키텍처 개요 (Architecture Overview)

이 페이지는 런타임 토폴로지와 실행 흐름만 다룹니다.

먼저 FractalOps 헌법으로 제품 법을 읽고, FractalOps Canonical Architecture로 제품 정의를 읽으세요. 현재 스택/솔루션/내비게이션 라우팅은 Current Stack, Solution, and IA Map이 단일 원천(SSOT)입니다. 시스템/컨테이너/컴포넌트 경계를 먼저 맞춰야 하면 FractalOps C4 Model을 보세요.

빠른 길잡이 — 새 엔지니어용

“내가 짠 코드가 실제로 어떤 경로를 타는가?”를 먼저 잡으세요. 사람이나 에이전트가 무언가를 바꾸려고 하면, 그 요청은 절대 route에서 직접 실행되지 않고 Proposal Plane -> Temporal -> operation asset control / connector를 거쳐 진실 평면에 기록됩니다. 이 단방향 규율이 FractalOps 런타임의 척추입니다.

핵심 실행 체인 (Core Execution Chain)

flowchart TB
  input["Portal 또는 API 입력"]
  validate["request 계약 검증\n(Pydantic RequestIn)"]
  sim["proposal / policy 시뮬레이션\n(변경 요청 시)"]
  enqueue["큐 또는 워크플로 enqueue"]
  temporal["Temporal workflow / activity"]
  rac["operation asset control"]
  exec["connector 또는 executor"]
  proof["audit / evidence / graph projection"]

  input --> validate --> sim --> enqueue --> temporal --> rac --> exec --> proof

이 체인의 각 단계는 코드에서 실제 모듈로 존재합니다.

단계	코드 근거
HTTP/CLI/MCP 계약 검증	backend/src/fractalops/interfaces/<transport>/<context>/features/<feature>/
큐 / enqueue	backend/src/fractalops/orchestration/workflow/features/submit_job/
Temporal workflow / activity	backend/src/fractalops/orchestration/workflow/features/, backend/src/fractalops/adapters/workflow/features/
operation asset control	backend/src/fractalops/application/access/features/runtime_asset_control/
connector / executor	backend/src/fractalops/application/connectors/features/, backend/src/fractalops/adapters/connectors/features/
evidence / graph projection	backend/src/fractalops/application/evidence/features/, backend/src/fractalops/application/semantics/features/

계층 배치 (Layer Placement)

FractalOps 백엔드는 헥사고날(hexagonal) 레이어링을 따릅니다. 의존성 방향은 항상 안쪽(domain)을 향합니다.

flowchart LR
  subgraph L["product law"]
    L0["L0\n헌법 / 제품 법"]
    L1["L1\nfractalops-contract 정규 계약"]
  end

  subgraph code["backend/src/fractalops/<layer>/<context>/features/<feature>/"]
    domain["domain\n불변식 · 집합체 계약 · 온톨로지 의미"]
    application["application\n유스케이스 · 포트 · source-owned 정책"]
    adapter["adapters\nDB · provider · 외부 변환"]
    interface["interfaces\nHTTP · CLI · MCP 바인딩"]
    orchestration["orchestration\n조립 · 프로세스 흐름"]
  end

  L0 --> L1 --> domain
  interface --> application --> domain
  adapter --> application
  orchestration --> interface
  orchestration --> adapter

레이어 간 의존 방향은 tach.toml이 강제합니다. domain은 fastapi/pydantic/sqlalchemy를 import하지 않고, application은 adapters/interfaces/orchestration/platform에 의존하지 않습니다 (Tach DDD / Feature Slice 표준 참고).

런타임 경계 (Runtime Boundaries)

• Portal: 1차 인간 워크플로 표면
• api / worker / execution-runtime: FractalOps 소유 런타임 구성요소
  • FastAPI entrypoint: fractalops.orchestration.platform.features.serve_http_api.main:app
  • Temporal worker: fractalops.orchestration.platform.features.serve_workflow_worker.main
• Temporal: 큐잉된 실행과 장기 오케스트레이션
• OpenBao: 비밀의 단일 원천(secret source of truth)
• DataHub: 프로젝트 RDF steward 에이전트가 채우는 카탈로그/계보 누적 평면
• ClickHouse warehouse: 웨어하우스 사실/증명 평면. 같은 steward 생애주기를 이벤트/사실로 저장
• PostHog / OpenTelemetry: 분산 제품 행동/런타임 이벤트 소스. ClickHouse 누적 전에 공유 온톨로지로 분류
• Chronicle evidence: 장기 증명 평면
• PlaywrightGrid: Studio/AgentSquad용 브라우저 실행 평면 (로컬 브라우저 대체 경로는 런타임 계약이 아님)
• operation assets: asset_id 또는 role로 선택되는 타입드 실행 표면
• LangBoard: 생애주기 표면, 지식 위키, 봇 자동화 표면

실행 substrate vs 통합 endpoint

FractalOps는 자신을 운영하고 개선하는 데 필요한 실행 substrate만 강하게 소유합니다.

강하게 소유하는 substrate:

• portal
• api
• worker
• execution-runtime
• Temporal
• CNPG-backed Supabase Core / Storage / Realtime
• Daytona
• PlaywrightGrid

그 외 인접 도구는 보통 통합 endpoint(integration endpoint) 입니다.

• URL, 인증, health 계약으로 기술됩니다.
• 제품 진실의 소유자가 되지 않습니다.
• 실행 평면이 진짜로 의존하지 않는 한, FractalOps가 스택-로컬 생애주기 로직을 떠안지 않습니다.

Operation Asset Control (운영 자산 제어)

FractalOps는 raw vmid, raw namespace, 스택별 provider 키워드를 정규 제어 명사로 취급하지 않습니다. 대신 타입드 selector(asset_id / role) 뒤로 머신 제어를 숨깁니다.

flowchart LR
  req["operation 또는 CLI 요청"] --> svc["RuntimeAssetControlService"]
  svc --> ctrl["RuntimeAssetController"]
  ctrl --> asset["operation asset\n(lxc · vm · kubernetes)"]

코드 근거: RuntimeAssetControlService는 backend/src/fractalops/application/access/features/runtime_asset_control/service.py에 있습니다. 자산 계약은 backend/src/fractalops/domain/access/features/runtime/assets.py가 소유합니다.

application/access/features/runtime_asset_control/service.py

class RuntimeAssetControlService:
    def __init__(self, *, runtime_assets: list[RuntimeAssetDescriptor],
                 runtime_asset_roles: dict[str, str]) -> None: ...

    def list_assets(self) -> list[RuntimeAssetDescriptor]: ...
    def get_asset(self, *, asset_id: str = "", role: str = "") -> RuntimeAssetDescriptor: ...
    def check(self, *, asset_id: str = "", role: str = "") -> RuntimeAssetHealth: ...
    def run_command(self, ...) -> RuntimeCommandResult: ...
    def http_request(self, ...) -> RuntimeHttpResult: ...

자산 디스크립터 타입은 domain/access/features/runtime/assets.py가 정의합니다.

domain/access/features/runtime/assets.py

RuntimeAssetKind = Literal["lxc", "vm", "kubernetes"]

class RuntimeAssetDescriptor(_RuntimeAssetRecord):
    __fields__ = (
        "asset_id", "kind", "role", "title", "summary",
        "locator", "capabilities", "bindings",
        "entry_url", "manage_url", "executor_url",
    )

selector 규칙:

• 대상이 정확히 하나여야 하면 asset_id를 쓴다.
• 연산이 정규 런타임 책임에 결속되면 role을 쓴다.

URL 규칙(헌법의 네이밍 법과 일치):

• public URL(=entry_url)은 사람/브라우저 진입용
• executor URL(=executor_url)은 머신 제어용
• 엣지 보호나 브라우저 라우팅이 자동화를 오염시킬 수 있으면 둘을 분리해야 한다

동기 HTTP 호출은 foundation HttpClient로

스택 어댑터의 동기 아웃바운드 HTTP는 머신 경계가 operation asset control에 속하지 않는 한 foundation HttpClient를 선호합니다.

foundation/infrastructure/providers/http_client.py

class HttpClient:
    def __init__(self, *, timeout_seconds: int = 10, verify_tls: bool = True,
                 headers: Mapping[str, str] | None = None,
                 trust_env: bool = False) -> None: ...

    def request(self, *, method: str, url: str,
                headers=None, params=None, content=None,
                json_body=None, form_body=None, files=None) -> HttpResult: ...

HttpResult는 status_code, body, json_body, headers를 담는 frozen dataclass이며, httpx.HTTPError는 status_code=0으로 흡수되어 호출부가 예외 분기를 강제당하지 않습니다.

진실 평면 (Truth Planes)

flowchart TB
  subgraph desired["원하는 상태"]
    git["Git\n(원하는 코드 / desired state)"]
    bao["OpenBao\n(secret source of truth)"]
  end
  subgraph proof["사실 / 증명"]
    dh["DataHub\n(catalog + lineage)"]
    ch["ClickHouse warehouse\n(warehouse facts + proof)"]
    cr["Chronicle evidence\n(장기 증명)"]
  end
  subgraph signal["신호 소스"]
    ph["PostHog\n(제품 행동)"]
    otel["OpenTelemetry\n(trace/metric/log)"]
    mimir["Mimir\n(metrics TSDB)"]
  end

  ph --> otel
  otel --> mimir
  otel -->|온톨로지 분류 후| ch
  ch --> cr
  dh -.->|검색/내비| ch

각 평면의 소유 경계는 헌법 진실 평면 법이 정의합니다. 연결 코드는 각 레이어의 semantics, evidence, feature_plane 컨텍스트 아래 outcome slice가 소유합니다.

검증과 생성 (Validation and Generation)

항목	명령 / 근거
정규 Python 테스트 러너(조용한 fail-only)	python -m fractalops.testing.unittest_runner / make test-unit
아키텍처 경계 린터	tach check --dependencies --interfaces / make architecture-lint (표준)
큐레이트된 contract suite	ops/testing/run_contract_suite.py / make test-contract
cross-artifact runtime 검증	scenarios/<outcome> / pnpm test
생성 산출물 드리프트 가드	make codegen-check (backend/src/fractalops_generated/는 codegen 소유)

로컬 Docker 기반 integration 레인은 이 호스트에서 정규가 아닙니다.

운영 규칙 (Operational Rules)

• API는 proposal에 결속된 작업의 직접 부수효과를 절대 수행하지 않는다.
• Temporal이 실행을 소유한다.
• 정책 불확실성은 fail-closed가 기본값이다.
• 변경 후에도 증명은 조회 가능해야 한다.
• 라이브 fanout은 portal_live_events를 쓰고, 라이브 UI는 harness-projection을 읽는다.
• AgentSquad 공개 연속성은 fresh | resume로만 노출된다.
• Studio는 공유 에이전트 실행 경계이며, 프로젝트 에이전트 스쿼드는 Studio를 통해 돌고, AgentSquad는 Studio 위에서 도는 FractalOps 자기개선 워크플로다.
• Armory가 MCP/tool pack 구성과 에이전트별 초기화를 소유한다. 브라우저 실행은 새 Armory 관리 MCP가 명시적으로 대체하지 않는 한 PlaywrightGrid 전용이다.
• 런타임 제어는 타입드 operation asset 계약 뒤에 머문다.
• 보조 도구는 정규 제어 네이밍을 재정의하거나 우연히 진실 소유자가 되어서는 안 된다.

런타임 모드 (Runtime Modes)

런타임은 여러 모드를 지원합니다. 의존성이 항상 있다고 가정하지 말고 settings를 먼저 확인하세요.

from fractalops.config.settings import settings

if not settings.temporal_enabled:
    # Temporal 비활성 모드를 graceful 하게 처리
    pass

설정 근거(backend/src/fractalops/config/):

• temporal_enabled: bool = Field(default=True, alias="FRACTALOPS_TEMPORAL_ENABLED") (config/temporal.py)
• secret_backend: str = Field(default="env", alias="FRACTALOPS_SECRET_BACKEND") (config/core.py)
• settings = Settings()는 CoreSettings, TemporalSettings, DatabaseSettings 등 도메인별 설정 클래스를 합성합니다 (config/settings.py).
• 임베디드 SQLite 런타임은 제거되었습니다. database_runtime_url()은 FRACTALOPS_DATABASE_URL이 비어 있거나 미해결 ref:이면 예외를 던집니다(테스트 한정 sqlite 예외만 허용).

관련 문서

• FractalOps Constitution
• FractalOps Canonical Architecture
• Current Stack, Solution, and IA Map
• Dev Preview Plane
• Engineering Handoff
• Pydantic Boundary Contracts
• Portal Control Plane Requirements