studyclub-engineering

StudyClub 코드 모노레포 (public). 미국·캐나다·한국의 개발자 스터디 클럽 서비스.

• 사용자 사이트: https://studyclub.life
• 운영 콘솔: https://back-office.studyclub.life
• API: https://api.studyclub.life

⚠️ PUBLIC 레포 — .env·토큰·키·개인정보 등 민감정보 커밋 금지. 자세한 규칙은 CLAUDE.md.

🚀 처음이면 ONBOARDING.md 부터 — 클론 → .env → 실행 방식 고르기(전부 Docker / 프론트만 로컬 / 백엔드도 로컬 / 운영 API) → 구글 로그인까지 한 장에 있다.

구조

frontend/                # Node 워크스페이스 (pnpm + turbo)
  apps/
    core-front/          # 사용자향 (Next.js 16, ko/en) — 랜딩·스터디·행사·가이드·공지·소개
    back-office-front/   # 운영자향 (Next.js 16) — 스터디/행사/멤버/캡틴 관리 콘솔
    playground/          # 디자인 컴포넌트 & 프로토타입 샌드박스
  packages/
    design/              # 디자인 토큰 & 정본 CSS (@studyclub/design — base.css, core.css, console.css)
    ui/                  # 공용 UI 컴포넌트 (@studyclub/ui — Storybook 포함)
    mock/                # mock 데이터 + MSW API 계층 (@studyclub/mock)
    types/               # 공용 도메인·국제화 타입 (@studyclub/types)
    utils/               # 공용 함수·상수 (@studyclub/utils)
backend/                 # Spring Boot 4 멀티모듈 (Gradle Kotlin DSL, Java 25)
  api/                   # 실행 모듈 — REST API (:8080)
  domain/                # 도메인 모델
  common/                # 공통 (ApiResponse 등)

core-front·back-office-front는 실제 백엔드 API를 사용하며, 개발 환경에서는 앱별 조건에 따라 MSW를 활성화합니다. playground는 mock 기반 프로토타입입니다. 공용 타입·함수는 mock과 분리된 @studyclub/types·@studyclub/utils에서 직접 참조합니다. 앱별 기능 구조와 패키지 의존성은 프론트 프로젝트 구조를 참고하세요.

실행

로컬 전체 셋업(구글 로그인 · docker compose 포함)은 ONBOARDING.md. 아래는 앱 단위 명령 요약이다.

Frontend

# 프로젝트 루트에서 바로 실행할 때
pnpm --prefix frontend storybook       # Storybook (:6006)
pnpm --prefix frontend run dev         # 모든 앱 동시 실행

# 또는 frontend 디렉토리에서 실행할 때
cd frontend
pnpm install
pnpm run dev                       # turbo — 모든 앱 동시
# 개별 실행 (단축키)
pnpm run dev:core-front            # http://localhost:4700
pnpm run dev:back-office-front     # http://localhost:4701
pnpm run dev:playground            # http://localhost:4702
pnpm run storybook                 # http://localhost:6006 (Storybook)
# 빌드
pnpm run build
pnpm run build-storybook           # Storybook 정적 빌드

• Node 20+ 필요.
• 데이터 수정: 스터디는 frontend/packages/mock/src/data/studies/ (recruiting.ts, ongoing.ts, closed-*.ts), 크루는 src/data/crew.ts, 커뮤니티·행사·공지는 src/data/community.ts.

Backend

cd backend
./gradlew :api:bootRun                   # http://localhost:8080
# 빌드 (실행 jar)
./gradlew :api:bootJar                   # → api/build/libs/app.jar

• JDK 25 필요. Gradle 은 wrapper(9.7.1 고정)가 받아오므로 따로 설치하지 않습니다.

주요 엔드포인트:

메서드	경로	설명
GET	/	StudyClub API
GET	/api/health	{ "status": "UP" }
GET	/api/studies	스터디 목록 (현재 더미)

Docker:

docker build -f backend/Dockerfile -t studyclub-api backend
docker run -p 8080:8080 studyclub-api

배포 (CI/CD)

main push → 프로덕션, develop push → 스테이지. GitHub Actions 가 도커 이미지 빌드·푸시 후 K8s 롤아웃.

워크플로	대상	이미지
core-front-{main,develop}	core-front	hyperrealitycorp/studyclub-core-front-{production,stage}
back-office-front-{main,develop}	back-office-front	…-back-office-front-{production,stage}
backend-{main,develop}	api	…-studyclub-api-{production,stage}

• 프론트 워크플로 docker context = frontend/, 백엔드 = backend/.
• 시크릿(도커·SSH·슬랙)은 레포 GitHub Actions Secret 으로 주입 (코드에 평문 금지).

도메인

도메인	서비스
studyclub.life	core-front (prod)
stage.studyclub.life	core-front (stage)
back-office.studyclub.life	back-office-front (prod)
back-office-stage.studyclub.life	back-office-front (stage)
api.studyclub.life	api (prod)

기여

• PR 은 CODEOWNERS(@titaniper) 승인 후에만 main 에 머지됩니다 (외부 기여자 포함).
• 외부 라이브러리 추가는 합의 필수.