시스템 아키텍처
Fascia는 설계 시 인텔리전스와 런타임 실행을 Two-Plane 아키텍처(이중 플레인 구조)로 분리합니다. Control Plane(컨트롤 플레인)은 스펙 설계, 검증, 배포를 담당합니다. Data Plane(데이터 플레인)은 고객의 자체 클라우드 인프라에서 결정적 실행 로직을 수행합니다.
아키텍처 다이어그램
User ─── Chat Studio ──┐
Flow Studio ───┤── Build Phase (Fascia-hosted)
Deploy ────────┘ ├── Spec Registry
├── Safety Agent
└── Risk Engine
Runtime (Customer GCP)
├── Cloud Run (Executor)
├── Cloud SQL (Postgres)
├── Cloud Scheduler
├── Secret Manager
└── Pub/Sub (optional)
Two-Plane 아키텍처
Control Plane (Fascia 호스팅)
Control Plane은 설계가 이루어지는 곳입니다. Fascia가 호스팅하고 관리합니다.
| 컴포넌트 | 역할 |
|---|---|
| Chat Studio | 자연어로 Entity, Tool, Flow를 설계하는 대화형 인터페이스입니다. LLM 기반으로 사용자의 의도를 구조화된 스펙으로 변환합니다. |
| Flow Studio | ReactFlow 기반의 시각적 그래프 편집기로, Tool 실행 로직을 설계합니다. 드래그 앤 드롭 노드 배치, 연결 검증, 실시간 타입 체킹을 지원합니다. |
| Spec Registry | 모든 Entity, Tool, Policy, Invariant(불변식) 스펙의 버전 관리 저장소입니다. 스펙은 버전이 매겨지면 불변이 되며, 변경은 새 버전을 생성합니다. |
| Safety Agent | Tool 스펙을 검토하고, 안전하지 않은 패턴을 감지하며, 수정을 제안하고, 테스트 케이스를 생성 하는 AI 기반 분석 컴포넌트입니다. 신뢰성을 위해 서로 다른 LLM 패밀리 간 멀티모델 크로스체크를 사용합니다. 빌드 단계에서만 작동합니다. |
| Risk Engine | Tool Flow 그래프를 Risk 분류 규칙에 따라 평가합니다. Green, Yellow, Red Risk Level을 할당합니다. Red Tool은 배포가 차단됩니다. |
Control Plane은 스펙, 메타데이터, 배포 기록만 저장합니다. 고객 비즈니스 데이터를 저장하거나 처리하지 않습니다.
Data Plane (고객 GCP)
Data Plane은 실행이 이루어지는 곳입니다. 모든 컴포넌트는 BYOC 모델에 따라 고객의 자체 GCP 프로젝트 내에서 실행됩니다.
| 컴포넌트 | 역할 |
|---|---|
| Cloud Run (Executor) | 컴파일된 Tool 실행 로직을 수행합니다. Executor는 SpecBundle(컴파일된 스펙)을 해석하고 Flow 그래프를 결정적으로 실행하는 Go 바이너리입니다. |
| Cloud SQL (Postgres) | 워크스페이스당 하나의 PostgreSQL 인스턴스입니다. 고객 애플리케이션의 모든 비즈니스 데이터를 저장합니다. 배포 시 자동으로 프로비저닝됩니다. |
| Cloud Scheduler | 스케줄에 따라 크론 트리거 Tool을 호출합니다. 배포 시 Terraform을 통해 관리됩니다. |
| Secret Manager | 모든 민감 데이터를 저장합니다: API 키, OAuth 클라이언트 시크릿, 데이터베이스 비밀번호, JWT 서명 키. 시크릿은 고객의 GCP 프로젝트를 벗어나지 않습니다. |
| Pub/Sub | (선택 사항) 큐 트리거 Tool과 Tool 간 이벤트 기반 워크플로를 활성화합니다. |
기술 스택
| 레이어 | 기술 | 역할 |
|---|---|---|
| 프론트엔드 | React + TypeScript + ReactFlow | Chat Studio, Flow Studio, Management Console |
| 플랫폼 백엔드 | Node.js + TypeScript + Fastify | Spec Registry, Safety Agent, Risk Engine, Deploy Pipeline |
| Executor | Go | Cloud Run에서의 Flow 그래프 실행 |
| 플랫폼 데이터베이스 | PostgreSQL | Spec Registry, 워크스페이스 메타데이터, 배포 기록 |
| 고객 데이터베이스 | PostgreSQL (Cloud SQL) | 워크스페이스당 하나의 인스턴스, 자동 프로비저닝 |
| LLM | 멀티모델 크로스체크 | Claude + GPT-4 (다른 패밀리), Gemini 폴백 |
주요 기술 결정
Executor에 Go를 선택한 이유는?
Executor는 고객의 GCP 프로젝트 내 Cloud Run에서 실행됩니다. 고객 제품의 최종 사용자가 보내는 모든 API 호출이 Executor를 거치기 때문에, 콜드 스타트 시간이 매우 중요합니다. Go는 Cloud Run에서 약 50ms의 콜드 스타트를 달성하며, 이는 Node.js의 300-500ms와 비교됩니다. Executor는 명확하게 경계가 정해진 컴포넌트로, Flow 그래프 엔진과 노드 핸들러가 구현되면 변경이 드뭅니다. 성능 이점이 이중 언어 코드베이스 유지의 비용을 정당화합니다.
플랫폼 백엔드에 Fastify를 선택한 이유는?
Fascia의 핵심 추상화는 스펙이며, 스펙은 JSON Schema로 정의됩니다. Fastify는 Ajv를 통한 네이티브 JSON Schema 검증을 제공하므로, 도메인 정의에서 API 검증, 자동 생성 Swagger 문서까지 라우트 수준의 스키마 선언이 자연스럽게 흐릅니다. 이러한 정렬은 Zod 기반 프레임워크(Hono)나 데코레이터 기반 프레임워크(NestJS)에서 필요한 변환 레이어를 제거합니다.
PostgreSQL을 선택한 이유는?
PostgreSQL은 이중 역할을 수행합니다. JSONB 컬럼은 스펙 콘텐츠를 효율적으로 저장하면서 스펙 스키마 발전의 유연성을 유지합니다. 관계형 테이블은 워크스페이스 메타데이터, 배포 기록, 감사 로그를 완전한 트랜잭션 무결성과 함께 처리합니다. 플랫폼 데이터베이스와 고객 데이터베이스 모두에 동일한 기술을 사용하여 운영을 단순화하고 버그의 발생 범위를 줄입니다.
핵심 설계 원칙
| 원칙 | 설명 |
|---|---|
| Spec이 진실의 원천 | 모든 런타임 동작은 구조화된 스펙에서 도출됩니다. Entity, Tool, Policy는 선언적으로 정의되고 실행 아티팩 트로 컴파일됩니다. |
| 런타임에서 LLM 사용 금지 | LLM (Claude, GPT, Gemini)은 Control Plane의 빌드/설계 단계에서만 사용됩니다. Executor는 어떤 LLM API도 호출하지 않습니다. 모든 런타임 동작은 결정적입니다. |
| 결정적 실행 | 모든 Tool 실행은 동일한 9단계 계약을 따릅니다. 동일한 입력과 데이터베이스 상태가 주어지면, 출력은 항상 동일합니다. |
| Policy 우선 | 안전하지 않은 연산은 실행되기 전, 설계 시에 감지되고 차단됩니다. Risk Engine은 구조적 안전 문제가 있는 Tool의 배포를 방지합니다. |
| BYOC | 모든 고객 데이터와 런타임 인프라는 고객의 자체 GCP 프로젝트에 존재합니다. Fascia는 고객 비즈니스 데이터를 저장하지 않습니다. BYOC 배포 참조. |
Execution Contract
모든 Tool 실행은 이 정확한 9단계 시퀀스를 따릅니다. LLM이 관여하지 않습니다. 예외는 없습니다.
| 단계 | 작업 | 설명 |
|---|---|---|
| 1 | 입력 검증 | Tool의 선언된 입력 JSON Schema에 대해 요청 페이로드를 확인합니다. |
| 2 | 인가 | JWT 토큰을 검증하고, RBAC 역할을 확인하며, 행 수준 접근 정책을 적용합니다. |
| 3 | 정책 검사 | 참조된 모든 Policy (속도 제한, 예산 확인, 행 제한)를 평가합니다. |
| 4 | 트랜잭션 시작 | 이후의 모든 쓰기 작업을 위한 데이터베이스 트랜잭션을 시작합니다. |
| 5 | Flow 그래프 실행 | DAG를 노드별로 순회하며 엣지를 따릅니다. 각 노드는 자신의 작업 (read, write, transform 등)을 수행합니다. |
| 6 | Invariant 강제 | 수정된 Entity의 모든 Invariant를 확인합니다. Invariant가 실패하면 트랜잭션이 롤백됩니다. |
| 7 | 커밋 / 롤백 | 모든 단계가 성공하면 트랜잭션을 커밋합니다. 실패 시 롤백합니다. |
| 8 | 감사 로그 기록 | 작업을 감사 로그에 기록합니다 (타임스탬프, 사용자, Tool, 작업, 변경 전/후 상태). |
| 9 | 출력 반환 | Tool의 출력 JSON Schema에 맞는 정규화된 응답을 호출자에게 전송합니다. |
데이터 흐름
설계에서 실행까지 스펙의 라이프사이클입니다:
- 설계 -- 사용자가 Control Plane의 Chat Studio 또는 Flow Studio를 통해 스펙을 생성하거나 수정합니다.
- 검증 -- Safety Agent가 스펙에서 안전하지 않은 패턴을 분석합니다. Risk Engine이 Risk Level을 할당합니다.
- 저장 -- 검증된 스펙이 Spec Registry에 새로운 불변 버전으로 저장됩니다.
- 컴파일 -- 스펙이 SpecBundle (자체 완결형 실행 아티팩트)로 컴파일됩니다.
- 배포 -- Terraform이 고객의 GCP 인프라를 프로비저닝하거나 업데이트합니다. SpecBundle이 Cloud Run에 배포됩니다.
- 실행 -- 최종 사용자가 HTTP를 통해 Tool을 호출합니다. Executor가 SpecBundle을 로드하고 Execution Contract를 따릅니다.
관련 문서
- BYOC 배포 -- 고객의 GCP 프로젝트에서 런타임 인프라가 프로비저닝되는 방법을 설명합니다
- Entity 스펙 스키마 -- 핵심 비즈니스 객체 추상화를 정의합니다
- Tool 스펙 스키마 -- 실행 가능한 서버 로직 정의를 설명합니다
- Risk 분류 규칙 -- Risk Engine의 Tool 안전성 평가 방법을 설명합니다