# Frontend

`packages/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) |
| Tiptap | Rich text editor (ProseMirror-based) |
| Lucide | Icon library |

## 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 |
|-----------|---------|
| `InitiativeHeader` | Initiative name, project badges, inline-editable execution mode & branch |
| `InitiativeContent` | Content tab with page tree + editor |
| `StatusBadge` | Colored status indicator |
| `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 |

### 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, button, card, dialog, dropdown-menu, input, label, sonner, textarea.

## 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 |

## 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, select projects
2. `createInitiative` mutation → auto-creates root page
3. Navigate to initiative detail

### 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
- Shared type re-exports from `packages/shared/src/types.ts`