마스터스러너스 (mastersrunners)

한국 러너들을 위한 훈련 기록, 커뮤니티, 크루 운영 도구를 만드는 모노레포입니다.

현재 상태

이 저장소는 초기 준비 단계 설명을 넘어 실제 제품 기능과 하네스 구조를 함께 담는 모노레포입니다. 현재 코드베이스에는 다음 기능 축이 구현되어 있습니다.

• 워크아웃 기록과 업로드
• 피드, 게시물, 댓글, 좋아요
• 프로필, 팔로우, 차단
• 크루, 크루 게시판, 활동, 출석, QR 체크인
• 챌린지, 이벤트
• 메시지/대화, 알림
• 파일 업로드와 스토리지 연동

하네스 상태는 상시 점수표 대신 harness-diagnostics를 필요할 때 호출해 점검합니다. 운영 방식은 docs/runbooks/harness-diagnostics.md를 기준으로 봅니다.

기술 스택

• Web: Vite + React 19 + React Router v7
• API: NestJS 11
• Database: Prisma + PostgreSQL
• Shared packages: packages/database, packages/types
• Storage: Cloudflare R2 중심, 로컬 디스크 fallback 지원
• Test tooling: Jest, Playwright

저장소 구조

apps/
  web/        # Vite SPA
  api/        # NestJS API
packages/
  database/   # Prisma schema and database package
  types/      # Shared TypeScript types
design/       # Technical design, architecture, ADR, initiatives
docs/         # Domain docs, runbooks, guides, reports, history
tasks/        # Status-scoped execution queue
scripts/      # Executable helper scripts

빠른 시작

1. 의존성 설치

pnpm install

2. 개발 서버 실행

pnpm dev

3. 빌드

pnpm build

4. 테스트

pnpm --filter @masters/api test
pnpm --filter @masters/api test:e2e

5. 배포 검증

pnpm deploy:verify -- http://localhost:4000

하네스 진입점

이 저장소는 에이전트 친화적인 하네스로 정리 중입니다. 문서를 읽을 때는 아래 순서를 권장합니다.

1. AGENTS.md
2. tasks/active/ 또는 tasks/README.md
3. design/
4. docs/domain/
5. docs/runbooks/environment-and-settings.md
6. docs/runbooks/harness-diagnostics.md

역할은 다음처럼 나뉩니다.

• design/: 프론트엔드, 백엔드, 아키텍처, ADR, initiative
• docs/: 도메인 규칙, 운영 가이드, 기여 가이드, 보고서, 역사성 자료
• tasks/: todo, active, archive로 나뉜 실제 실행 상태
• .github/workflows/, scripts/: 실행 가능한 자동화

주요 문서

• AGENTS.md: 표준 에이전트 진입점
• design/README.md: 설계 문서 경계
• docs/README.md: 문서 구조 설명
• docs/domain/README.md: 도메인 문서 인덱스
• docs/runbooks/environment-and-settings.md: 환경 변수와 런타임 설정의 첫 진입점
• docs/runbooks/harness-diagnostics.md: 하네스 진단을 언제 어떻게 호출할지
• docs/runbooks/deployment.md: 배포 runbook
• docs/reports/history/README.md: 레거시 계획과 과거 설계 입력 보관 위치
• design/operating-rules/exceptions.md: repo 밖에서만 닫을 수 있는 예외 레지스트리
• design/initiatives/I-0004-truth-model-cleanup.md: truth-model cleanup
• design/initiatives/I-0005-current-state-design-corpus.md: current-state design corpus
• design/initiatives/I-0006-guardrail-hardening.md: guardrail hardening
• design/initiatives/I-0007-readability-hardening.md: readability hardening

주의사항

• 프론트엔드는 현재 SPA이며, 저장소에 남아 있는 .next 산출물은 source of truth가 아닙니다.
• 워크아웃 canonical unit은 meters, seconds, seconds per kilometer입니다.
• 공개 health endpoint는 GET /health입니다.

환경과 설정

• 환경 변수와 런타임 설정은 docs/runbooks/environment-and-settings.md에서 먼저 찾습니다.
• production-like 예제 값은 .env.production.example에 있습니다.
• 배포/런타임 계약은 docs/runbooks/deployment.md의 Environment Contract를 기준으로 봅니다.

문의

• 이메일: [email protected]