MCP 서버 @neki-team/sprint-mcp : Claude Code · Claude Desktop · Cursor 등에서 티켓·위키를 조작. 개인 API 토큰(Bearer)으로 /api/mcp/v1 을 호출하며, 설치 방법은 mcp/README.md 참고
GitHub App : 태스크에서 브랜치 생성, webhook 으로 PR 상태 역동기화
OG 링크 미리보기(Slack 등에서 티켓·위키 링크 카드)
인증
Google Workspace SSO. ALLOWED_EMAIL_DOMAIN 도메인 제한에 더해, 가입 승인 게이트(PENDING → APPROVED)를 통과해야 앱에 진입할 수 있음
승인 전 계정은 웹 화면뿐 아니라 개인 토큰(MCP API)까지 함께 잠김
기술 스택
영역
선택
프레임워크
Next.js 16 (App Router, Server Components + Server Actions)
언어
TypeScript
UI
shadcn/ui (Base UI 기반) + Tailwind CSS v4
에디터
Tiptap 3
DB / ORM
PostgreSQL + Prisma 6
인증
Auth.js (NextAuth v5) — Google OIDC
스토리지
S3 (위키 이미지 · 첨부 파일)
테스트
Vitest
배포
Docker (standalone) + k3s + ArgoCD(GitOps)
아키텍처
flowchart LR
U["팀원 브라우저"] -->|HTTPS| ING["k3s Ingress (Traefik)"]
M["MCP 클라이언트<br/>(Claude Code 등)"] -->|"Bearer 토큰<br/>/api/mcp/v1"| ING
ING --> SVC["Service :80"]
SVC --> POD["Next.js Pod :3000<br/>Server Components + Server Actions"]
POD -->|Prisma| DB[("PostgreSQL")]
POD -->|OIDC| G["Google Workspace SSO"]
POD -->|위키 이미지·첨부| S3[("S3")]
POD -->|"브랜치 생성 (App API)"| GH["GitHub"]
GH -.->|"PR webhook"| POD
INIT["initContainer<br/>prisma migrate deploy"] -.->|기동 선행| POD
인증 흐름:
sequenceDiagram
participant B as 브라우저
participant A as Next.js (Auth.js)
participant G as Google
participant D as PostgreSQL
B->>A: /login → "Google로 계속하기"
A->>G: OIDC 인가 요청 (hd=도메인)
G-->>A: 콜백 (id_token)
A->>A: 이메일 도메인 검증 (ALLOWED_EMAIL_DOMAIN)
A->>D: 세션 저장 (Prisma Adapter)
A->>A: 가입 승인 상태 확인 (PENDING / APPROVED)
A-->>B: APPROVED → /dashboard, PENDING → 승인 대기 안내
# 1) 의존성 설치 (postinstall 에서 prisma generate 자동 실행)
npm install
# 2) 환경변수
cp .env.example .env
# DATABASE_URL 을 로컬 Postgres 로 지정
# AUTH_SECRET 생성: npx auth secret (또는 openssl rand -base64 32)
# GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET 입력 (아래 OAuth 설정 참고)
# 위키 이미지 업로드·GitHub 연동을 쓰려면 S3_* / GITHUB_APP_* 도 채운다
# 3) DB 스키마 적용
npm run db:migrate # 개발용 (마이그레이션 생성/적용)
# 또는 기존 DB 에 반영만: npm run db:deploy
# 4) (선택) 데모 데이터
npm run db:seed
# 5) 실행
npm run dev # http://localhost:3000
스키마를 바꾼 뒤에는 next dev 가 옛 Prisma client 를 물고 있으므로 dev 서버를 재시작해야 합니다. 이 함정을 포함한 주의사항은 docs/gotchas.md 에 정리돼 있습니다.
발급된 Client ID / Secret 을 .env(로컬) 또는 k8s Secret(운영)에 입력
ALLOWED_EMAIL_DOMAIN 에 회사 도메인(예: musinsa.com)을 넣으면 해당 워크스페이스 계정만 로그인할 수 있습니다. 도메인을 통과해도 승인 전까지는 PENDING 상태로 /pending 화면에서 대기합니다.
승인 전환 UI 는 아직 없습니다. 운영자가 DB 에서 직접 UPDATE "User" SET "status" = 'APPROVED' 로 처리하며, database 세션 전략이라 재로그인 없이 다음 요청부터 반영됩니다.
배포 (k3s + GitOps)
k8s 매니페스트는 이 레포가 아니라 GitOps 레포 Team-Neki-GitOps 에 있습니다. 앱 레포는 이미지를 빌드해 태그만 bump 하고, 실제 적용은 ArgoCD 가 담당합니다.
flowchart LR
A["main 머지"] --> B["GitHub Actions<br/>'Deploy to Prod' 수동 실행<br/>(workflow_dispatch)"]
B --> C["이미지 빌드<br/>(schema + migrations 포함)"]
C --> D["GitOps 레포<br/>이미지 태그 bump"]
D --> E["ArgoCD 자동 배포"]
E --> F["initContainer:<br/>prisma migrate deploy"]
F --> G["앱 컨테이너 기동<br/>node server.js"]
배포 트리거 : main 머지만으로는 배포되지 않습니다. Actions 탭에서 "Deploy to Prod" 를 수동 실행해야 합니다
마이그레이션 : 롤아웃마다 initContainer 가 prisma migrate deploy 를 실행합니다. Prisma 가 advisory lock 을 잡으므로 다중 파드 동시 배포에도 안전하며, 로컬에서 손으로 적용할 필요가 없습니다. 대신 스키마를 바꾸면 마이그레이션 SQL 을 반드시 커밋에 포함해야 합니다
베이스라인 : 최초 배포 시 prisma/migrations/20260707170339_sprint_project_team 이 테이블을 생성하고, 이후 마이그레이션이 차례로 적용됩니다
빌드 인자 : NEXT_PUBLIC_APP_URL 은 next build 시점에 번들로 인라인되므로 ConfigMap 이 아니라 Dockerfile build arg 로 주입합니다
헬스체크 : liveness 는 /api/health(DB 미의존), readiness 는 /api/ready 를 사용합니다. /api/ready 는 첫 호출에 주요 페이지와 DB(SELECT 1)를 한 번씩 미리 호출하는 웜업을 시작하고, 끝날 때까지 503 을 돌려줍니다. 그래서 새 파드는 데워진 뒤에 트래픽을 받습니다(배포 직후 첫 요청 2~3초 → 0.1초). 웜업이 끝난 뒤에는 DB 를 건드리지 않습니다
CI(.github/workflows/ci.yml)는 모든 push · PR 에서 lint → typecheck → test → build 를 실행합니다.
프로젝트 구조
prisma/
schema.prisma # 데이터 모델(정본)
migrations/ # 20260707170339_sprint_project_team 이 베이스라인
seed.ts # 데모 데이터
src/
auth.ts # Auth.js (Google SSO + 승인 게이트)
app/
(app)/ # 인증 필요 영역 (사이드바 셸)
dashboard | sprints | projects | epics | tasks | board | timeline
wiki | announcements | labels | notifications | teams | users
login/ # 로그인
pending/ # 가입 승인 대기 (앱 셸 밖)
api/ # auth | health | mcp/v1 | github | wiki
components/ # ui(shadcn) + 기능별 컴포넌트
lib/ # 순수 로직 (validators, order, mentions, s3, github ...)
server/
queries.ts # 읽기(서버)
actions/ # 쓰기(Server Actions)
tests/ # Vitest. src/ 구조를 미러링
mcp/ # MCP 서버 패키지 (@neki-team/sprint-mcp)
docs/ # 설계 · 이력 · 가이드 문서
Dockerfile # 멀티스테이지 standalone + Prisma CLI(마이그레이션용)