Skip to content

FE Architecture

wcorn edited this page Apr 5, 2026 · 6 revisions

FE 코드 아키텍처

React 프론트엔드 프로젝트 구조를 정의한다. 모든 FE 모듈은 이 아키텍처를 따른다.

1. 기술 스택

영역 선택 버전
빌드 Vite 7.x
프레임워크 React 19.x
언어 TypeScript 5.x
라우팅 React Router v7
서버 상태 TanStack Query v5
클라이언트 상태 Zustand v5
API 클라이언트 Axios -
스타일링 Tailwind CSS + shadcn/ui -

2. 폴더 구조

Feature-based (도메인별) 구조를 사용한다. BE 패키지 구조와 대칭을 이룬다.

fe/src/
├── app/                        # 앱 엔트리, 프로바이더, 라우터
│   ├── App.tsx
│   ├── router.tsx
│   └── providers.tsx
│
├── features/                   # 도메인별 모듈
│   └── {domain}/
│       ├── api/                # API 호출 함수 (TanStack Query 훅)
│       ├── components/         # 도메인 컴포넌트
│       ├── hooks/              # 도메인 훅
│       ├── store/              # Zustand 스토어 (필요 시)
│       └── types/              # 도메인 타입
│
├── shared/                     # 공통 모듈
│   ├── api/                    # Axios 인스턴스, 인터셉터
│   ├── components/             # 공통 UI (shadcn/ui 기반)
│   ├── hooks/                  # 공통 훅
│   ├── lib/                    # 유틸리티
│   └── types/                  # 공통 타입
│
├── pages/                      # 페이지 컴포넌트 (라우트 단위)
│   └── {Domain}Page.tsx
│
└── main.tsx

폴더 규칙

  • features/{domain}/ 안에서 도메인 관련 코드를 모두 관리한다
  • features/ 간 직접 import 금지. 공유가 필요하면 shared/로 올린다
  • pages/는 라우트 진입점만 담당하고, 실제 UI는 features/ 컴포넌트를 조합한다
  • 파일이 1~2개뿐인 feature는 하위 폴더 없이 플랫하게 둬도 된다

새 도메인 추가 시

  1. features/{domain}/ 디렉토리 생성 (api, components, types 등 필요한 하위 폴더)
  2. pages/{Domain}Page.tsx 페이지 컴포넌트 생성
  3. app/router.tsx에 라우트 등록

3. 상태 관리 전략

서버 상태: TanStack Query

API로 가져오는 모든 데이터는 TanStack Query로 관리한다.

파일 구조

features/{domain}/api/
├── use{Domain}s.ts          # 목록 조회 (useQuery)
├── use{Domain}.ts           # 상세 조회 (useQuery)
├── useCreate{Domain}.ts     # 생성 (useMutation)
├── useUpdate{Domain}.ts     # 수정 (useMutation)
├── useDelete{Domain}.ts     # 삭제 (useMutation)

예시: features/categories/api/useCategories.ts, useCreateCategory.ts, useUpdateCategory.ts, useDeleteCategory.ts

Query Key 컨벤션

// 도메인 목록
['categories']
['goals']
['fixed-schedules']
['routines']
['todos']
['materials']

// 상세 조회 (ID 파라미터)
['goals', goalId]
['routines', routineId]
['materials', materialId]

// 필터/날짜 파라미터
['todos', { status, priority, categoryId }]
['calendar', 'daily', date]
['calendar', 'weekly', date]
['calendar', 'monthly', year, month]

// 하위 리소스
['goals', goalId, 'milestones']
['materials', materialId, 'daily-overrides']

// 설정
['preferences']
['priority-rules']

규칙:

  • 1단계: 도메인명 (kebab-case)
  • 2단계: ID 또는 서브 리소스명
  • 3단계 이후: 파라미터 (필터 객체 또는 개별 값)

Mutation 후 Invalidation 전략

// useCreateCategory.ts 예시
export function useCreateCategory() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateCategoryRequest) =>
      client.post('/api/categories', data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['categories'] });
    },
  });
}

// useUpdateGoal.ts — 목록 + 상세 둘 다 무효화
export function useUpdateGoal(goalId: number) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: UpdateGoalRequest) =>
      client.put(`/api/goals/${goalId}`, data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['goals'] });
    },
  });
}

// useDeleteRoutine.ts — 삭제 시 관련 쿼리 모두 무효화
export function useDeleteRoutine() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (routineId: number) =>
      client.delete(`/api/routines/${routineId}`),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['routines'] });
    },
  });
}

invalidation 규칙:

  • 생성/삭제: 목록 쿼리 키만 무효화 (['goals'])
  • 수정: 같은 도메인 전체 무효화 (['goals'] → 목록 + ['goals', id] 상세 모두)
  • 블록 완료: ['calendar', 'daily', date] 무효화

Optimistic Update 정책

작업 Optimistic Update 이유
CRUD (생성/수정/삭제) X 서버 응답 대기. 데이터 정합성 우선
블록 완료 체크 O 즉각적인 피드백 필요. 실패 시 롤백
루틴 체크 O 즉각적인 피드백 필요

블록 완료 Optimistic Update 예시:

export function useCompleteBlock(date: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (blockId: number) =>
      client.patch(`/api/calendar/blocks/${blockId}/complete`),
    onMutate: async (blockId) => {
      await queryClient.cancelQueries({ queryKey: ['calendar', 'daily', date] });
      const previous = queryClient.getQueryData(['calendar', 'daily', date]);

      queryClient.setQueryData(['calendar', 'daily', date], (old: any) => ({
        ...old,
        completedBlocks: old.completedBlocks + 1,
        blocks: old.blocks.map((b: any) =>
          b.id === blockId ? { ...b, status: 'COMPLETED' } : b
        ),
      }));

      return { previous };
    },
    onError: (_err, _blockId, context) => {
      queryClient.setQueryData(['calendar', 'daily', date], context?.previous);
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['calendar', 'daily', date] });
    },
  });
}

Error Handling 패턴

모든 mutation의 에러는 onError 콜백에서 toast로 처리한다.

import { toast } from 'sonner';

export function useCreateGoal() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: CreateGoalRequest) =>
      client.post('/api/goals', data),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ['goals'] });
      toast.success('목표가 생성되었습니다.');
    },
    onError: (error: AxiosError<ApiErrorResponse>) => {
      const message = error.response?.data?.message ?? '요청에 실패했습니다.';
      toast.error(message);
    },
  });
}

규칙:

  • 성공: toast.success (생성/수정/삭제 시)
  • 실패: toast.error (서버 에러 메시지 표시, 없으면 기본 메시지)
  • useQuery 에러: 컴포넌트에서 error 상태로 처리 (toast 아님)

클라이언트 상태: Zustand

UI 상태만 Zustand로 관리한다.

  • 스토어를 도메인별로 분리하되 가볍게 유지한다
  • 서버 데이터를 Zustand에 복제하지 않는다
  • 인증 토큰은 메모리에 저장한다 (localStorage 사용 안 함)

4. API 클라이언트

Axios 인스턴스

shared/api/
├── client.ts           # Axios 인스턴스 + 인터셉터
└── index.ts
  • 요청 인터셉터: Access Token을 Authorization 헤더에 자동 첨부
  • 응답 인터셉터: 401 → /api/auth/reissue 호출 → 성공 시 원래 요청 재시도, 실패 시 /login 이동

5. 라우팅

React Router v7으로 구성한다.

  • PrivateRoute: 미인증 → /login 리다이렉트
  • PublicRoute: 인증됨 → / 리다이렉트
  • 라우트 추가 시 app/router.tsx에 등록

6. 스타일링

Tailwind CSS

  • 디자인 토큰(색상, 간격, 폰트)을 Tailwind 설정에 정의

shadcn/ui

  • 기본 UI 컴포넌트(Button, Input, Dialog 등)는 shadcn/ui 사용
  • shared/components/ui/에 배치
  • 도메인 특화 컴포넌트는 features/{domain}/components/에서 직접 구현

7. 공통 인프라

오디오/사운드

앱 전역에서 사용하는 알림음·효과음은 shared/audio/ 공통 모듈을 통해 재생한다. 모듈별로 개별 오디오 로직을 구현하지 않는다.

  • 상세: Shared-Audio
  • 파일 형식: mp3
  • 저장 위치: fe/public/sounds/ (정적 에셋)
  • 재생 훅: shared/audio/useSound
  • 레지스트리: shared/audio/sounds.ts

사용처: Tools(타이머 알림), Planner(예정: 일정/복습 알림) 등

FE 관측성 (Faro)

브라우저 에러·로그·Web Vitals·트레이스를 Grafana Faro Web SDK로 수집하여 Loki/Tempo에 전송한다.

  • 상세: 관측성 (Observability) §7
  • 패키지: @grafana/faro-react + @grafana/faro-web-tracing
  • 초기화: main.tsx의 initializeFaro()
  • 자동 수집: ErrorBoundary, console, Web Vitals, 라우트 변경, fetch/XHR 트레이스
  • BE 연결: fetch 요청에 traceparent 주입 → BE Tempo span과 단일 트레이스 병합
  • 전송 대상: Alloy faro.receiver (telemetry.orino.dev)

8. 선택 근거

결정 대안 선택 이유
Feature-based 구조 Layer-based, FSD BE 구조와 대칭, 도메인 응집도, FSD는 1인 개발에 과함
TanStack Query + Zustand Redux Toolkit, Jotai 서버/클라이언트 분리 명확, 보일러플레이트 최소
Tailwind + shadcn/ui CSS Modules, styled-components 혼자 개발 시 UI 생산성 극대화, 기본 컴포넌트 재구현 불필요
Axios ky, fetch 인증 인터셉터 설계와 직결, 생태계 성숙
React Router v7 TanStack Router 안정성, 레퍼런스 풍부, 라우팅 복잡도 낮음

Clone this wiki locally