콘텐츠로 이동
ZERO-ONE Wiki

시스템 아키텍처

전체 구조

ZERO-ONE은 스터디 매칭·진행을 핵심으로 하는 웹 서비스입니다. 프론트엔드(Next.js)와 백엔드(Spring Boot)가 분리된 구조이며, 2026년 5월 두 저장소(study-platform-client, study-platform-mvp)를 **monorepo study-platform-mono**로 통합했습니다. 내부 구조는 보존하되 루트에 공통 문서·규칙·CI 레이어를 얹는 방식입니다.

study-platform-mono/
├── study-platform-client/   # 프론트 (Next.js · Yarn · Playwright)
├── study-platform-mvp/      # 백엔드 (Spring Boot 3.4 · Java 21 · Gradle)
├── docs/                    # product-ssot(도메인 요구사항) · backend/frontend/ops 문서
├── llm-wiki/                # LLM 가독용 지식 맵
└── .github/                 # CI/CD 워크플로우 · composite actions

문서는 원본 → product-ssot → llm-wiki → 스키마/테스트 → 코드 → 릴리스 기록 순으로 흐릅니다.

기술 스택

백엔드

  • Spring Boot 3.4 · Java 21 (Amazon Corretto) — AWS 장기 지원(LTS) 배포판이라 채택.
  • MariaDB(운영 시 이중화), Redis(MVP 1차에는 백엔드 서버에 함께 구성), Kafka + Batch(초기에는 단일 서버, 트래픽 증가 시 분리).
  • Gradle 빌드, Docker 컨테이너로 배포.

프론트엔드

  • Next.js 15 + React 19 — SEO·오픈그래프·서버 컴포넌트 활용 목적.
  • Tailwind CSS + shadcn/ui — CSS-in-JS 대신 headless UI로 작업 효율 확보.
  • 상태 관리: 클라이언트 = Zustand, 서버 = TanStack Query(캐시·선언적 에러 처리).
  • ESLint: @rushstack/eslint-config. Storybook으로 컴포넌트 단위 개발/디자인 소통.
  • App Router 사용. 라우트 그룹: (landing) 랜딩, (service) 대부분의 서비스 페이지, (admin) 관리자.

백엔드 도메인 / 패키지 구조

domain / global 두 축으로 나뉩니다. controller 대신 endpoint라는 용어를 사용합니다.

domain/
├── member/        # 회원 (member, profile)
├── study/         # 서비스 중심 — studymatching(주간 매칭), dailystudy(매일 스터디)
├── comment/       # 스터디·프로필·매칭에 달리는 댓글
├── notification/  # 여러 종류 알림
└── ... (course/payment 등 product-ssot 도메인)
global/
├── auth/          # 인증
├── util/
└── api/format/    # 공통 응답(BaseResponse/ErrorResponse)

각 도메인 패키지 내부는 endpoint / service(+dto) / entity / constant / repository(+dto)로 구성합니다.

product-ssot 기준 도메인은 auth, class, course, notification, payment 등으로 정리되어 있습니다.

매칭 도메인

서비스의 핵심. 주요 엔티티:

엔티티역할
MatchingRequest사용자의 현재 매칭 요청 상태(AUTO→DONE)
MatchingRequestPartner완료된 매칭의 결과(로그) — 재매칭 시에도 히스토리 유지
Blacklist특정 사용자 간 매칭 차단
MatchingTemplate 외”시간 우선”·“기술 우선” 등 가중치 기반 동적 매칭 규칙 시스템

현재는 모든 사용자에 동일 규칙을 적용하는 단일 로직이며, MatchingTemplate 기반 동적 가중치 시스템으로 개인화하는 방향이 설계되어 있습니다.

프론트엔드 구조 (전환 중)

초기에는 **FSD(Feature-Sliced Design)**로 설계(feature/shared/widget/entities). 현재는 type-based 구조로 마이그레이션 중이며, src/components/ui/(shadcn) 컴포넌트를 src/components/ui로 합치는 작업이 진행됩니다. SSR은 아직 적극 사용하지 않습니다.

공통 API 응답 형식

Envelope 패턴으로 응답을 일관화합니다.

  • BaseResponse: statusCode(필수), timestamp(필수), content, message. 컨트롤러는 BaseResponse.of(...)로 반환.
  • ErrorResponse: statusCode, timestamp, errorCode(서비스 고유 코드, 예 MEM001), errorName, message, detail. 에러 코드는 도메인별 enum(ErrorCodeSpec 구현)으로 관리해 머지 충돌·비대화를 방지합니다.

원문: