SOKUREE 플랫폼 모듈화 아키텍처 가이드 (Modular Architecture Guide)

본 문서는 SOKUREE 플랫폼의 "느슨한 결합(Loose Coupling)"과 "높은 응집도(High Cohesion)" 원칙을 실현하기 위한 모듈화 아키텍처 설계 및 개발 가이드를 제공합니다.

1. 아키텍처 설계 원칙

1.1 Minimal Platform Scope (최소 플랫폼 범위)

플랫폼(Core/Platform)은 전체 시스템의 뼈대만 관리하며, 각 비즈니스 모듈의 내부 구현에는 관여하지 않습니다.

플랫폼 역할: 전체 레이아웃(헤더, 사이드바), 인증 및 세션 관리, 동적 모듈 로딩, 공통 디자인 토큰 제공.
모듈 역할: 비즈니스 로직, 독립적인 UI 구성, 자체 라우팅 정보 정의.

1.2 Inversion of Control (제어의 역전)

플랫폼이 모듈을 직접 import 하여 배치하는 대신, 모듈이 자신의 정보를 플랫폼에 주입(Injection)하는 방식으로 동작합니다. 이를 통해 새로운 모듈 추가 시 플랫폼 코드 수정을 최소화합니다.

2. 폴더 구조 (Project Structure)

src/
├── core/               # 플랫폼의 뇌 (핵심 비즈니스 규칙 및 인터페이스)
│   └── types.ts        # IModuleDefinition 등 공통 타입 정의
├── platform/           # 플랫폼의 뼈대 (UI 레이아웃 및 인프라)
│   ├── App.tsx         # 메인 앱 엔트리 및 레이아웃 구성
│   ├── ModuleLoader.tsx # 모듈 라우트를 동적으로 결합하는 컴포넌트
│   └── styles/
│       └── global.css  # CSS Variables (Design Tokens) 선언
├── modules/            # 비즈니스 모듈 (독립적인 영역)
│   ├── asset/          # 자산 관리 모듈
│   ├── cctv/           # CCTV 모듈
│   └── ...
└── shared/             # 공통 유틸리티 및 컴포넌트 (선택 사항)

3. 핵심 인터페이스 (Core Interfaces)

3.1 IModuleDefinition

모듈이 플랫폼에 등록되기 위해 반드시 준수해야 하는 규격입니다.

export interface IModuleDefinition {
  moduleName: string;      // 모듈 식별자 (Global Unique)
  basePath: string;        // 모듈의 기본 URL 경로 (예: '/asset')
  routes: IModuleRoute[];  // 모듈 내부의 세부 라우팅 정보
  requiredRoles?: string[]; // (Optional) 접근을 위한 권한 정보
}

3.2 IModuleRoute

모듈 내 개별 페이지 및 메뉴 구성을 위한 정보입니다.

export interface IModuleRoute {
  path: string;            // basePath 이후의 상대 경로
  element: ReactNode;      // 렌더링할 컴포넌트
  label?: string;          // 메뉴에 표시될 이름
  icon?: ReactNode;        // 메뉴 아이콘
}

4. 디자인 시스템 (Design Tokens)

플랫폼은 모듈의 스타일 라이브러리 선택권(Tailwind, CSS-in-JS 등)을 존중하면서도 통일성을 유지하기 위해 CSS Variables를 사용합니다.

위치: src/platform/styles/global.css

사용 방법:

/* 모듈 내부 CSS */
.my-component {
  background-color: var(--sokuree-brand-primary);
  padding: var(--sokuree-spacing-md);
  border-radius: var(--sokuree-radius-md);
}

5. 새 모듈 추가 방법 (Quick Start)

모듈 정의 생성: src/modules/[moduleName]/index.ts (또는 유사한 위치)에서 IModuleDefinition 객체를 내보냅니다.
라우트 정의: 모듈 내부에서 사용할 페이지들을 routes 배열에 추가합니다.
플랫폼 등록: src/platform/App.tsx의 sampleModules (또는 실제 서버에서 받아온 모듈 리스트)에 위 객체를 추가합니다.
확인: 사이드바 메뉴에 자동으로 노출되며 해당 경로 접근 시 정상 렌더링되는지 확인합니다.

6. 향후 고려 사항

Dynamic Import: 모듈이 많아질 경우 React.lazy를 통한 코드 분할(Code Splitting) 적용.
Error Boundary: 특정 모듈의 런타임 에러가 플랫폼 전체로 전파되지 않도록 ModuleLoader 내부에 에러 처리 로직 강화.
Shared Context: 플랫폼이 제공하는 사용자 정보 등을 모듈이 쉽게 꺼내 쓸 수 있는 Hook 제공.

4.2 KiB Raw Blame History