아키텍처

ONESHIM Backoffice v2의 아키텍처는 확장성, 타입 안전성, 개발자 경험을 핵심 원칙으로 설계되었습니다.

Monorepo 아키텍처

Turborepo + pnpm workspace를 사용하여 패키지 간 의존성을 명확히 관리합니다.

turbo.json 파이프라인

build → test → lint → typecheck

각 태스크는 의존성 그래프에 따라 병렬 실행되며, Turborepo의 캐싱을 통해 변경된 패키지만 재빌드됩니다.

패키지 의존성 그래프

상태 관리 전략

상태를 3가지 영역으로 분할하여 각 영역에 최적화된 도구를 사용합니다.

1. Server State: TanStack Query

API 데이터와 WebSocket 실시간 데이터를 관리합니다.

• 자동 캐싱: staleTime, gcTime 기반 캐시 무효화
• 낙관적 업데이트: 사용자 경험 향상을 위한 즉시 반영
• WebSocket 실시간: 모니터링 메트릭, 알림 등 실시간 데이터 스트리밍
• 14개 도메인별 hooks: 각 도메인에 특화된 Query/Mutation hooks 제공

2. Client State: Zustand

UI 전용 상태를 관리합니다.

• Sidebar: 열기/닫기, 축소/확장 상태
• Theme: Light/Dark 모드 전환
• Command Palette: 열기/닫기, 검색 상태
• Minimal boilerplate: Redux 대비 코드량 대폭 감소

3. URL State: nuqs

URL 쿼리 파라미터로 관리되는 상태입니다.

• 필터: DataTable 필터 조건
• 정렬: 컬럼별 정렬 방향
• 페이지네이션: 현재 페이지, 페이지 크기
• 공유 가능: URL 복사만으로 동일한 뷰 재현

Design System (packages/ui)

4-Layer CSS Token 시스템

Primitive Tokens  → 색상, 간격, 타이포그래피 원시 값
    ↓
Semantic Tokens   → 의미 기반 매핑 (primary, danger, success)
    ↓
Component Tokens  → 컴포넌트별 토큰 (button-bg, card-border)
    ↓
Dark Mode Tokens  → 다크 모드 오버라이드

shadcn/ui + Radix Primitives

접근성(a11y)이 보장된 Radix Primitives를 기반으로, shadcn/ui 스타일링을 적용합니다. 복사-붙여넣기 방식이 아닌 패키지화하여 일관된 디자인 시스템을 유지합니다.

17개 P0 컴포넌트

카테고리	컴포넌트	수량
Primitives	Button, Input, Select, Checkbox, Switch, Textarea, Label, Badge	8
Data Display	DataTable, Card, Stat Card, KPI Widget	4
Feedback	Toast, Alert, Skeleton	3
Navigation	Sidebar, Command Palette	2

API Integration (packages/api-client)

타입 생성 파이프라인

14개 도메인별 TanStack Query hooks

각 도메인(Dashboard, Monitoring, Knowledge, AI, Ontology, Digital Twin 등)마다 전용 hooks를 제공하여 타입 안전한 API 호출을 보장합니다.

WebSocket 실시간 hooks

모니터링 메트릭, 알림, 시스템 상태 등 실시간 데이터를 WebSocket을 통해 스트리밍합니다. TanStack Query의 queryClient와 연동하여 캐시를 자동 업데이트합니다.

라우팅 (TanStack Router v1)

File-based Routing

파일 시스템 기반 라우팅으로 라우트 설정을 자동화합니다. 파일 구조가 곧 URL 구조입니다.

lazyRouteComponent 코드 스플리팅

각 페이지를 lazyRouteComponent로 래핑하여 초기 번들 크기를 최소화합니다. 사용자가 해당 페이지에 접근할 때만 코드를 로드합니다.

Auth Guard + Role-based Routes

• Auth Guard: 인증되지 않은 사용자는 로그인 페이지로 리다이렉트
• Role-based Routes: 사용자 역할에 따라 접근 가능한 페이지를 제한

Enterprise UX 패턴

Command Palette (Cmd+K)

어디서나 Cmd+K로 Command Palette를 열어 페이지 이동, 검색, 액션 실행이 가능합니다. Linear 스타일의 빠른 탐색을 제공합니다.

Keyboard Shortcuts

주요 액션에 키보드 단축키를 지원하여 파워 유저의 생산성을 극대화합니다.

Global Context Variables

• Time Range: 전역 시간 범위 설정 (모니터링, 대시보드 등에 일괄 적용)
• Environment: 개발/스테이징/프로덕션 환경 전환

Per-widget Skeleton + ErrorBoundary

각 위젯별로 독립적인 로딩 상태(Skeleton)와 에러 처리(ErrorBoundary)를 적용합니다. 하나의 위젯에서 에러가 발생하더라도 다른 위젯은 정상 작동합니다.