# OrgChart Architecture

상태: 개발 전 설계. 확정 범위·환경·우선순위는 [README](README.md)를 따른다. 최신 추가 요청에 따라 Framework-independent Core를 기준으로 한다.

## 1. 독립 Core와 패키지 제안

확정: Core는 React·Vue runtime에 의존하지 않는다. 표준 DOM API와 JavaScript/TypeScript를 사용하고 dabeng/OrgChart 엔진을 Core에서 관리한다. 데이터 계약·Validation·Data Source Adapter·집계는 공통이다. Routing·로그인·Navigation·상위 Layout은 소유하지 않는다.

`packages/org-chart` / `@hm-design/org-chart`는 제안이다. npm workspaces `packages/*`와 양립할 수 있음을 확인했지만 생성·명칭 승인은 하지 않았다.

우선 검토안은 Core `@hm-design/org-chart`와 React Wrapper `@hm-design/org-chart-react` 두 패키지다. 경로 후보는 `packages/org-chart`와 `packages/org-chart-react`다. workspace·build 연결과 Core 소비에 React가 따라오지 않는 dependency·bundle 경계를 입증하고 최종 분리를 결정한다. 같은 패키지의 `/react` subpath는 우선안이 불가능할 때의 비교 항목만 남긴다. Vue·Angular·기타 framework는 이번 범위에서 제외한다. 실제 분리·경로·Export는 승인 전이다.

향후 책임별 구조 예시이며 이번에는 파일을 만들지 않는다.

```text
packages/org-chart/                 제안: framework-independent Core
  src/
    index.ts                       공개 Core facade와 type
    data/                          계약·Validation·집계(DOM도 비의존)
    sources/                       JSON Mock / 외부 JSON 공급
    view-model/                    ID index·파생 트리·표시 모델
    engine/                        dabeng adapter·DOM·생명주기
    renderers/                     표준 DOM 노드·콘텐츠·안전한 텍스트
    styles/                        컨테이너 scope·Theme mapping·Overlay
  브라우저 entry·빌드 설정          승인 후 결정
packages/org-chart-react/           우선 검토안: React 연결만 담당
src/org-chart/                      콘텐츠 단독 Story·가상 fixture 제안 위치
```

Core는 `@hm-design/ui` React API·`@hm-design/center-graphic`을 import하지 않는다. HM Theme CSS는 호스트의 별도 제공 또는 승인된 standalone 배포 경로로 연결한다. Theme 때문에 React peer를 가진 UI 전체 패키지 설치를 Vanilla의 필수 조건으로 만들지 않는다. 엔진 dependency의 버전·포함 범위는 TBD다. React Wrapper만 React/React DOM peer를 검토한다.

루트 [build-package.mjs](../../scripts/build-package.mjs)는 현재 `ui`, `center-graphic`만 허용한다. workspace 자동 탐색만으로 신규 빌드가 완성되지 않는다. 미래 별도 build 또는 최소 기존 빌드 연결 승인이 필요하다. 배포·의존성 격리는 [Framework Integration](framework-integration.md)에서 검증한다.

## 2. 데이터 흐름과 계층 책임

```text
JSON Mock / 외부 JSON / 미래 REST API
               ↓ Data Source Adapter: 원본 필드 매핑
동일 normalized 계약 후보(unknown)
               ↓ Data Validation: 구조·참조·정책 검증
검증 성공한 Normalized Data Contract(OrgChartData)
               ↓ ViewModel / Engine Adapter
조직별 표시 모델·집계·engine용 파생 트리·추가 relation 모델
               ↓ Framework-independent Core
DOM 콘텐츠·engine 계층 영역·Relation Overlay 후보
               ↑ 동일 Core 생명주기 호출
Vanilla 호스트 / React Wrapper (동일 Core 재사용)
```

Source 매핑은 Validation 이전에 공통 계약 후보를 만든다. 검증 후 신뢰된 계약과 구별한다. TypeScript cast만으로 신뢰하지 않고 모든 Source가 같은 runtime validator를 거친다.

- Data Source: 데이터를 읽고 매핑한다. 네트워크·취소·향후 캐시를 담당하며 engine DOM이나 framework를 알지 못한다.
- Validation: Schema Version·필수 값·ID·참조·순환·상태·관계·입력 안전성을 검사한다. 성공 데이터 또는 위치별 issue를 반환한다.
- Normalized Contract: 조직·직원·관계사·관계·표현·Metadata를 분리한다. engine용 `children`·`relationship`·`className`은 저장하지 않는다.
- ViewModel / 집계: index·하위 조직·정렬·leader·직원 그룹·집계를 순수 변환한다. 모든 환경이 같은 함수를 사용한다.
- Engine Adapter: 복사한 파생 트리만 전달하며 DOM mount/update/dispose를 관리한다. 원본 수정·fetch·공통 UI 변경은 금지한다.
- Core facade / DOM Renderer: 요청 경쟁, Validation, 상태, 콘텐츠 DOM, 인스턴스 ID, 생명주기·Overlay를 관리한다. 텍스트는 `textContent` 등 안전한 경로로 처리한다.
- React Wrapper(Framework Adapter): React mount/effect/ref/cleanup과 Props를 Core에 연결한다. Validation·집계·engine·노드 디자인·인터랙션 재구현은 금지한다. 다른 framework Adapter는 이번에 설계 구체화/구현하지 않고 동일 facade의 향후 확장성만 보존한다.
- 상위 앱: 컨테이너·Theme bootstrap·Routing·로그인/권한·API client를 소유한다. React 호스트는 적합한 HM 공개 Component 조합을 사용할 수 있다.

## 3. 공개 생명주기 초안

현재 Export가 아닌 제안이다. 데이터 type은 [Data Contract](data-contract.md)와 연결한다. `HTMLElement`는 DOM 경계에만 사용한다.

```ts
interface OrgChartDataSource {
  load(context: { signal: AbortSignal }): Promise<unknown>;
}
type ValidationIssue = { code: string; path: string; message: string };
type OrgChartIssue = ValidationIssue | {
  code: "SOURCE_LOAD" | "SOURCE_PARSE" | "SOURCE_MAP";
  path: "dataSource";
  message: string;
};
type OrgChartState =
  | { status: "loading" }
  | { status: "empty" }
  | { status: "ready"; dataVersion: string; aggregation: AggregationResult }
  | { status: "error"; issues: readonly OrgChartIssue[] };
interface OrgChartOptions {
  dataSource: OrgChartDataSource;
  aggregationPolicy?: ApprovedAggregationPolicy;
  interaction?: { pan: boolean; zoom: boolean }; // 공개 옵션 후보, 기본값 TBD
  onStateChange?: (state: OrgChartState) => void;
}
interface OrgChartHandle {
  mount(container: HTMLElement): Promise<void>;
  update(input: unknown): Promise<void>;
  reload(source?: OrgChartDataSource): Promise<void>;
  destroy(): void;
}
declare function createOrgChart(options: OrgChartOptions): OrgChartHandle;
```

`update`는 normalized 스냅샷 후보를 검증·반영하고 `reload`는 현재 또는 새 Source를 읽는다. 두 동작은 동일 Validation·집계·render 경로를 사용한다. 데이터 실패는 state callback으로 전달해 페이지 종료를 방지한다. 호출 순서·Promise·정리 규칙은 [Framework Integration](framework-integration.md)을 따른다.

구조·참조·cycle·보안의 fatal Validation issue는 차트 Error다. 집계 정책 미확정은 차트 Error와 구별하여 ready의 AggregationResult `unavailable`로 전달하는 제안이다. Source 로딩·JSON 구문·매핑 실패도 제어된 Error지만 code/path로 Validation 오류와 구별하고 서버 원문을 전달하지 않는다. warning·업무 승인 필요 issue의 공개 전달 형식과 치명도는 API 승인 전 확정한다.

API Source로 전환해도 facade·각 framework의 사용 구조는 유지하고 Source만 바꾼다. 인증은 호스트 client가 처리한다. 검색·다운로드·편집·추가 메뉴·상세 모달은 이번 범위가 아니다.

## 4. 데이터 변경과 갱신

조직 추가/삭제·명칭·parent 이동, 직원 추가/삭제·조직 이동·직위/직책·사진·상태·관계사 변경, relation 변경, 기준일·제목 변경은 스냅샷 → Validation → ViewModel 재계산으로 반영한다. 전체 재계산 방식을 우선 검토하고 정렬은 Data Contract의 초안을 따른다.

Source 전환·reload·update마다 이전 작업을 취소하고 revision을 비교해 늦은 응답을 무시한다. Metadata 버전이 같아도 새 스냅샷은 검증한다. engine에는 복사본만 전달한다. 확장 상태·focus·zoom 보존은 PoC 후 결정하며 복원 키는 안정된 도메인 ID다.

검증·집계·render는 Core가 소유한 동일 불변 스냅샷을 사용한다. JSON Source의 캡처 시점은 생성 시점으로 제안하고 update는 호출 시 입력을 확보한다. 최종 DOM/state 반영 직전에도 revision·destroy 상태를 검사한다. consumer가 원본 객체를 나중에 바꿔 이미 반영한 화면·숫자가 암묵적으로 바뀌면 계약 실패다.

데이터만 바꾸는 범위는 승인된 계약의 유형·상태·표현 옵션 안이다. 새 업무 정책·관계 의미·카드 기능은 계약/UI 버전 변경이 필요할 수 있다. 모든 미래 변경을 무조건 무코드로 약속하지 않는다.

## 5. 엔진과 콘텐츠 경계

엔진은 조직 parent-child와 기본 계층 연결선을 담당한다. 직원은 조직 ID로 조회해 노드/그룹에 표시하고 리더를 조직으로 중복 삽입하지 않는다.

중앙 허브가 실제 조직인지 설명 콘텐츠인지 TBD다. 임시 visual root는 내부에서만 생성하고 집계에서 제외한다. 다중 root 처리도 미확정이다. `OrganizationRelation`은 parent-child와 별도이며 engine `relationship` 플래그로 치환하지 않는다. 특수 곡선·교차 관계·고정 배치는 별도 Overlay/Layout 후보로 검토한다. 추가 relation은 집계 분모를 변경하지 않는다.

완료 조건과 미결정 의존성은 [Implementation Plan](implementation-plan.md)을 따른다.