---
domain: platform-common
last_rule_review_commit: null
last_rule_updated_at: 2026-07-18
---

# platform-common

## 목적 / 책임

각 plane이 공유하는 설정, PostgreSQL 연결, HTTP lifecycle, 관측성, artifact 저장, 외부 integration port를 제공한다. 도메인 로직이 특정 인프라 제품에 결합되지 않도록 adapter 경계를 유지한다.

## 포함 경로

- `packages/go/artifact/` — 교체 가능한 artifact store 계약과 filesystem 구현
- `packages/go/config/` — 서비스별 YAML 설정 로딩과 검증
- `packages/go/database/` — pgx 연결 lifecycle과 sqlc 생성 adapter
- `packages/go/httpserver/` — 공통 health/readiness와 HTTP server lifecycle
- `packages/go/integration/` — source, retrieval, embedding, reranking, generation, secret의 product-neutral port
- `packages/go/observability/` — logging, metrics, tracing 조립
- `configs/`, `deploy/` — 로컬 설정 예시와 배포 자산

## 제외 경로

- `packages/go/controlplane/`, `db/` — 수명주기 상태 모델과 쿼리 원본
- `packages/go/rag/` — 온라인 RAG 요청 의미와 응답 계약
- `packages/go/workflow/`, `packages/python/` — workflow와 adaptation 실행 의미

## 주요 구성 요소

- `database.Store` — pgx pool과 생성된 sqlc query 접근점
- `artifact.Store` / `artifact.Filesystem` — artifact 저장 port와 로컬 구현
- `integration.Ports` — 외부 capability의 제품 중립 계약
- `httpserver.Start` — 공통 HTTP lifecycle
- `observability.SetupTracing` — trace exporter 설정

## 유지할 패턴

- 공통 패키지는 plane별 정책을 소유하지 않고 작은 port와 lifecycle adapter에 집중한다.
- integration instance는 versioned capability와 secret reference로 구성한다.
- artifact URI와 content hash를 유지해 lineage를 추적할 수 있게 한다.
- readiness는 실제 필수 dependency 상태를 반영하고 health와 구분한다.
- 설정 예시에는 로컬 기본값만 두며 운영 secret을 포함하지 않는다.

## 다른 도메인과의 경계

- **control-plane**: 공통 persistence adapter를 제공하되 스키마와 수명주기 규칙은 control-plane이 소유한다.
- **rag-data-plane**: retrieval/generation port를 제공하되 release 해석과 응답 의미는 rag-data-plane이 소유한다.
- **workflow-execution**: config, database, artifact adapter를 제공하되 lease와 executor 상태 전이는 workflow-execution이 소유한다.

## 금지 사항

- 공통 패키지에 control-plane, RAG, workflow의 유즈케이스 정책을 넣지 않는다.
- integration port를 특정 vendor의 request/response 타입으로 노출하지 않는다.
- config, log, trace, 예제 배포 파일에 secret이나 credential 원문을 남기지 않는다.