# web

## 목적 / 책임

NomadCode의 브라우저 운영 콘솔 도메인이다. 프로젝트/agent workspace, backend integration, UI shell, 클라이언트 상태 관리를 담당한다.

## 포함 경로

- `apps/web/src/app/` — React app과 router 조립.
- `apps/web/src/routes/` — 페이지 단위 route.
- `apps/web/src/layout/` — shell, navigation, sidebar.
- `apps/web/src/components/` — agent, project, settings, common UI components.
- `apps/web/src/stores/` — Zustand 기반 client state.
- `apps/web/src/api/` — backend API client.
- `apps/web/src/styles/` — global style.
- `apps/web/index.html`, `apps/web/.env.example` — Vite HTML entry와 환경 변수 예시.
- `apps/web/package.json`, `apps/web/package-lock.json`, `apps/web/vite.config.ts`, `apps/web/tsconfig.json` — web build/tooling.

## 제외 경로

- `services/core/` — API implementation과 persistence는 core 도메인이다.
- `apps/mobile/` — Flutter UI는 mobile 도메인이다.
- `packages/contracts/` — shared schema/source-of-truth는 contracts 도메인이다.

## 주요 구성 요소

- `src/app/App.tsx` — QueryClient와 router provider 조립.
- `src/app/router.tsx` — web route 구성.
- `src/layout/AppShell.tsx` — 전체 shell.
- `src/layout/AgentSidebar.tsx` — agent context/sidebar 영역.
- `src/routes/AgentPage.tsx` — agent workspace page.
- `src/routes/ProjectsPage.tsx` — project workspace page.
- `src/routes/SettingsPage.tsx` — integration settings page.
- `src/stores/agentStore.ts` — agent interaction state.
- `src/stores/layoutStore.ts` — shell navigation/sidebar state.
- `src/stores/projectStore.ts` — project workspace state.
- `src/api/client.ts` — API 호출 공통 client.
- `src/components/settings/IntegrationStatus.tsx` — integration 상태 표시와 테스트 액션 UI.

## 유지할 패턴

- 페이지는 `src/routes`, layout은 `src/layout`, 재사용 UI는 `src/components`에 둔다.
- API 호출 형태가 바뀌면 `src/api`를 먼저 갱신하고, 필요 시 contracts/core 변경을 같은 작업에 포함한다.
- shell/navigation 변경은 모바일 viewport도 함께 고려한다.
- 새 UI 상태는 route-local state와 shared store 중 책임 범위를 먼저 판단한다.
- settings/integration UI는 실제 API 연결 여부와 placeholder 동작을 구분한다.
- `npm run check`가 통과하도록 TypeScript type을 유지한다.

## 다른 도메인과의 경계

- **core**: web은 core의 HTTP/API surface만 사용한다.
- **contracts**: 반복되는 request/response shape는 contracts 후보로 올린다.
- **mobile**: UX 개념은 공유할 수 있지만 Flutter 구현과 React 구현은 분리한다.
- **workspace-ops**: root `bin/*`나 monorepo 문서는 web 변경과 분리한다.

## 금지 사항

- core 내부 구조를 web 컴포넌트에 하드코딩하지 않는다.
- API mock과 실제 API shape를 장기간 다르게 유지하지 않는다.
- 공통 UI component에 page-specific side effect를 넣지 않는다.
- 대규모 visual/style 변경과 API behavior 변경을 한 커밋에 섞지 않는다.