Web Frontend Guided Demo

This demo walks through the FCC React frontend -- a Vite + React + TypeScript application with seven D3-powered visualizations, real-time WebSocket event streaming, and a NanoCube data explorer.

---

Table of Contents

1. Introduction and Prerequisites
2. Dashboard Overview
3. Persona Browser
4. Workflow Graphs
5. Protocol Explorer
6. HypothesisLab
7. D3 Visualization Deep Dives
8. Tips and Customization

---

Introduction and Prerequisites

System Requirements

• Node.js 18+ and npm
• Python 3.10+ with FCC installed (pip install -e ".[dev]")
• A modern browser (Chrome, Firefox, or Edge)

Getting Started

cd frontend
npm install
npm start

The dev server starts at http://localhost:5173. The frontend connects to the FCC Python backend via WebSocket at ws://localhost:8765/ws/events and fetches persona data from /api/personas.

Offline mode: If the Python backend is not running, the frontend gracefully falls back to a static dataset of 21 personas embedded in the usePersonaRegistry hook.

Project Structure

frontend/src/
  main.tsx              # Vite entry point
  App.tsx               # Router and layout
  components/
    Layout.tsx          # Shell with navigation sidebar
    ThemeToggle.tsx     # Light/dark mode switch
    hypothesis/         # H1-H5 hypothesis panels
  hooks/
    usePersonaRegistry.ts   # Persona data fetching & filtering
    useWebSocket.ts         # WebSocket connection with auto-reconnect
  pages/
    Dashboard.tsx       # Landing page with stat cards
    Personas.tsx        # Grid/list persona browser
    Workflows.tsx       # Sankey workflow graphs
    Protocols.tsx       # A2A + MCP protocol viewer
    HypothesisLab.tsx   # Hypothesis panels + NanoCubeExplorer
    Collaboration.tsx   # Session monitoring
  visualizations/
    ForceGraph.tsx      # Force-directed persona network
    SankeyWorkflow.tsx  # Sankey workflow phase flow
    VoronoiPersonaMap.tsx   # Voronoi category territories
    ChordDiagram.tsx    # Cross-reference chord diagram
    HyperEdgeGraph.tsx  # Champion orchestration hyperedges
    ProvenanceFlow.tsx  # Artifact lineage timeline
    HeatmapMatrix.tsx   # Dimension score heatmap
    NanoCubeExplorer.tsx    # Interactive data drill-down
    d3-utils.ts         # Shared color scales, tooltips, responsive SVG

---

Dashboard Overview

The Dashboard page (pages/Dashboard.tsx) is the landing page. It provides a high-level summary of the FCC framework state.

Stat Cards

Four stat cards display key metrics in a responsive grid:

Card	Value	Description
Total Personas	102	Core + plugin personas
Categories	20	Persona categories
Tests	5,570+	Pytest + Vitest combined
Workflow Graphs	6	5-node base through 55-node extended

The persona count and category count are loaded dynamically via the usePersonaRegistry hook. While loading, the cards show a placeholder ... value.

FCC Phase Cards

Three cards summarize the core FCC phases:

• Find -- Research, discover, gather information. Explore the problem space, identify constraints, and surface relevant knowledge.
• Create -- Design, build, and synthesize solutions. Transform findings into actionable architectures and deliverables.
• Critique -- Review, evaluate, and refine. Apply quality gates, governance checks, and iterative improvement.

Each card is color-coded to match the FCC phase palette defined in d3-utils.ts: Find (#1E88E5), Create (#43A047), Critique (#E53935).

WebSocket Connection Status

A status indicator in the top-right corner shows the live WebSocket connection state. It uses the useWebSocket hook which automatically reconnects with exponential backoff (3-second intervals, up to 10 attempts).

• Green dot + "Connected" -- Real-time event streaming is active.
• Gray dot + "Disconnected" -- Backend is unreachable; frontend operates in read-only mode with static data.

Quick Links

Four quick-link cards provide navigation to the main pages:

• Persona Browser -- Explore all personas with filtering and search
• Workflow Graphs -- Visualize FCC workflow graphs
• Protocol Integration -- View A2A cards, MCP tools, and event feeds
• Collaboration Sessions -- Monitor human-in-the-loop sessions

---

Persona Browser

The Persona Browser page (pages/Personas.tsx) provides two view modes for exploring the full persona catalog.

Grid View vs. List View

Toggle between grid and list layouts:

• Grid view shows persona cards in a responsive multi-column layout. Each card displays the persona ID, name, category badge, phase badge, role title, and archetype.
• List view shows a compact table with sortable columns.

Category Filter Sidebar

A sidebar lists all 20 persona categories. Click a category to filter the display. Active filters are highlighted. Click again to remove the filter.

Categories include: core, integration, governance, stakeholder, champion, open_science, responsible_ai, jv_collaboration, docs_as_code, privacy, knowledge_graph, local_first_ai, data_engineering, ml_lifecycle, ml_models, devops, app_development, ux_visualization, protocol_engineering, jv_governance.

usePersonaRegistry Hook

The hook (hooks/usePersonaRegistry.ts) provides:

interface UsePersonaRegistryReturn {
  personas: PersonaData[]      // Full persona list
  loading: boolean             // True while fetching
  error: string | null         // Error message if fetch failed
  refresh: () => void          // Re-fetch from API
  getByCategory: (category: string) => PersonaData[]
  getByPhase: (phase: string) => PersonaData[]
  search: (query: string) => PersonaData[]
  categories: string[]         // Sorted unique categories
  phases: string[]             // Sorted unique phases
}

The hook first tries GET /api/personas. If the backend is unavailable, it falls back to STATIC_PERSONAS -- a 21-entry dataset covering core, integration, governance, stakeholder, and champion categories.

Persona Detail Modal

Clicking a persona card opens a detail modal with the full R.I.S.C.E.A.R. breakdown:

Component	Description
Role	Role title and archetype
Input	Expected inputs and data sources
Style	Communication and working style
Constraints	Operational boundaries
Expected Output	Deliverables this persona produces
Archetype	Behavioral archetype label
Responsibilities	Enumerated responsibilities
Role Skills	Technical and soft skills
Role Collaborators	Upstream, downstream, and peer personas
Role Adoption Checklist	Steps to adopt this persona

---

Workflow Graphs

The Workflows page (pages/Workflows.tsx) renders FCC workflow graphs as Sankey diagrams using the SankeyWorkflow visualization component.

Graph Options

Six workflow graph options are available:

Graph	Nodes	Description
base_sequence	5	Minimal FCC workflow
extended_sequence	20	Standard extended workflow
complete_24	24	Full workflow with all transitions
extended_84	55	Extended with all 102 core personas
eaifc_solution	varies	Solution-level EAIFC graph
eaifc_extended	varies	Extended EAIFC graph

Sankey Layout

The SankeyWorkflow component (visualizations/SankeyWorkflow.tsx) arranges nodes into phase columns using the predefined order:

Find --> Create --> Critique --> Build --> Ops

Nodes are grouped by their phase attribute and distributed vertically within each column. The layout is computed without external Sankey plugins -- a custom computeSankeyLayout function handles positioning.

Node Coloring

Nodes are colored by their FCC phase using the getFccColor utility:

const FCC_COLORS = {
  find: '#1E88E5',      // Blue
  create: '#43A047',    // Green
  critique: '#E53935',  // Red
  build: '#FB8C00',     // Orange
  ops: '#8E24AA',       // Purple
}

Edge Types

Edges represent three relationship types:

• Handoff -- Work product passes from one persona to another
• Feedback -- Critique flows back to an earlier phase
• Orchestration -- Champion coordinates multiple personas

Edge width is proportional to the value attribute on each link.

---

Protocol Explorer

The Protocols page (pages/Protocols.tsx) provides views into the A2A and MCP protocol integration layer.

A2A Card Generation Viewer

View generated A2A (Agent-to-Agent) cards for each persona. An A2A card describes a persona's skills, endpoints, and capabilities in the Google A2A protocol format.

MCP Tool/Resource Browser

Browse the MCP (Model Context Protocol) tools and resources exposed by the FCC framework. Each tool listing shows its name, description, input schema, and the persona(s) that invoke it.

Protocol Event Feed

A live event feed shows protocol events streamed from the EventBus via WebSocket. Events are filtered to show only protocol-related types:

• protocol.a2a.task.received
• protocol.a2a.task.completed
• protocol.a2a.task.failed
• protocol.a2a.card.requested
• protocol.mcp.tool.called
• protocol.mcp.tool.completed
• protocol.mcp.tool.failed
• protocol.mcp.resource.read
• protocol.mcp.prompt.rendered
• protocol.bridge.error

Each event row shows the timestamp, event type, source, and expandable payload.

---

HypothesisLab

The HypothesisLab page (pages/HypothesisLab.tsx) is an experimental workspace for exploring research hypotheses about agent collaboration.

H1--H5 Hypothesis Panels

Five hypothesis panels correspond to research questions about agent team effectiveness:

Panel	Hypothesis
H1	Multi-persona collaboration improves solution quality
H2	Champion orchestration reduces coordination overhead
H3	Cross-category interaction increases innovation
H4	Governance gates improve compliance without blocking delivery
H5	Real-time feedback loops accelerate convergence

Each panel shows supporting data, evidence indicators, and links to relevant workflow traces.

NanoCubeExplorer

The NanoCubeExplorer component (visualizations/NanoCubeExplorer.tsx) provides interactive drill-down into multi-dimensional persona data.

interface NanoCubeExplorerProps {
  dimensions: NanoCubeDimension[]  // Available dimension axes
  records: NanoCubeRecord[]        // Data records to explore
  title?: string                   // Explorer title
}

Features:

• Dimension selector -- Choose which dimension to aggregate by
• Drill-down filters -- Click a row to add a filter and drill deeper
• Sortable columns -- Sort by count or any measure
• Aggregation -- Automatic count and sum aggregation per group

---

D3 Visualization Deep Dives

The frontend includes seven D3 visualization components, all following the same Rosetta pattern: React owns the container and lifecycle; D3 renders inside a useRef-managed SVG element.

1. ForceGraph -- Persona Network

Renders a force-directed graph of persona relationships.

Data shape:

interface ForceNode {
  id: string        // Persona ID (e.g. "RC")
  name: string      // Display name
  category: string  // Category for coloring
  phase: string     // FCC phase
}

interface ForceLink {
  source: string    // Source persona ID
  target: string    // Target persona ID
  type: string      // Relationship type
  strength: string  // "primary" | "secondary" | "tertiary"
}

Key behaviors:

• Collision detection prevents node overlap
• Link strength varies by relationship tier (primary=0.7, secondary=0.4, tertiary=0.2)
• Nodes are colored by category via createColorScale
• Hover tooltip shows persona name, category, and phase
• Drag interaction repositions nodes

2. SankeyWorkflow -- Phase Flow

Renders workflow transitions as a Sankey diagram with phase-based columns.

Data shape:

interface SankeyNode {
  id: string      // Node identifier
  name: string    // Display name
  phase: string   // "Find" | "Create" | "Critique" | "Build" | "Ops"
}

interface SankeyLink {
  source: string  // Source node ID
  target: string  // Target node ID
  value: number   // Flow weight
}

Key behaviors:

• Nodes arranged in columns by phase order: Find, Create, Critique, Build, Ops
• Node height proportional to total flow value
• Links rendered as curved paths between columns
• Phase coloring from getFccColor

3. VoronoiPersonaMap -- Category Territories

Renders Voronoi tessellation of personas grouped by category.

Data shape:

interface VoronoiPersona {
  id: string        // Persona ID
  name: string      // Display name
  category: string  // Category for grouping
  x?: number        // Optional initial x position
  y?: number        // Optional initial y position
}

Key behaviors:

• Personas clustered by category using angular distribution
• Force simulation positions nodes with collision avoidance
• Voronoi cells computed from final positions, creating territory regions
• Category-colored cell fills with hover highlighting
• Tooltip shows persona details on hover

4. ChordDiagram -- Cross-References

Renders cross-reference interactions between persona categories as a chord diagram.

Data shape:

interface ChordCategory {
  name: string   // Category name
  count: number  // Number of personas in category
}

interface ChordInteraction {
  source: string  // Source category name
  target: string  // Target category name
  value: number   // Interaction weight
}

Key behaviors:

• Outer arcs sized by category persona count
• Inner ribbons show interaction strength between categories
• Symmetric: source->target and target->source are summed
• Arc labels show category names
• Hover highlights connected ribbons

5. HyperEdgeGraph -- Multi-Persona Connections

Renders champion-to-persona orchestration relationships as hyperedges.

Data shape:

interface ChampionNode {
  id: string              // Persona ID
  name: string            // Display name
  category: string        // Category for coloring
  isChampion: boolean     // True for champion personas
  orchestrates?: string[] // IDs of orchestrated personas
}

Key behaviors:

• Champion nodes rendered larger than base personas
• Hyperedges drawn as convex hulls around orchestrated groups
• Force simulation separates champions from base personas
• Category coloring distinguishes persona types

6. ProvenanceFlow -- Artifact Lineage

Renders project phase timeline as a horizontal flow.

Data shape:

interface ProvenancePhase {
  id: string          // Phase identifier
  name: string        // Display name
  phase: string       // FCC phase for coloring
  startDate: string   // ISO date string (YYYY-MM-DD)
  endDate?: string    // Optional end date
  milestones?: string[] // Optional milestone labels
}

Key behaviors:

• Time axis (x) with automatic date range scaling
• Phase bars colored by FCC phase
• Milestone markers shown as vertical lines within phase bars
• Tooltip shows phase details and date range

7. HeatmapMatrix -- Dimension Heatmap

Renders a matrix heatmap of persona dimension scores.

Data shape:

interface HeatmapCell {
  source: string  // Row label (persona)
  target: string  // Column label (dimension)
  value: number   // Score (0--100)
}

interface HeatmapMatrixProps {
  labels: string[]               // Row and column labels
  cells: HeatmapCell[]           // Cell data
  width?: number
  height?: number
  colorRange?: [string, string]  // [min color, max color]
}

Key behaviors:

• Sequential color scale from light (#f5f5f5) to dark (#1565C0)
• Rotated column labels at 45 degrees for readability
• Cell size auto-computed from available space and label count
• Hover tooltip shows exact score value

---

Tips and Customization

Theming

Use the ThemeToggle component to switch between light and dark modes. The toggle persists the preference in localStorage. All D3 visualizations respect the current theme via CSS custom properties.

Adding a New Visualization

1. Create a new file in frontend/src/visualizations/.
2. Follow the Rosetta pattern: export a React component that accepts a useRef<SVGSVGElement> and renders D3 inside useEffect.
3. Use responsiveSvg from d3-utils.ts for consistent SVG setup.
4. Use createColorScale for FCC-consistent coloring.
5. Use createTooltip for accessible hover tooltips.

Responsive Sizing

All visualizations accept optional width and height props with sensible defaults. The responsiveSvg utility sets a viewBox and preserveAspectRatio="xMidYMid meet" so visualizations scale with their container.

Color Palette Reference

The full FCC color palette is defined in d3-utils.ts under FCC_COLORS. It maps all 5 phases and 20 persona categories to consistent hex colors. See the Visualization Cookbook for recipes that use these colors.

WebSocket Configuration

The default WebSocket URL is ws://localhost:8765/ws/events. To change it, pass a custom URL to the useWebSocket hook:

const { isConnected, messages } = useWebSocket('ws://your-host:port/ws/events')

The hook auto-reconnects with a 3-second delay, up to 10 attempts.