85 lines
5.5 KiB
Markdown
85 lines
5.5 KiB
Markdown
# AS 프로젝트 기술 스택 분석 (Tech Stack)
|
|
|
|
본 문서는 `as` (Administrative Support / 전자결재 및 공공행정 지원 시스템) 애플리케이션의 핵심 프로그래밍 스택과 아키텍처 구조를 분석하여 정리한 문서입니다. 본 프로젝트는 Next.js 15와 FSD(Feature Sliced Design) 아키텍처를 도입하여 복잡한 비즈니스 로직을 격리하고 모노레포 환경에서 유연하게 패키지를 재사용하고 있습니다.
|
|
|
|
---
|
|
|
|
## 1. Core Framework & Runtime
|
|
|
|
* **Next.js 15.5.18**:
|
|
* **App Router** 구조를 기본으로 채택하여 파일 기반 라우팅, 서버 컴포넌트(RSC), 미들웨어 등을 적극적으로 활용합니다.
|
|
* `src/pages`와 `app/` 라우터를 조합하여 Next.js의 진입점(Layout, Page)은 최소화하고 비즈니스 모듈은 FSD 아키텍처 계층으로 격리하는 하이브리드 구성을 취하고 있습니다.
|
|
* **React 19 & TypeScript**:
|
|
* 최신 React의 강력한 타입 지원 기능을 활용하여 컴포넌트와 비즈니스 데이터의 정적 타입을 보장합니다.
|
|
* **pnpm Monorepo**:
|
|
* `workspace:*` 의존성 참조 형식을 사용하여 동일 레포지토리 내의 공통 모듈(`@common/auth`, `@common/components`, `@common/network`, `@common/assets`)을 패키지 형태로 안전하게 참조합니다.
|
|
|
|
---
|
|
|
|
## 2. Styling (CSS & Design System)
|
|
|
|
* **Tailwind CSS (v3.4)**:
|
|
* 유틸리티 퍼스트 CSS 프레임워크를 기반으로 하며, `postcss` 및 `autoprefixer`를 활용하여 스타일을 구성합니다.
|
|
* **Class Variance Authority (CVA)**:
|
|
* 컴포넌트의 Variants(버튼 크기, 활성/비활성 색상, 디자인 테마 등)를 선언적이고 타입 안전하게 관리하기 위해 사용됩니다.
|
|
* **Lucide React**:
|
|
* 통합적이고 일관된 아이콘 팩으로 화면 요소를 설계할 때 기본 아이콘 라이브러리로 활용됩니다.
|
|
|
|
---
|
|
|
|
## 3. State Management (상태 관리)
|
|
|
|
애플리케이션 내의 상태는 성격에 따라 3가지 레이어로 명확히 구분되어 관리됩니다.
|
|
|
|
### ① 전역 서버 상태 (Global Server State)
|
|
* **TanStack Query v5 (React Query)**:
|
|
* 서버 데이터 fetch, cache, sync, update 등을 담당합니다.
|
|
* 커스텀 훅 패턴을 활용하여 비즈니스 데이터 처리부와 UI 컴포넌트를 분리합니다.
|
|
* `ReactQueryDevtools`를 탑재하여 개발 단계에서 쿼리 캐시 상태를 실시간 모니터링합니다.
|
|
|
|
### ② 전역 클라이언트 상태 (Global Client State)
|
|
* **Zustand (Vanilla)**:
|
|
* `zustand/vanilla`의 `createStore`를 활용하여 글로벌 상태(사용자 정보, 알림창, 사이드바 메뉴 등)를 관리합니다.
|
|
* **Next.js SSR 친화적 상태 공유 패턴**:
|
|
Next.js의 서버 사이드 렌더링(SSR) 시 싱글톤 상태 오염 문제를 해결하기 위해, React Context (`StoreProvider`, `StoreContext`)와 `useRef`를 조합하여 요청 단위별 독립된 스토어 인스턴스를 생성하고 훅(`useUserStore` 등)을 통해 구독합니다.
|
|
|
|
### ③ 폼 상태 관리 및 검증 (Form State)
|
|
* **React Hook Form & Zod**:
|
|
* 결재 및 행정 신청 폼이 다수 존재하는 시스템 특성상, 입력 폼의 상태 변화를 비제어 컴포넌트 기반으로 최적화하여 렌더링 성능을 개선합니다.
|
|
* `zod` 스키마 빌더를 이용해 폼 유효성 검증 규칙을 직관적으로 선언하고 `@hookform/resolvers`로 바인딩합니다.
|
|
|
|
---
|
|
|
|
## 4. Components & Libraries
|
|
|
|
* **Radix UI**:
|
|
* `@radix-ui/react-tooltip` 등 마크업 구조와 접근성이 보장된 Headless UI 라이브러리를 차용하여 스타일 종속성 없이 접근성 높은 컴포넌트를 구성합니다.
|
|
* **TanStack Table v8 (React Table)**:
|
|
* 다양한 필터링, 정렬, 페이지네이션 요구사항이 존재하는 목록 화면을 처리하기 위해 사용되는 Headless Table 라이브러리입니다.
|
|
* **dnd-kit (`@dnd-kit/core`, `@dnd-kit/sortable`)**:
|
|
* 결재선 지정 화면 등에서 마우스 및 터치 인터랙션을 이용한 행 정렬(Drag & Drop)을 매끄럽게 처리하기 위해 도입되었습니다.
|
|
|
|
---
|
|
|
|
## 5. Network & Utils
|
|
|
|
* **Axios**:
|
|
* HTTP 클라이언트 라이브러리로, 인터셉터(Interceptor)를 통해 공통 인증 헤더 관리, 토큰 재발급, 에러 공통 처리를 수행합니다.
|
|
* **Tus JS Client**:
|
|
* 대용량 및 첨부 파일 업로드 시 네트워크 단절 상황에 대응할 수 있도록 Resumable(이어올리기) 프로토콜인 **Tus Protocol**을 사용하여 안정적인 업로드를 지원합니다.
|
|
* **Day.js**:
|
|
* 표준화된 시간 포맷팅 및 날짜 연산을 가볍고 빠르게 처리합니다.
|
|
* **JS Cookie**:
|
|
* 클라이언트 브라우저의 쿠키 설정 및 조회에 활용됩니다.
|
|
|
|
---
|
|
|
|
## 6. Monitoring & Linting (품질 관리)
|
|
|
|
* **OpenTelemetry**:
|
|
* 클라이언트 및 서버 측의 네트워크 지연 시간, 주요 사용자 인터랙션 트레이싱을 위해 APM 수집 어댑터가 구현되어 있습니다 (`instrumentation-client.ts`, `instrumentation.ts`).
|
|
* **Sentry (`@sentry/nextjs`)**:
|
|
* 프로덕션 환경에서의 실시간 에러 추적 및 분석을 담당합니다.
|
|
* **Steiger**:
|
|
* FSD 아키텍처 패턴을 물리적인 파일 경로 분석을 통해 규제하는 정적 분석 도구입니다. 레이어 간 비정상적인 의존성(예: 하위 레이어가 상위 레이어를 참조하는 역참조 등)을 빌드타임/린트 타임에 강력하게 통제합니다.
|