57 lines
3.2 KiB
Markdown
57 lines
3.2 KiB
Markdown
---
|
|
domain: platform-common
|
|
last_rule_review_commit: d4546ecbfdd0e166b8c634092c0d7c5009618cea
|
|
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.Registry` / `integration.Factory` — manifest 이름으로 외부 integration factory를 조회·구성하는 계약
|
|
- `integration.SourceConnector`, `RetrievalBackend`, `EmbeddingProvider`, `RerankProvider`, `GenerationProvider`, `SecretResolver` — 제품 중립 capability port
|
|
- `httpserver.Start` — 공통 HTTP lifecycle
|
|
- `observability.SetupTracing` — trace exporter 설정
|
|
|
|
## 유지할 패턴
|
|
|
|
- 공통 패키지는 plane별 정책을 소유하지 않고 작은 port와 lifecycle adapter에 집중한다.
|
|
- integration manifest는 schema version과 capability를 노출하고 factory에는 config와 secret reference만 전달한다.
|
|
- artifact URI와 content hash를 유지해 lineage를 추적할 수 있게 한다.
|
|
- filesystem artifact key는 configured root 밖으로 벗어나는 절대 경로와 traversal을 거부한다.
|
|
- 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 원문을 남기지 않는다.
|