0. 개요

backend-template은 도메인에 종속되지 않는 NestJS 백엔드 스타터다. 새 제품/도메인을 시작할 때 인증·설정·테스트·관측성·CI·컨벤션·AI 협업 환경(하네스)이 미리 깔린 상태에서 src/modules/ 아래에 도메인만 얹으면 된다. auth + identity(User/Team/Role)가 RBAC+ABAC 레퍼런스 구현으로 들어 있어, 새 도메인은 이걸 본떠 만든다.

기술 스택

항목	기술	비고
Runtime	Node.js 24	`package.json` engines
Language	TypeScript (strict)
Framework	NestJS 11	SWC 빌드
ORM	MikroORM v7	Unit of Work, legacy 데코레이터(`@mikro-orm/decorators/legacy`)
DB / Cache	PostgreSQL / Redis	Redis는 graceful degradation(`safe*` 메서드)
Config	zod typed config	부팅 시 env 검증
Package Manager	pnpm 10	corepack
Test	Jest 30 (`@swc/jest`)	unit / integration / e2e 3계층

핵심 설계 결정 (왜 이렇게)

도메인 비종속 + 레퍼런스 1개 — 엔진/골격을 제공하고 identity(auth+User/Team/Role)를 정석 예시로 둔다. 새 도메인은 이걸 복제·변형한다. 조기 플러밍은 피한다(미뤄둔 것은 docs/tech-debt).
타입 안전 설정 — 환경변수는 zod 스키마로 부팅 시 검증. 빈 문자열은 "누락"으로 취급.
default-deny 접근제어 — 팀 스코프 RBAC + 리소스 소유권 ABAC, 3-tier(AWS IAM Role 유사).
3경로 쿼리 전략 — 쓰기/단건은 MikroORM, 복잡 조회는 Kysely, 도메인 간 읽기는 ReadService.
기계 강제 컨벤션 — 레이어 경계·마이그레이션 드리프트·lint를 사람이 아니라 CI/훅이 막는다.
AI 협업 하네스 — "누가 작업해도 같은 품질"이 나오도록 시스템 프롬프트·스킬·서브에이전트·훅을 구조화.

1. 빠른 시작 (Getting Started)

clone 직후 순서다.

의존성 설치 — pnpm install (corepack로 pnpm 10 사용).
환경변수 준비 — .env는 git에 없다(시크릿 포함, gitignore). 팀에 .env 값을 요청한다. 단, .env.test는 committed(로컬호스트 전용·시크릿 없음)라 clone 직후 테스트가 바로 돈다.
로컬 인프라 기동 — pnpm docker:up (PostgreSQL + Redis 컨테이너). 끌 때는 pnpm docker:down.
DB 스키마 — 로컬(dev)은 엔티티 기준 auto-sync. 마이그레이션 워크플로는 §4 참조.
개발 서버 — pnpm start:dev (watch + type-check + SWC, 기동 전 Swagger metadata 자동 생성).