아키텍처

이 문서는 저장소 안에서 어떤 앱과 패키지가 어떤 역할을 하는지 빠르게 찾기 위한 지도입니다. 기능을 수정할 때 먼저 앱 경계와 공유 패키지 경계를 확인하세요.

모노레포 구조

이 저장소는 Turborepo + pnpm 워크스페이스로 구성됩니다.

애플리케이션

• apps/web
• apps/control-api
• apps/query-api
• apps/realtime-service
• apps/ingest-worker
• apps/export-service

패키지

• packages/trpc
• packages/db
• packages/auth
• packages/ingest
• packages/realtime
• packages/exporter
• packages/sdk

데이터 계층

• PostgreSQL + Prisma: 사용자, 조직, 프로젝트, 대시보드, 세그먼트, 알림, usage
• MotherDuck/DuckDB 또는 ClickHouse: 이벤트와 집계 분석. ANALYTICS_BACKEND로 하나를 선택하며 기본값은 motherduck입니다.
• Redis: queue, cache, realtime 보조 상태

docs 위치

이번 /docs는 별도 앱이 아니라 apps/web 안의 docs route입니다.

• source config: apps/web/source.config.ts
• loader: apps/web/lib/source.ts
• page route: apps/web/app/docs
• search route: apps/web/app/api/docs/search/route.ts
• content: apps/web/content/docs

주의할 점

• apps/web은 control plane UI와 gateway 역할을 함께 합니다.
• data plane 서비스는 분리할 수 있지만, 로컬 개발에서는 fallback 경로가 함께 동작합니다.
• 공유 패키지 변경은 web, worker, API 서비스에 동시에 영향을 줄 수 있습니다.

다음 단계

• API 경계는 서비스 Plane과 엔드포인트
• 로컬 실행은 로컬 개발