# 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 (신규 폼만) | 기존 폼 안정성 유지하면서 점진 적용 |