# 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)

```text
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
모듈이 플랫폼에 등록되기 위해 반드시 준수해야 하는 규격입니다.

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

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

```typescript
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
  /* 모듈 내부 CSS */
  .my-component {
    background-color: var(--sokuree-brand-primary);
    padding: var(--sokuree-spacing-md);
    border-radius: var(--sokuree-radius-md);
  }
  ```

---

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

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

---

## 6. 향후 고려 사항

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