# RARA 프로젝트 규칙

## 응답 언어

- 사용자에게 보이는 답변과 프로젝트 문서는 기본적으로 한국어로 작성한다.
- 코드 식별자, 공개 API 필드, 프로토콜 이름은 기존 영문 표기를 유지한다.

## 프로젝트 개요

- RARA는 저장소와 모델 제품에 종속되지 않도록 설계된 내부 RAG 수명주기 플랫폼이다.
- 제어 플레인, 온라인 RAG 데이터 플레인, Go/Python 실행기를 한 저장소에서 운영한다.
- 현재 코드는 플랫폼 스캐폴드 단계이며, 실제 검색 백엔드·모델 공급자·소스 커넥터는 버전이 있는 integration으로 확장한다.

## 주요 구조

| 경로 | 역할 |
|------|------|
| `apps/` | control-plane, rag-api, Go worker 실행 진입점과 향후 운영 UI |
| `packages/go/` | Go 도메인 로직, 포트, 공통 런타임 어댑터 |
| `packages/python/` | Python adaptation executor와 생성된 Protobuf 클라이언트 |
| `api/openapi/` | 공개 HTTP/JSON 및 SSE 계약 |
| `api/proto/` | Go/Python executor 간 내부 gRPC 계약 |
| `db/` | PostgreSQL 스키마와 sqlc 쿼리 원본 |
| `gen/` | Protobuf에서 생성된 Go 코드 |
| `configs/`, `deploy/` | 서비스 설정 예시와 로컬 배포 자산 |

## 기술 스택

- Go 1.26, Cobra, Fx, pgx, sqlc
- Python 3.12, gRPC, pytest, Ruff
- PostgreSQL 18
- OpenAPI 3.1, Protobuf/gRPC, HTTP/JSON, SSE
- Make 기반 생성·검증·빌드 흐름

## 프로젝트 특화 컨벤션

- PostgreSQL은 제어 상태와 lineage만 저장한다. 대형 artifact와 retrieval index를 PostgreSQL에 결합하지 않는다.
- 외부 저장소·검색·모델·secret 기능은 `packages/go/integration`의 product-neutral port 뒤에 둔다.
- `api/proto/`와 `db/migrations/`, `db/queries/`를 생성 코드의 원본으로 취급한다.
- `gen/go/`, `packages/python/src/rara/v1/*_pb2*.py`, `packages/go/database/dbgen/`은 직접 수정하지 않고 `make proto` 또는 `make sqlc`로 갱신한다.
- 공개 RAG handler를 변경할 때는 `api/openapi/rara-v1.yaml`과 요청·응답·SSE 동작을 함께 검토한다.
- executor wire contract를 변경할 때는 Protobuf 호환성을 유지하고 Go/Python 생성물을 함께 갱신한다.
- 기본 검증 진입점은 `make test`와 `make build`이며, CI는 sqlc diff, Go 테스트, Ruff, Python 테스트, 서비스 빌드를 수행한다.

## 도메인 매핑

| 경로 패턴 | 도메인 | rules.md |
|----------|--------|----------|
| `apps/control-plane/**` | control-plane | `agent-ops/rules/project/domain/control-plane/rules.md` |
| `apps/client/**` | control-plane | `agent-ops/rules/project/domain/control-plane/rules.md` |
| `packages/go/controlplane/**` | control-plane | `agent-ops/rules/project/domain/control-plane/rules.md` |
| `db/migrations/**`, `db/queries/**` | control-plane | `agent-ops/rules/project/domain/control-plane/rules.md` |
| `apps/rag-api/**` | rag-data-plane | `agent-ops/rules/project/domain/rag-data-plane/rules.md` |
| `packages/go/rag/**` | rag-data-plane | `agent-ops/rules/project/domain/rag-data-plane/rules.md` |
| `api/openapi/**` | rag-data-plane | `agent-ops/rules/project/domain/rag-data-plane/rules.md` |
| `apps/worker/**` | workflow-execution | `agent-ops/rules/project/domain/workflow-execution/rules.md` |
| `packages/go/workflow/**` | workflow-execution | `agent-ops/rules/project/domain/workflow-execution/rules.md` |
| `packages/python/**` | workflow-execution | `agent-ops/rules/project/domain/workflow-execution/rules.md` |
| `api/proto/**`, `gen/go/rara/v1/**` | workflow-execution | `agent-ops/rules/project/domain/workflow-execution/rules.md` |
| `packages/go/artifact/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `packages/go/config/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `packages/go/database/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `packages/go/httpserver/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `packages/go/integration/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `packages/go/observability/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |
| `configs/**`, `deploy/**` | platform-common | `agent-ops/rules/project/domain/platform-common/rules.md` |