# ui-shell

## 목적 / 책임

앱 진입점, 라우터, 전체 레이아웃, 공통 UI 원자, 전역 스타일을 담당한다. 사용자가 Agent, Projects, Settings 화면 사이를 일관되게 이동할 수 있는 shell을 유지한다.

## 포함 경로

- `src/main.tsx` : React app mount 진입점
- `src/app/` : QueryClient, RouterProvider, route tree
- `src/layout/` : activity bar, top bar, mobile nav, agent sidebar 배치
- `src/components/common/` : 여러 화면에서 공유하는 Button, Card, EmptyState
- `src/styles/global.css` : 전역 토큰, layout, component class style
- `index.html`, `vite.config.ts` : Vite app shell 설정

## 제외 경로

- `src/routes/AgentPage.tsx`, `src/components/agent/`, `src/stores/agentStore.ts` : agent-workspace
- `src/routes/ProjectsPage.tsx`, `src/components/projects/`, `src/stores/projectStore.ts` : project-workspace
- `src/api/`, `src/components/settings/`, `src/routes/SettingsPage.tsx` : backend-integration

## 주요 구성 요소

- `App` : TanStack Query와 Router provider 조립
- `router` : root/index/agent/projects/settings route 정의
- `AppShell` : 주요 layout과 agent sidebar context 연결
- `ActivityBar`, `MobileNav`, `TopBar` : primary navigation과 shell action
- `Button`, `Card`, `EmptyState` : 반복 UI primitive

## 유지할 패턴

- 새 route는 `src/app/router.tsx`에 추가하고 shell navigation과 store 상태 동기화를 함께 점검한다.
- 공통 컴포넌트는 도메인 데이터를 알지 않도록 유지한다.
- 화면별 스타일은 기존 class naming 흐름 안에서 `global.css`에 모으되, 큰 UI 경계가 생기면 별도 스타일 분리를 검토한다.
- 버튼에는 가능한 한 lucide icon을 함께 사용하고 기존 size/variant 체계를 확장한다.

## 다른 도메인과의 경계

- **agent-workspace**: shell은 agent sidebar를 배치하지만 메시지 생성과 agent context 의미는 agent-workspace가 맡는다.
- **project-workspace**: shell은 현재 route와 선택된 프로젝트 정보를 전달할 뿐 프로젝트 목록 조작은 project-workspace에 둔다.
- **backend-integration**: 연결 상태 표시는 shell에서 보여줄 수 있으나 API base URL, fetch, health check 구현은 backend-integration에 둔다.

## 금지 사항

- 공통 컴포넌트에 특정 페이지의 mock 데이터나 API 호출을 넣지 않는다.
- route 변경과 navigation 표시 상태를 서로 다른 곳에서 중복 정의하지 않는다.
- `dist/` 생성물을 기준으로 UI를 수정하지 않는다.