Docs Index

📖 이 docs 는 VitePress 사이트로도 빌드된다 — prose 마크다운(아래 폴더들)은 사이드바·검색과 함께 렌더되고, design/ 카탈로그는 /design 에 verbatim 호스팅. 배포는 operations/docs-site-deploy.md. 로컬: cd docs && npm install && npm run docs:dev.

design/ 은 docs 중 유일하게 빌드되는 정적 사이트(자체 package.json + Vite)다. 나머지 폴더는 생 마크다운.

분류 기준:

폴더	무엇	빈도
dev/	어떻게 빌드하나, 어떤 스타일로 짜나, git 룰	매일
platform/	특정 OS / 프레임워크의 함정, 디버깅 매뉴얼	막혔을 때
operations/	외부 시스템 다룰 때 쓰는 정보	배포 / 마이그레이션 / 등록 시
policies/	왜 이렇게 결정했나	정책 변경 / onboarding 시
api/	endpoint 별 명세 + 실 curl 예제	새 endpoint 만들 때 / AI 가 endpoint 작업 시
spec/	화면 / flow / 도메인 룰 (기획자 관점)	새 feature 설계 시
design/	토큰 SSOT + 컴포넌트/화면 카탈로그 (빌드되는 사이트)	UI 작업 시

dev/ — 개발

• environment.md — 백엔드/모바일/프론트 실행, DB 접속, 빌드 리체크
• style-guide.md — Phosphor Icons, UI 위계, 키보드 UX 패턴
• migration-rules.md — DB 마이그레이션 / 데이터 처리 판단 룰

platform/ — 플랫폼 gotchas

• flutter-gotchas.md — BackdropFilter 한계 + glass UI, 한글 글리프, dev 튜닝 패널
• tailwind-v4-gotchas.md — @theme 커스텀 네임스페이스 (spacing/text/radius) utility 자동 생성 한계 + 디버깅
• nextjs-cf-gotchas.md — Next.js + CF Workers: build-time prerender 가 runtime secret 못 보는 함정 + force-dynamic 패턴
• native-debugging.md — iOS / Android 실기기 디버깅 프로토콜 + 환경 셋업
• dart-api-quirks.md — TLS 1.2 / cipher / corp_cls 등
• compat-matrix.md — Framework × OS × 기기 호환성 매트릭스

operations/ — 운영

• infrastructure.md — Railway 환경변수, 미들웨어, Admin API, GraphQL
• prod-db.md — Railway PostgreSQL 마이그레이션 이력 + 테이블 규모
• app-store.md — Apple / Google 앱 등록 + IAP 상품
• cloudflare-deploy.md — frontend CF Workers + Static Assets 배포 (OpenNext for Cloudflare)
• docs-site-deploy.md — 이 docs 사이트(VitePress + design verbatim) CF Pages 배포 + CF Access

policies/ — 정책 / 의사결정 이력

• monetization.md — 수익 모델 + quota / 광고 정책 + 진화 이력
• lazy-reveal.md — AI 분석 reveal 모델 (자동 → 명시적)
• quota-ad-v3.md — 광고/quota 정책 V3 토론 이력
• pr-review.md — Codex 등 자동 리뷰 처리 룰
• lazy-auth-launch.md — 출시 전 lazy auth + 웹 부활 5명 패널 결정 + 5-PR 계획
• web-as-design-source.md — 웹 = 디자인 source of truth, Flutter 로 역포팅. 모바일 전용 뷰포트 + 토큰 매핑 표
• api-routing-conventions.md — endpoint path / Registry helper / secret 비교 / RL 우선순위 룰 (PR #79 합의)

api/ — API 명세 (점진 작성)

• README.md — endpoint markdown 템플릿 + curl 예제 룰

spec/ — 화면 / flow / 도메인 + 아키텍처

• README.md — screen- / flow- / domain- prefix 가이드
• architecture.md — 시스템 전체 다이어그램 + 백엔드 / Flutter 레이어
• backend-structure.md — Go 백엔드 폴더 / 패키지 책임
• flutter-structure.md — Flutter 폴더 / 레이어 / Riverpod 구조
• db-schema.md — DB 스키마 (tbls 자동 생성, db-schema/ 디렉토리)
• domain-app-check.md — Firebase App Check: 왜 필요한지 + 동작 원리 + soft→strict 전환
• domain-analytics.md — Firebase Analytics 이벤트 taxonomy + RevealOutcome / AuthGateAction enum

---

다른 위치 (docs/ 외)

• ~/.config/cloud-tokens/README.md — 인프라 토큰 (Railway / Vercel) 사용법
• CONTRIBUTING.md — 브랜치 / 커밋 / PR 규칙
• CLAUDE.md (project root) — 프로젝트 절대 룰 + 디렉토리 + 자주 쓰는 명령
• ~/.claude/CLAUDE.md — 글로벌 작업 룰 (자동 실행, 메모리 저장 룰)