---
domain: web
last_rule_review_commit: e3b5dae725db62dd7a47c563abcce557e0557551
last_rule_updated_at: 2026-05-21
---

# web

## 목적 / 책임

NomadCode의 이전 React/Vite 브라우저 운영 콘솔 scaffold 도메인이다. Flutter-first 전환 이후 장기 제품 UI 경로에서는 제외하며, 이 도메인의 작업은 제거, 격리, 또는 legacy 상태 보존에 한정한다.

## 포함 경로

- `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 source of truth는 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.

## 유지할 패턴

- 새 제품 기능을 React web에 추가하지 않는다.
- 제거 전 legacy 유지가 필요한 경우 기존 `src/routes`, `src/layout`, `src/components`, `src/api`, `src/stores` 구조를 유지한다.
- API 호출 형태가 바뀌면 Flutter 앱과 contracts/core 경계를 우선 확인하고, legacy web 변경은 필요한 최소 범위로 제한한다.
- legacy scaffold를 직접 수정할 때는 `npm run check`가 통과하도록 TypeScript type을 유지한다.

## 다른 도메인과의 경계

- **core**: web은 core의 HTTP/API surface만 사용한다.
- **contracts**: 반복되는 request/response shape는 contracts 후보로 올린다.
- **mobile**: Flutter 앱이 제품 UI source of truth이며, web은 제품 UI 구현을 복제하지 않는다.
- **workspace-ops**: root `bin/*`나 monorepo 문서는 web 변경과 분리한다.

## 금지 사항

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