hushroom/.cli/docs/architecture.md

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 재사용
• 메모/노트 입력은 탑승 생성 경로에서 제거됨

I18n 소유권 (1단계)

• 지원 언어/기본값/카피 상수: shared/config/i18n.ts
• 초기 언어 결정/수동 고정 저장: features/i18n/model/resolveInitialLocale.ts
• 런타임 번역 접근(context/hook): features/i18n/model/useI18n.tsx
• 앱 초기 bootstrap + 수동 변경 UI(헤더 select): features/i18n/ui/I18nLayoutShell.tsx
• app/layout.tsx는 i18n shell을 마운트해 단일 URL에서 언어 상태만 관리한다
• 우선순위: 수동 저장값(localStorage) > 브라우저 언어 > en
• 지원 외 언어는 en으로 폴백한다
• 페이지/UI 문구는 key(lobby.*, flight.*, debrief.*, log.*, settings.*, routes.*)로 관리한다
• 항로 메타(shared/config/routes.ts)는 사용자 노출 문자열 대신 i18n key를 소유한다

변경 정책

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