Repository navigation
FE Architecture
wcorn edited this page Apr 5, 2026
·
6 revisions
React 프론트엔드 프로젝트 구조를 정의한다. 모든 FE 모듈은 이 아키텍처를 따른다.
| 영역 | 선택 | 버전 |
|---|---|---|
| 빌드 | Vite | 7.x |
| 프레임워크 | React | 19.x |
| 언어 | TypeScript | 5.x |
| 라우팅 | React Router | v7 |
| 서버 상태 | TanStack Query | v5 |
| 클라이언트 상태 | Zustand | v5 |
| API 클라이언트 | Axios | - |
| 스타일링 | Tailwind CSS + shadcn/ui | - |
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는 하위 폴더 없이 플랫하게 둬도 된다
-
features/{domain}/디렉토리 생성 (api, components, types 등 필요한 하위 폴더) -
pages/{Domain}Page.tsx페이지 컴포넌트 생성 -
app/router.tsx에 라우트 등록
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
// 도메인 목록
['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단계 이후: 파라미터 (필터 객체 또는 개별 값)
// 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 | 이유 |
|---|---|---|
| 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] });
},
});
}모든 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 아님)
UI 상태만 Zustand로 관리한다.
- 스토어를 도메인별로 분리하되 가볍게 유지한다
- 서버 데이터를 Zustand에 복제하지 않는다
- 인증 토큰은 메모리에 저장한다 (localStorage 사용 안 함)
shared/api/
├── client.ts # Axios 인스턴스 + 인터셉터
└── index.ts
- 요청 인터셉터: Access Token을 Authorization 헤더에 자동 첨부
- 응답 인터셉터: 401 → /api/auth/reissue 호출 → 성공 시 원래 요청 재시도, 실패 시 /login 이동
React Router v7으로 구성한다.
-
PrivateRoute: 미인증 →/login리다이렉트 -
PublicRoute: 인증됨 →/리다이렉트 - 라우트 추가 시
app/router.tsx에 등록
- 디자인 토큰(색상, 간격, 폰트)을 Tailwind 설정에 정의
- 기본 UI 컴포넌트(Button, Input, Dialog 등)는 shadcn/ui 사용
-
shared/components/ui/에 배치 - 도메인 특화 컴포넌트는
features/{domain}/components/에서 직접 구현
앱 전역에서 사용하는 알림음·효과음은 shared/audio/ 공통 모듈을 통해 재생한다. 모듈별로 개별 오디오 로직을 구현하지 않는다.
- 상세: Shared-Audio
- 파일 형식: mp3
- 저장 위치:
fe/public/sounds/(정적 에셋) - 재생 훅:
shared/audio/useSound - 레지스트리:
shared/audio/sounds.ts
사용처: Tools(타이머 알림), Planner(예정: 일정/복습 알림) 등
브라우저 에러·로그·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)
| 결정 | 대안 | 선택 이유 |
|---|---|---|
| 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 | 안정성, 레퍼런스 풍부, 라우팅 복잡도 낮음 |