toki/rara
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rara/agent-ops/rules/project/rules.md
toki fdc86c7ff4
Some checks are pending
ci / validate (push) Waiting to run
Details
initial commit
2026-07-18 18:41:17 +09:00

4.3 KiB
Raw Blame History

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