아키텍처

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

Monorepo 아키텍처

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

빌드 파이프라인

build → test → lint → typecheck

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

패키지 구성

상태 관리 전략

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

1. Server State

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

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

2. Client State

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

• Sidebar: 열기/닫기, 축소/확장 상태
• Theme: Light/Dark 모드 전환
• Command Palette: 열기/닫기, 검색 상태

3. URL State

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

• 필터/정렬/페이지네이션: URL 공유만으로 동일한 뷰 재현

Design System

CSS Token 시스템

4-Layer 토큰 구조로 일관된 디자인 시스템을 유지합니다:

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

접근성(a11y)이 보장된 Radix Primitives를 기반으로 디자인 시스템을 패키지화하여 일관성을 유지합니다.

API Integration

타입 생성 파이프라인

서버의 OpenAPI 명세에서 TypeScript 타입을 자동 생성하여, 엔드투엔드 타입 안전성을 보장합니다. 각 도메인별 전용 hooks를 통해 타입 안전한 API 호출이 가능합니다.

라우팅

• File-based Routing: 파일 구조가 곧 URL 구조
• 코드 스플리팅: 페이지별 지연 로딩으로 초기 번들 최소화
• Auth Guard + Role-based Routes: 인증 및 역할 기반 접근 제어

Enterprise UX 패턴

패턴	설명
Command Palette (Cmd+K)	어디서나 빠른 페이지 이동, 검색, 액션 실행
Keyboard Shortcuts	주요 액션에 키보드 단축키 지원
Global Context Variables	전역 시간 범위, 환경 전환
Per-widget Skeleton + ErrorBoundary	위젯별 독립적 로딩/에러 처리