PlatformUpdated 2026-04-01
Frontend(next-dashboard)
CtrlPlus 플랫폼의 Next.js 156 App Router 기반 대시보드 프론트엔드 아키텍처 문서
Next.jsSpring BootDockerPostgreSQLMariaDB
개요
1. 프로젝트 개요
| 항목 | 내용 |
|---|---|
| 프레임워크 | Next.js 16.x (App Router) |
| 언어 | TypeScript |
| 패키지 매니저 | pnpm |
| 스타일링 | Tailwind CSS v4 |
| 상태 관리 | Zustand |
| 서버 상태 | TanStack Query (React Query) |
| 인증 | JWT (HttpOnly Cookie) |
| 차트 | Recharts |
| 다이어그램 | XYFlow (React Flow), Mermaid |
| 배포 | PM2 + Nginx (Café24 VPS) |
2. 디렉토리 구조
Bash
3. 라우팅 패턴
3-1. App Router 기본 규칙
TypeScript
3-2. workstate 쿼리 파라미터
Workbench 페이지는 workstate 쿼리로 렌더링할 블록 타입을 제어한다.
| workstate 값 | 렌더링 블록 |
|---|---|
diagram | Mermaid 다이어그램 블록 |
layout | XYFlow 레이아웃 블록 |
config | 설정/파라미터 패널 |
control | 센서·액추에이터 제어 패널 |
| (없음) | 기본 WorkTask 요약 뷰 |
TypeScript
3-3. SideNav 슬러그 변형 매핑
TypeScript
4. 인증 (JWT Cookie)
4-1. 흐름 요약
Browser → Next.js Route Handler (프록시) → Spring Boot API
↓
HttpOnly Cookie (access_token)
↓
Bearer 헤더로 변환 후 포워딩
4-2. Route Handler 프록시
TypeScript
4-3. Zustand authStore
TypeScript
5. API 통신
5-1. fetch 래퍼
TypeScript
5-2. React Query 훅 예시
TypeScript
6. Workbench 모듈
6-1. WorkTask 엔티티 타입
TypeScript
6-2. WorkboardShell (뷰 전환)
TypeScript
6-3. DiagramBlock (Mermaid 렌더러)
TypeScript
7. 레이아웃 시스템
7-1. DashboardLayout
TypeScript
7-2. createPortal 기반 WorkbenchCanvas
WorkbenchCanvas는 createPortal을 사용해 레이아웃 밖의 풀스크린 오버레이로 렌더링한다.
TypeScript
8. 스타일링 규칙
8-1. 색상 팔레트 (CSS Variables)
css
8-2. 라이트 테마 원칙
- 배경:
white/neutral-50기본 - 사이드바:
white+border-r border-neutral-200 - 카드:
bg-white rounded-xl border border-neutral-200 shadow-sm - 다크 배경 사용 금지
9. 환경 변수
Bash
10. 주요 패턴 요약
| 패턴 | 적용 위치 | 설명 |
|---|---|---|
| Route Group | (auth), (dashboard) | 레이아웃 분리 |
| Proxy Route Handler | app/api/[...proxy] | 쿠키 → Bearer 변환 |
| Zustand | authStore, workbenchStore | 클라이언트 전역 상태 |
| React Query | 모든 서버 데이터 훅 | 캐싱·무효화 |
| createPortal | WorkbenchCanvas | 풀스크린 오버레이 |
| workstate param | Workbench 슬러그 페이지 | 블록 타입 라우팅 |
| await params/searchParams | 모든 Page 컴포넌트 | Next.js 15 필수 |