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
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, 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 (which re-exports from apps/server/)