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 아키텍처 패턴을 물리적인 파일 경로 분석을 통해 규제하는 정적 분석 도구입니다. 레이어 간 비정상적인 의존성(예: 하위 레이어가 상위 레이어를 참조하는 역참조 등)을 빌드타임/린트 타임에 강력하게 통제합니다.

5.5 KiB Raw Blame History