sam-docs/frontend/v1/01-architecture.md

01. 프로젝트 아키텍처

대상: 프론트엔드/백엔드/기획자 버전: 1.0.0 최종 수정: 2026-03-09

---

1. 기술 스택

영역	기술	버전
프레임워크	Next.js (App Router)	15.x
런타임	React	19.x
언어	TypeScript	strict mode
UI 컴포넌트	shadcn/ui (Radix UI 기반)	-
스타일링	Tailwind CSS	4.x
폼 관리	react-hook-form + Zod	-
상태관리	React hooks (useState/useCallback/useMemo)	-
토스트/알림	sonner	-
국제화	next-intl	-
모바일	Capacitor (하이브리드 앱)	-
백엔드 API	PHP Laravel (별도 프로젝트)	12.x

---

2. 프로젝트 특성

• 폐쇄형 ERP 시스템: 인증 필수, SEO 불필요, 오히려 노출 방지
• 모든 페이지 Client Component: 'use client' 필수 (서버 컴포넌트 사용 금지)
• 이유: HttpOnly 쿠키 기반 인증 → 서버 컴포넌트에서 쿠키 수정(토큰 갱신) 불가

---

3. 디렉토리 구조

src/
├── app/                          # Next.js App Router
│   ├── [locale]/                 # 다국어 라우팅 (ko, en)
│   │   ├── (protected)/          # 인증 필수 영역
│   │   │   ├── layout.tsx        # AuthenticatedLayout (사이드바/헤더)
│   │   │   ├── accounting/       # 회계 도메인
│   │   │   ├── hr/               # 인사 도메인
│   │   │   ├── production/       # 생산 도메인
│   │   │   ├── orders/           # 영업/주문 도메인
│   │   │   ├── business/         # 경영/대시보드
│   │   │   └── dev/              # 개발 도구 (운영 비활성)
│   │   └── (auth)/               # 비인증 영역 (로그인 등)
│   └── api/
│       └── proxy/[...path]/      # API 프록시 (HttpOnly 쿠키 처리)
│
├── components/
│   ├── atoms/                    # 최소 단위 (ScrollableButtonGroup 등)
│   ├── molecules/                # 조합 단위 (FormField 등)
│   ├── organisms/                # 페이지 구성 블록 (PageHeader, DataTable 등)
│   ├── templates/                # 페이지 레이아웃 틀
│   │   ├── UniversalListPage/    # 리스트 페이지 템플릿 (59+ 페이지 사용)
│   │   └── IntegratedDetailTemplate/  # 상세/폼 페이지 템플릿
│   ├── ui/                       # shadcn/ui 기본 컴포넌트
│   └── {domain}/                 # 도메인별 비즈니스 컴포넌트
│       ├── accounting/           # 회계 (입금, 출금, 전표 등)
│       ├── hr/                   # 인사
│       ├── production/           # 생산
│       ├── orders/               # 영업
│       └── business/             # CEO 대시보드 등
│
├── hooks/                        # 커스텀 훅
├── lib/
│   ├── api/                      # API 통신 유틸리티 (핵심)
│   ├── utils/                    # 범용 유틸리티
│   └── dashboard-invalidation.ts # 대시보드 갱신 시스템
│
├── middleware.ts                 # 인증/보안/봇 차단 미들웨어
└── types/                        # 전역 타입 정의

---

4. 컴포넌트 계층 구조

atoms → molecules → organisms → templates → pages

계층	역할	예시
atoms	HTML 확장, 단일 기능	ScrollableButtonGroup, PhoneInput
molecules	atom 조합, 재사용 폼 필드	FormField (Label+Input 통합)
organisms	페이지 구성 블록	PageHeader, DataTable, SearchableSelectionModal
templates	페이지 뼈대 (config 기반)	UniversalListPage, IntegratedDetailTemplate
pages	app/ 라우트 + 도메인 컴포넌트	page.tsx → {Domain}Component

---

5. 데이터 흐름

[사용자 액션]
    ↓
[컴포넌트] → useCallback/useState
    ↓
[Server Action] ('use server')
    ↓
[executeServerAction / executePaginatedAction]
    ↓
[serverFetch → authenticatedFetch]
    ↓
[/api/proxy/...path] (Next.js API Route)
    ↓
[PHP Laravel Backend /api/v1/...]

• 컴포넌트에서 직접 fetch() 금지
• 모든 데이터 요청은 Server Action → API 프록시 → 백엔드 경로
• 인증 토큰은 HttpOnly 쿠키에 저장, 프록시에서 자동 주입

---

6. 관련 프로젝트

프로젝트	경로	역할
sam-react-prod	sam-next/sma-next-project/sam-react-prod	Next.js 프론트엔드 (현재)
sam-api	sam-api/sam-api	PHP Laravel 백엔드 API
sam-design	sam-design/sam-design	React 디자인 시스템 (레거시)
sam-docs	sam-docs	프로젝트 문서 (현재 문서)

---

7. 주요 설계 결정

결정	이유
Client Component Only	폐쇄형 ERP, 쿠키 수정 필요
API Proxy Pattern	HttpOnly 쿠키 보안 유지
Config-Driven Templates	59+ 리스트 페이지 일관성
Server Actions	타입 안전 + 쿠키 접근 가능
Tailwind + shadcn/ui	빠른 개발 + 일관된 디자인
Zod (신규 폼만)	기존 폼 안정성 유지하면서 점진 적용