nomadcode/agent-ops/rules/project/domain/web/rules.md

domain	last_rule_review_commit	last_rule_updated_at
web	e3b5dae725	2026-05-21

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 변경을 한 커밋에 섞지 않는다.