Governed AI Gateway & Execution Platform

GoVail

AI 요청을 단순 프록시 경로와 근거·정책이 필요한 실행 경로로 분리하고,
인증, DLP, 비용, 감사, Evidence, Execution Boundary를 공통 경계에서 관리한다.

아키텍처 문서설계 결정 (Decisions)검증 기준 (Validation)GitHub

---

1. Architecture Overview: 경로 분리

Coding Agent처럼 자체 계획 및 도구 루프를 가진 클라이언트와 대화·외부 실행이 필요한 클라이언트는 요구하는 거버넌스 수준이 다르다.
GoVail은 이를 단일 파이프라인으로 강제하지 않고, 서버측 execution_profile을 기준으로 경로를 분리한다.

Credential metadata가 경로를 고릅니다. Gateway 거버넌스는 두 경로에 공통입니다.

ClientCoding Agent / Web App

↓

Shared GovernanceGoVail Gateway

• Auth
• DLP
• Rate Limit
• Cost
• Audit
• Execution Profile

↓

CODE · Thin Pathagentic_coding

Agent가 이미 계획·도구 루프를 가지고 있으면 Runtime을 겹치지 않습니다.

Gateway 통과 후 LLM Direct Proxy

WEB · Governed Pathgoverned_web

1. Router — Requested Interaction / Execution Boundary
2. Runtime — Evidence / Policy / Governed Execution

두 경로 모두 모델 호출로 모입니다

UpstreamModel

• CODE / Thin Path (agentic_coding) — Gateway에서 Auth, DLP, Rate Limit, Cost, Audit만 집행한 후 LLM으로 직행한다. 클라이언트의 자체 루프를 존중하며 불필요한 Runtime 중첩을 없앤다.
• WEB / Governed Path (governed_web) — Router가 요청의 실행 경계(route_target, execution_mode, side_effect, approval_required)를 판정하고, 최신 근거나 외부 실행이 필요한 경우에만 Runtime을 경유한다.

---

2. 핵심 설계 원칙

01

Fast Path ≠ Governed Path

모든 AI 요청이 동일한 Runtime을 필요로 하지 않는다. 자체 도구 루프를 가진 Coding Agent는 Gateway 보안만 거치는 Thin Path를 쓰고, 거버넌스가 필요한 요청만 Governed Path를 탄다.

02

Inference ≠ Authority

LLM의 출력은 확률적 제안일 뿐 실행 권한이 아니다. 실제 외부 실행 및 변경 권한은 모델 밖의 정형 스키마 검증, 사용자 승인, 결정론적 정책 경계(Deterministic Boundary)에서 집행된다.

03

Precision Requires Evidence

최신 사실과 Named Entity 주장은 모델의 parametric knowledge만으로 확정하지 않는다. Evidence Acquisition을 수행하고 근거-주장 정합성을 검증한다. 검색 실패는 비존재의 증거가 아니다.

04

Applications Own Their State

GoVail Core는 개별 Application의 DB, 상태 저장소, 워크플로우를 소유하지 않는다. Gateway, Evidence, Policy, Audit 경계만 Core가 담당하고 도메인 상태는 Application에 격리한다.

---

3. Execution Pipeline

요청이 들어와 실행되고 감사 로그로 기록되기까지의 각 단계별 책임과 검증 경계다.

Execution Pipeline

요청에서 실행까지의 검증 단계

01

GoVail GatewayRust / Axum

• Auth: API Key & Profile SSOT
• DLP: PII/Secret 패턴 차단
• Cost: 토큰 및 Rate Limit 통제
• Routing: CODE vs WEB 분기

02

Semantic RouterFastAPI (/decide)

• Route Target: llm vs runtime
• Execution Mode: direct / workflow / approval
• Side Effect: read vs write/execute
• Boundary: 실행 권한 분리

03

Governed RuntimeFastAPI / Engine

• Evidence: 최신 사실·엔티티 취득
• Grounding: 근거-주장 정합성 검증
• Approval: 변경 작업 Payload Hash 검증
• Durable: Fail-closed 안전 실행

04

Audit & ProvenanceJSON Schema SSOT

• Schema: 정형 이벤트 스트림
• Audit Trail: 요청-판단-실행 전 과정 불변 기록
• Contract: 크로스 서비스 무결성
• Observability: Prometheus / Loki

---

4. Architecture Evolution

복잡도를 계속 추가하는 것보다 Core가 소유해야 할 책임과 경계를 명확히 하는 방향으로 발전했다.

초기 접근	발견한 문제	현재 결정
모든 요청을 Runtime 경유	Coding Agent의 자체 루프와 역할 중복	CODE Thin Path
중앙 Memory	Application State 경계 침범	App-owned State
범용 Workflow	Core 복잡도 증가	App-owned Workflow
LLM 기반 실행 판단	실행 Authority 불명확	Deterministic Boundary
Parametric Knowledge 의존	최신 사실 및 정밀 Claim 오류	Evidence Dependency
Core에 다양한 Agent 기능 집약	책임 경계 불명확	Gateway / Governance 중심으로 축소

초기모든 요청을 Runtime 경유

문제Coding Agent의 자체 루프와 역할 중복

현재CODE Thin Path

초기중앙 Memory

문제Application State 경계 침범

현재App-owned State

초기범용 Workflow

문제Core 복잡도 증가

현재App-owned Workflow

초기LLM 기반 실행 판단

문제실행 Authority 불명확

현재Deterministic Boundary

초기Parametric Knowledge 의존

문제최신 사실 및 정밀 Claim 오류

현재Evidence Dependency

초기Core에 다양한 Agent 기능 집약

문제책임 경계 불명확

현재Gateway / Governance 중심으로 축소

---

5. 결론: 복잡도를 통제하는 도구들

1인 개발자가 분산된 여러 서비스를 안정적으로 다루기 위해서는 뛰어난 기억력보다는 시스템적인 강제력이 필요하다.

"1인 개발자가 여러 분산 서비스를 안정적으로 다루기 위해서는 뛰어난 기억력보다는 시스템적인 강제력이 필요합니다."

— GoVail Core Architecture Decision

01

OpenAPI & JSON Schema SSOT

서비스 간 호출 규격을 코드 주석이나 문서가 아닌 스키마로 단일화. 코드 생성 및 런타임 직렬화 검증을 강제합니다.

02

Deterministic Policy Boundary

모델의 확률적 제안과 시스템 실행 권한을 물리적으로 분리. 외부 Write는 사용자 승인과 해시 검증을 통과해야만 실행됩니다.

03

Credential-driven Path Isolation

클라이언트 헤더에 의존하지 않고 서버측 자격증명 메타데이터(`execution_profile`)로 Thin Path와 Governed Path를 엄격히 분기합니다.

04

Executable Contract Tests

모든 라우팅 판정과 페일클로즈(Fail-closed) 동작을 CI/CD 파이프라인에서 자동 검증하여 회귀 버그를 원천 차단합니다.

---

6. 검증 체계 (Validation)

아키텍처가 문서에만 존재하는 것이 아니라 실제 테스트와 계약으로 검증되고 있음을 보장한다.

• Gateway / Router / Runtime Contract Tests — OpenAPI / JSON Schema 기반 계약 일치 및 Credential Profile 불변성 검증
• Execution Boundary Edge-case Tests — 단순 설명·인용과 실제 실행 요청의 구분, READ/WRITE 분리 및 승인 경계 테스트
• Evidence Adversarial Benchmark — 날조된 최신 사실 및 불일치 Claim 검출, 근거-주장 간 일관성 검증
• External-action E2E Validation — 승인 Payload Hash 무결성, 승인 없는 외부 변경 차단(Fail-closed) 동작 검증
• MCP Protocol Interoperability Tests — GoVail MCP의 Envelope/Capability 계약 준수 및 상태 비소유 원칙 테스트

상세 검증 항목은 Validation에서 확인할 수 있다.

---

Technology Stack

• Rust (Axum)
• Python (FastAPI)
• OpenAPI
• JSON Schema
• Docker