# Architecture

## 목표

- 사람이 유지보수하기 쉬운 구조
- LLM/CLI가 토큰을 낭비하지 않고 정확히 수정할 수 있는 구조
- 경계(레이어)를 강제해 회귀(regression)를 예방

## 레이어 규칙 (FSD)

### app/\*

- 페이지/레이아웃은 **조합자(composer)** 역할만 한다
- `app/**` 는 **widgets public API만** import 한다
- `app/**` 는 `features/entities/shared`의 UI를 직접 import 하지 않는다

### widgets/\*

- 페이지 단위 블록(화면 조립 단위)
- `index.ts`를 통해 public API를 노출한다
- 내부에서 `features/entities/shared`를 조합한다

### features/\*

- 제품 기능 단위(UI + model + lib)
- `app/*` 를 import 하면 안 된다
- `entities/shared` 는 import 가능

### entities/\*

- 도메인 모델(session/log 등)
- 가능한 한 타입/스키마를 스스로 소유한다
- `shared` 만 import 가능

### shared/\*

- 재사용 가능한 최소 단위(ui/lib/config/types)
- `entities/features/widgets/app` 를 import 하면 안 된다

## Public API 규칙

- 모든 widget은 `index.ts`를 가진다
- 페이지는 아래 형태로 import 한다:
  - `import { X } from "@/widgets/x";`
- `app/*`에서 `widgets/x/ui/*` 같은 깊은 경로 import는 피한다

## 공용 위치 규칙

- `shared/ui`: 공용 UI 프리미티브(button/card/dialog/input…)
- `shared/lib`: 순수 유틸(math/motion 등)
- `shared/config`: 튜닝 상수(예: starfield params)

## LLM/CLI 작업 규칙

- 모든 작업은 `current.md`에 **대상 파일 경로**를 반드시 명시한다
- 튜닝 작업은 가능하면 **config만 수정**한다
- 레포 검색이 필요하면 `grep/rg`는 1회만 사용하고, 결과 요약은 5줄 이내로 제한한다

## Starfield 소유권

- Flight 배경 로직: `features/flight-starfield/**`
- Lobby 별자리/글린트: `features/lobby-starfield/**`
- 페이지 마운트: `widgets/flight-background`, `widgets/lobby-background`
- 튜닝 파라미터: `shared/config/starfield.ts`

## Boarding 소유권

- 탑승 시작 로직: `features/boarding/model/startVoyage.ts`
- 탑승 미션 폼 UI: `features/boarding/ui/BoardingMissionForm.tsx`
- 로비 출항 진입: `widgets/lobby-routes` (modal open/close + flight 진입)
- `/boarding` 라우트: 딥링크 호환을 위해 동일 form/model 재사용
- 메모/노트 입력은 탑승 생성 경로에서 제거됨

## 변경 정책

- 구조 리팩토링은 명시적으로 요청되지 않는 한 동작을 바꾸면 안 된다
- 포맷만 바꾸는 변경(diff) 지양