Codewalkers/docs/frontend.md

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