프론트엔드 폴더 구조 설명 - 100-hours-a-week/9-team-Devths-WIKI GitHub Wiki

0️⃣ 프로젝트 최상단

1. public/

  • 빌드 과정 없이 그대로 제공되는 파일을 넣는 곳
  • 예: 아이콘, 이미지, 파비콘, 정적 파일
  • 코드에서 /images/logo.png처럼 바로 접근 가능

1️⃣ src/

1. src/app/

  • Next.js App Router: 라우팅 전용
  • URL ↔ 페이지 연결
  • 어떤 URL로 들어오면 어떤 화면을 보여줄지만 결정

(1) layout.tsx

  • 모든 페이지에 공통으로 적용되는 최상위 레이아웃
  • <html>, <body> 설정 + 전역 Provider 장착 위치
  • 보통 여기서 하는 일:
    • 전역 폰트 적용
    • <AppProviders /> 장착(React Query, Toast Host 등)

(2) globals.css

  • Tailwind base + 전역 스타일
  • reset, 기본 폰트, 공통 배경색 같은 앱 전체 스타일이 들어감

(3) (public)/ : 비로그인(공개) 라우트 그룹

  • (public)은 폴더 이름이 URL에 포함되지 않음(라우트 그룹)
  • 로그인 안 해도 접근 가능한 화면들

page.tsx ( / )

  • 랜딩 화면 라우트 엔트리
  • 보통 return <LandingPage />처럼 “연결만” 함

login/page.tsx ( /login )

  • 로그인 화면 라우트 엔트리
  • return <LoginPage />

signup/page.tsx ( /signup )

  • 회원가입 화면 라우트 엔트리
  • return <SignupPage />

auth/callback/page.tsx ( /auth/callback )

  • 구글 OAuth 인증 후 돌아오는 콜백 처리 화면
  • URL에 붙은 code 같은 값을 읽어서 로그인 처리 후 리다이렉트

(4) (app)/

  • 로그인한 유저만 들어올 수 있는 영역
  • (app)/layout.tsx가 핵심

(app)/layout.tsx

  • 보호 영역 공통 레이아웃
  • 여기서 하는 일:
    1. <AppShell>로 헤더/하단탭/컨테이너를 깔아줌
    2. <AuthGate>로 로그인 여부 확인 후 접근 허용/차단

calendar/page.tsx ( /calendar )

  • 캘린더 라우트 엔트리
  • return <CalendarPage />

board/page.tsx ( /board )

  • 게시판 라우트 엔트리
  • return <BoardPage />

chat/page.tsx ( /chat )

  • 채팅 라우트 엔트리
  • return <ChatPage />

llm/page.tsx ( /llm )

  • AI 기능 화면 라우트 엔트리
  • return <LlmPage />

notifications/page.tsx ( /notifications )

  • 알림 화면 라우트 엔트리
  • return <NotificationsPage />

profile/page.tsx ( /profile )

  • 프로필 화면 라우트 엔트리
  • return <ProfilePage />

(app)/not-found.tsx

  • 보호영역에서 404가 났을 때 보여주는 화면
  • 장점: AppShell(헤더/탭)은 유지한 채 “내용만 404”로 보여줄 수 있음

(app)/error.tsx

  • 보호영역에서 런타임 에러가 났을 때 보여주는 화면
  • 마찬가지로 AppShell 유지 가능

src/app/not-found.tsx (전체 404)

  • 전체 라우팅에서 못 찾는 경로에 대한 404
  • 공개 영역에서도 공통으로 404를 보여주고 싶을 때 사용

src/app/error.tsx (전체 에러)

  • 앱 전체에서 터지는 에러 처리
  • 보호영역/공개영역 전부 커버하고 싶을 때 사용

2. src/screens/

  • 페이지(화면) 단위 컴포넌트
  • 실제 UI/데이터 로딩/이벤트 처리를 대부분 여기서 함
  • src/app은 라우팅 연결, src/screens/는 화면 구현

LandingPage.tsx

  • 랜딩 UI 구현 (슬라이드, 시작하기 버튼 등)

LoginPage.tsx

  • 로그인 UI 구현 (구글 로그인 버튼 등)

SignupPage.tsx

  • 회원가입 UI 구현 (닉네임, 프로필 사진 등)

OAuthCallbackPage.tsx

  • OAuth 콜백 처리 UI/로직
  • code 파라미터 읽기 → 로그인 API 호출 → 성공 시 /calendar 이동

CalendarPage.tsx

  • 캘린더 화면 UI + 일정 CRUD + 필터 등

BoardPage.tsx

  • 게시판 목록/상세/작성 진입(추후 라우팅 확장 가능)

ChatPage.tsx

  • 채팅 목록/채팅방/메시지 전송 UI

LlmPage.tsx

  • AI 기능 화면(예: 프롬프트 입력/결과 출력/업로드 흐름)

NotificationsPage.tsx

  • 알림 리스트, 읽음 처리, 이동

ProfilePage.tsx

  • 내 정보 보기/수정, 로그아웃 등

3. src/components/ (재사용 UI 컴포넌트)

  • 여러 화면에서 재사용하는 UI를 모아두는 곳

components/layout/

  • AppShell 관련 뼈대
  • AppShell.tsx
    • 헤더 + 메인 컨텐츠 영역 + 바텀탭을 감싸는 레이아웃
    • 보통 여기서 core/hosts(전역 로딩/모달/토스트)도 한 번만 렌더하는 위치가 됨
  • Header.tsx
    • 상단 헤더 UI
  • BottomNav.tsx
    • 하단 탭 UI

components/ui/

  • Button/Input/Modal/Toast 같은 작은 공용 UI
  • shadcn/ui의 래핑 컴포넌트나 프로젝트 공통 스타일 적용 컴포넌트가 여기에 들어감

components/common/

  • 여러 페이지에서 쓰는 조립된 컴포넌트
  • 예:
    • LandingCarousel
    • FileUploader
    • AvatarUploader
  • ui보다 큼 (보통 내부에서 ui 컴포넌트를 조합함)

components/index.ts

  • components exports를 한 곳에서 정리
  • import 경로 깔끔하게 하려면 사용

4. src/core/ (전역 강제 정책)

  • 프로젝트 규칙을 강제로 적용하는 영역

core/providers/

  • AppProviders.tsx
    • 전역 Provider들을 한 번에 묶는 파일
    • 예:
      • QueryClientProvider
      • 전역 Toast/Modal Provider
      • 테마/폰트 Provider

core/guards/

  • AuthGate.tsx
    • 보호영역 접근 제어
    • 예 동작:
      • 로그인 상태 확인(예: GET /users/me)
      • 실패 시 /login 이동
      • 401 발생 시 refresh 로직으로 연결(인터셉터랑 연동)

core/hosts/

  • 전역 UI를 딱 1번만 렌더하는 곳
  • 어디서든 store/hook으로 “열어!” 하면 실제 UI는 여기서 뜸
  • GlobalLoadingHost.tsx
    • 전역 로딩(스피너/오버레이) 표시
  • GlobalInfoModalHost.tsx
    • “알림/정보” 모달 (확인 버튼 1개)
  • GlobalConfirmModalHost.tsx
    • “확인/취소” 모달 (2버튼)
  • GlobalToastHost.tsx
    • 토스트 알림

core/routing/

  • navigation.ts
    • 라우트 상수, 이동 helper
    • 예: ROUTES.calendar, goToLogin() 같은 것들

core/index.ts

  • core exports 모음

5. src/services/ (도메인 단위 서비스 로직)

  • 백엔드랑 통신하는 함수 + 비즈니스 로직

services/auth/ (authService.ts, tokenService.ts)

  • authService.ts
    • 로그인/회원가입/로그아웃 같은 인증 관련 API 호출
  • tokenService.ts
    • 토큰 저장/삭제/조회(로컬스토리지/쿠키 등)
    • refresh 토큰 처리 전략이 있으면 여기에 모임

services/users/userService.ts

  • 내 정보 조회, 프로필 수정 등 유저 API

services/calendars/calendarService.ts

  • 일정 조회/추가/수정/삭제 API

services/posts/postService.ts

  • 게시글 CRUD, 검색/필터 등

services/chats/

  • chatService.ts
    • 채팅방 목록, 메시지 내역 조회, 메시지 전송(HTTP)
  • websocketClient.ts
    • STOMP/WebSocket 연결/구독/해제 관리
    • 실시간 메시지 수신 처리

services/llm/llmService.ts

  • AI 요청/응답 API (텍스트/업로드 등)

services/notifications/notificationService.ts

  • 알림 목록, 읽음 처리, 알림 삭제 등

6. src/lib/

lib/api/

  • axios.ts
    • axios 인스턴스 생성
    • 인터셉터(401 처리, 토큰 자동 첨부, refresh 재시도 등)
    • 프로젝트 전체 HTTP 규칙의 중심
  • endpoints.ts
    • 엔드포인트 문자열을 상수로 모음
    • 예: ENDPOINTS.users.me

lib/query/

  • queryClient.ts
    • TanStack Query 전역 옵션 설정(재시도 정책, 캐시 시간 등)
  • keys.ts
    • queryKey 모음
    • 예: queryKeys.user.me(), queryKeys.calendar.list(filter)

lib/validators/

  • zod 스키마 모음(선택)
  • 예: 회원가입 폼 검증, 일정 생성 폼 검증

lib/utils/

  • 날짜 포맷, debounce, throttle 같은 공통 함수

7. src/hooks/ (커스텀 훅)

  • 화면에서 로직을 깔끔하게 빼고 싶을 때 사용
  • 예:
    • useAuth: 로그인 상태/로그아웃 액션
    • useModal: 전역 모달 열기/닫기
    • useToast: 토스트 띄우기
    • useInfiniteScroll: 무한스크롤 공통 로직

8. src/stores/ (Zustand 상태)

auth.store.ts

  • 로그인 상태, 유저 정보(필요 최소) 저장

  • 서버 상태는 Query로 관리하고,

    여기에는 앱 UI가 당장 필요한 최소 상태만 두는 게 안전함

ui.store.ts

  • 전역 로딩/모달/토스트 같은 UI 트리거 상태

index.ts

  • store exports 모음

9. src/constants/

routes.ts

  • 라우트 문자열 상수
  • 예: /calendar, /login

storageKeys.ts

  • 로컬스토리지 키 이름 상수
  • 예: ACCESS_TOKEN, REFRESH_TOKEN

ui.ts

  • UI 관련 상수
  • 예: 토스트 지속시간, 모달 기본 문구 등

10. src/types/ (공통 타입)

api.ts

  • 공통 API 응답 타입
  • 예: ApiResponse<T>, ApiError

domain.ts

  • 도메인 공통 타입
  • 예: User, CalendarEvent, Post, ChatMessage

index.ts

  • types exports 모음

11. src/styles/ (전역 스타일 보조)

tokens.css

  • 디자인 토큰(색상, 폰트 크기, spacing) 같은 걸 정리
  • Tailwind를 쓰더라도, 팀에서 통일해야 하는 값을 모아두면 편함

12. src/assets/ (번들에 포함할 에셋)

fonts/

  • 폰트 파일을 직접 번들에 포함하고 싶을 때 사용
  • 단, Next font 최적화를 쓸 거면 방식에 따라 사용 여부가 달라짐

2. 기타 설정/테스트 파일

tests/

  • 테스트 코드 모음(단위/통합/E2E 보조 등)

playwright.config.ts

  • E2E 테스트(브라우저 자동화) 설정

vitest.config.ts

  • 단위 테스트 설정(사용한다면)

tailwind.config.ts

  • Tailwind 설정(테마/플러그인/콘텐츠 스캔 경로)

next.config.js

  • Next 설정(이미지 도메인, 리다이렉트/리라이트 등)

package.json

  • 의존성/스크립트 정의

pnpm-lock.yaml

  • 패키지 버전 고정(팀원 환경 동일하게)
⚠️ **GitHub.com Fallback** ⚠️