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
PipelineTab	Execution tab entry — fetches tasks, phase deps, task deps
PipelineGraph	Horizontal DAG of phase columns with connectors
PipelineStageColumn	Single depth column containing phase groups
PipelinePhaseGroup	Phase card with status border accent, progress bar, TaskGraph

Review Components (src/components/review/)

Component	Purpose
ReviewTab	Review tab container — orchestrates header, diff, sidebar, and preview
ReviewHeader	Consolidated toolbar: phase selector pills, branch info, stats, preview controls, approve/reject actions
ReviewSidebar	VSCode-style icon strip (Files/Commits views) with file list, comment counts, and commit navigation
DiffViewer	Unified diff renderer with inline comments
PreviewPanel	Docker preview status: building/running/failed with start/stop (legacy, now integrated into ReviewHeader)
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
useChatSession	Manages chat session for phase/task refinement
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. Per-phase Play button: if phase is pending (with non-detail tasks), approves then queues in one click; if already approved, just queues
4. "Execute N phases" top-level button: approves all pending phases that have tasks, then calls queueAllPhases — count includes both pending (with tasks) and approved phases
5. 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

Chat with Phase/Task

1. Execution tab → select phase → "Chat" button (or open task → "Chat" button in footer)
2. ChatSlideOver opens as right-side panel
3. Send message → sendChatMessage mutation → agent spawns (or resumes) in 'chat' mode
4. Agent applies changes (create/update/delete phases, tasks, pages) → changeset created
5. Assistant message appears with inline changeset summary + revert button
6. Send next message → agent resumes → repeat
7. Close chat → session closed, agent dismissed

Components: ChatSlideOver, ChatBubble, ChatInput, ChangeSetInline in src/components/chat/.

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.