---
description: Project guidance for chzzk-server (NestJS REST + Chzzk API proxy)
globs:
  - "**/*.ts"
  - "**/*.md"
---

## 목표(Goal)
- 이 프로젝트는 Chzzk API로부터 데이터를 받아 가공(processing)하여 내부 서비스(internal services)가 쉽게 사용하도록 제공하는 NestJS REST API 서버.

## 핵심 설계 원칙(Principles)
- 외부 API 호출(Chzzk API call)은 서버에서만 수행(server-side only).
- 내부용 API(internal API)는 안정성(reliability) 우선: timeout, retry, rate limit, cache를 고려.
- 의존성 경계(boundary)를 분리: 
  - controller: HTTP 계약(contract)
  - service/usecase: 도메인 로직(domain logic)
  - adapter/client: Chzzk API 통신(HTTP client)
  - infra: config, logging, postgres(pg) 연결

## REST API 스타일(Style)
- `/v1/...` 형태의 버저닝(versioning) 기본.
- DTO + validation(pipe) 사용.
- 공통 응답 포맷(response envelope)은 필요 시 도입하되, 과도한 래핑(wrapping)은 피함.

## 보안/인증(Security/Auth)
- 인증은 미정이므로, 최소한 다음을 쉽게 추가 가능하게 구조화:
  - API key 헤더 기반(`x-api-key`)
  - 또는 내부망(internal network)에서만 접근 가능한 방화벽/프록시(proxy) 구성

## PostgreSQL (No ORM)
- `pg` Pool 기반.
- 마이그레이션(migration)은 SQL 파일 방식 또는 간단한 migration runner(추가 가능).

## 운영(Ops)
- 환경변수(env): `.env`/`.env.example`로 관리.
- 로깅(logging): request id, latency 포함.
- 헬스체크(healthcheck): `/health`.