270a5cb21d
Preview deployments let reviewers spin up the app at a specific branch in local Docker containers, accessible through a single Caddy reverse proxy port. Docker is the source of truth — no database table needed. New module: src/preview/ with config discovery (.cw-preview.yml → compose → Dockerfile fallback), compose generation, Docker CLI wrapper, health checking, and port allocation (9100-9200 range).
138 lines
5.0 KiB
Markdown
138 lines
5.0 KiB
Markdown
# 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, merge config |
|
|
| `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`
|