Codewalkers/docs/frontend.md

# Frontend

`apps/web/` — React web UI for managing initiatives, agents, and content.

## Tech Stack

| Technology | Purpose |
|-----------|---------|
| React 19 | UI framework |
| TanStack Router | File-based routing |
| tRPC React Query | Type-safe API client with caching |
| Tailwind CSS | Utility-first styling |
| shadcn/ui | Component library (button, card, dialog, dropdown, input, label, textarea, badge, sonner, tooltip) |
| Tiptap | Rich text editor (ProseMirror-based) |
| Lucide | Icon library |
| Geist Sans/Mono | Typography (variable fonts in `public/fonts/`) |

## Design System (v2)

Theme spec: `docs/wireframes/v2/theme.md`

- **Brand**: Indigo (#6366F1) — `--primary` is indigo, not black
- **Dark mode**: 3-state toggle (light/system/dark), persisted in `localStorage('cw-theme')`
- **Status tokens**: 6 semantic statuses (active/success/warning/error/neutral/urgent) with bg/fg/border/dot variants. Use `bg-status-{status}-bg`, `text-status-{status}-fg`, etc.
- **Terminal tokens**: Always-dark surface for agent output. Use `bg-terminal`, `text-terminal-fg`, etc.
- **Diff tokens**: `bg-diff-add-bg`, `text-diff-remove-fg`, etc.
- **Shadows**: 5-level system (xs-xl). Dark mode uses inset highlights + ambient glow.
- **Transitions**: `duration-fast`, `duration-normal`, `ease-default`, `ease-spring`
- **Z-index**: Named scale from `z-base` to `z-tooltip`
- **Radius**: 6px base (down from 8px)
- **Flash prevention**: Inline `<script>` in `index.html` reads theme before paint

### Status-to-Entity Mapping

Use `mapEntityStatus(rawStatus)` from `StatusDot.tsx` to convert raw entity statuses to semantic tokens. `StatusDot` and `StatusBadge` both use this automatically.

## Path Alias

`@/*` maps to `./src/*` (configured in `tsconfig.app.json`).

## Routes

| Route | Component | Purpose |
|-------|-----------|---------|
| `/` | `routes/index.tsx` | Dashboard / initiative list |
| `/initiatives/$id` | `routes/initiatives/$initiativeId.tsx` | Initiative detail (tabbed) |
| `/settings` | `routes/settings/index.tsx` | Settings page |

## Initiative Detail Tabs

The initiative detail page has three tabs managed via local state (not URL params):

1. **Content Tab** — Page tree + Tiptap editor, proposal review
2. **Execution Tab** — Pipeline visualization, phase management, task dispatch
3. **Review Tab** — Pending proposals from agents

## Component Inventory (73 components)

### Core Components (`src/components/`)
| Component | Purpose |
|-----------|---------|
| `InitiativeCard` | Initiative list card with activity indicator (dot + label + phase progress), overflow menu |
| `InitiativeHeader` | Initiative name, project badges, inline-editable execution mode & branch |
| `InitiativeContent` | Content tab with page tree + editor |
| `StatusDot` | Small colored dot using status tokens, with pulse animation |
| `StatusBadge` | Colored badge using status tokens |
| `TaskRow` | Task list item with status, priority, category |
| `QuestionForm` | Agent question form with options |
| `InboxDetailPanel` | Agent message detail + response form |
| `ProjectPicker` | Checkbox list for project selection |
| `RegisterProjectDialog` | Dialog to register new git project |
| `Skeleton` | Loading placeholder with shimmer animation |
| `SkeletonCard` | Composite skeleton layouts (agent-card, initiative-card, etc.) |
| `EmptyState` | Shared empty state with icon, title, description, action |
| `ErrorState` | Shared error state with retry |
| `SaveIndicator` | Saving/saved/error status indicator |
| `CommandPalette` | Cmd+K search palette (initiatives, agents, navigation) |
| `ThemeToggle` | 3-state theme toggle (Sun/Monitor/Moon) |
| `NavBadge` | Numeric badge for nav items |
| `KeyboardShortcutHint` | Formatted keyboard shortcut display |
| `ConnectionBanner` | Offline/reconnecting state banner |
| `HealthDot` | Server health indicator with tooltip |
| `BrowserTitleUpdater` | Dynamic document.title with agent counts |

### Editor Components (`src/components/editor/`)
| Component | Purpose |
|-----------|---------|
| `TiptapEditor` | Core rich text editor wrapper |
| `PageEditor` | Page content editor with auto-save |
| `PhaseContentEditor` | Phase content editor |
| `ContentProposalReview` | Accept/dismiss proposals from agents |
| `SlashCommandMenu` | Slash command popup in editor |

### Execution Components (`src/components/execution/`)
| Component | Purpose |
|-----------|---------|
| `ExecutionTab` | Main execution view container |
| `ExecutionContext` | React context for execution state |
| `PhaseDetailPanel` | Phase detail with tasks, dependencies, plan |
| `PhaseSidebar` | Phase list sidebar |
| `TaskDetailPanel` | Task detail with agent status, output |

### Pipeline Components (`src/components/pipeline/`)
| Component | Purpose |
|-----------|---------|
| `PipelineVisualization` | DAG visualization of phase pipeline |
| `PipelineNode` | Individual phase node in pipeline |
| `PipelineEdge` | Dependency edge between nodes |

### Review Components (`src/components/review/`)
| Component | Purpose |
|-----------|---------|
| `ReviewTab` | Review tab container with diff viewer and preview integration |
| `ReviewSidebar` | Review info, actions, file list, comment summary |
| `DiffViewer` | Unified diff renderer with inline comments |
| `PreviewPanel` | Docker preview status: building/running/failed with start/stop |
| `ProposalCard` | Individual proposal display |

### UI Primitives (`src/components/ui/`)
shadcn/ui components: badge (6 status variants + xs size), button, card, dialog, dropdown-menu, input, label, select, sonner, textarea, tooltip.

## Custom Hooks (`src/hooks/`)

| Hook | Purpose |
|------|---------|
| `useRefineAgent` | Manages refine agent lifecycle for initiative |
| `useDetailAgent` | Manages detail agent for phase planning |
| `useAgentOutput` | Subscribes to live agent output stream |
| `useConnectionStatus` | Tracks online/offline/reconnecting state |
| `useGlobalKeyboard` | Global keyboard shortcuts (1-4 nav, Cmd+K) |

## Theme (`src/lib/theme.tsx`)

`ThemeProvider` wraps the app root. `useTheme()` returns `{ theme, setTheme, isDark }`. The provider listens for OS `prefers-color-scheme` changes when in `system` mode.

## tRPC Client

Configured in `src/lib/trpc.ts`. Uses `@trpc/react-query` with TanStack Query for caching and optimistic updates.

## Key User Flows

### Creating an Initiative
1. Dashboard → "New Initiative" → enter name, optional description, select projects
2. `createInitiative` mutation → auto-creates root page (seeded with description as tiptap content); if description provided, auto-spawns refine agent
3. Navigate to initiative detail page on success

### Managing Content (Pages)
1. Content tab → page tree sidebar
2. Click page → Tiptap editor loads content
3. Edit → auto-saves via `updatePage` mutation
4. Use slash commands for formatting

### Refining Content with AI
1. Content tab → "Refine" button
2. `spawnArchitectRefine` mutation → agent analyzes pages
3. Agent creates proposals (page edits, new phases, tasks)
4. Proposals appear in review section → accept/dismiss each

### Pipeline Visualization
1. Execution tab → pipeline DAG shows phases as nodes
2. Drag to add dependencies between phases
3. Approve phases → queue for dispatch
4. Tasks auto-queued when phase starts

### Detailing Phases
1. Select phase → "Detail" button
2. `spawnArchitectDetail` mutation → agent creates task proposals
3. Accept proposals → tasks created under phase
4. View tasks in phase detail panel

## Shared Package

`packages/shared/` exports:
- `sortByPriorityAndQueueTime()` — priority-based task sorting
- `topologicalSort()` / `groupByPipelineColumn()` — phase DAG layout
- `InitiativeActivity` / `InitiativeActivityState` — server-computed activity state for initiative cards
- Shared type re-exports from `packages/shared/src/types.ts` (which re-exports from `apps/server/`)

## Initiative Activity Indicator

`listInitiatives` returns an `activity` field on each initiative, computed server-side from phase statuses via `deriveInitiativeActivity()` in `apps/server/trpc/routers/initiative-activity.ts`. This eliminates per-card N+1 `listPhases` queries.

Activity states (priority order): active architect agents > `pending_review` > `executing` > `blocked` > `complete` > `ready` > `planning` > `idle` > `archived`. Each state maps to a `StatusVariant` + pulse animation in `InitiativeCard`'s `activityVisual()` function. Active architect agents (modes: discuss, plan, detail, refine) are checked first — mapping to `discussing`, `detailing`, `detailing`, `refining` states respectively — so auto-spawned agents surface activity even when no phases exist yet. `PhaseSidebarItem` also shows a spinner when a detail agent is active for its phase.