frontend/README.md

AgentGraph React

A modern React-based interface for AI agent pipeline analysis and knowledge graph management, built with Shadcn UI components.

Features

• Modern UI: Built with React 18, TypeScript, and Shadcn UI components
• Trace Management: Upload, view, and manage AI agent execution traces
• Pipeline Processing: Run comprehensive analysis pipelines including:
  • Prompt Reconstruction
  • Perturbation Testing
  • Causal Analysis
• Knowledge Graphs: Generate and visualize knowledge graphs from trace data
• Real-time Updates: Live progress tracking and status updates
• Command Palette: Quick access to all features via Cmd/Ctrl+K
• Dark/Light Theme: Automatic theme switching with system preference

Tech Stack

• React 18 with TypeScript
• Vite for fast development and building
• Shadcn UI for beautiful, accessible components
• Tailwind CSS for styling
• Lucide React for icons
• React Query for data fetching (planned)

Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type checking
npm run type-check

# Linting
npm run lint

Development Server

The development server runs on http://localhost:3001 with hot reload enabled.

Building

The build output goes to ../static/js/agentgraph/dist/ to integrate with the FastAPI backend.

Integration

This React app integrates with the existing FastAPI backend:

• Route: /agentgraph - Main interface
• API Proxy: Development server proxies /api/* to http://localhost:8000
• Static Assets: Built files are served by FastAPI from /static/js/agentgraph/dist/

Project Structure

src/
├── components/
│   ├── ui/              # Shadcn UI components
│   ├── layout/          # Layout components (sidebar, workspace)
│   ├── features/        # Feature-specific components
│   │   ├── upload/      # File upload functionality
│   │   ├── traces/      # Trace management
│   │   ├── pipeline/    # Pipeline processing
│   │   ├── command/     # Command palette
│   │   └── workspace/   # Main workspace views
│   └── shared/          # Shared components
├── context/             # React contexts for state management
├── hooks/               # Custom React hooks
├── lib/                 # Utilities and API client
├── types/               # TypeScript type definitions
└── styles/              # Global styles

API Integration

The app uses a centralized API client (src/lib/api.ts) that interfaces with the FastAPI backend:

• Traces: Upload, list, and process trace files
• Knowledge Graphs: Generate, enrich, and analyze knowledge graphs
• Tasks: Monitor background task progress
• Pipeline: Execute and monitor analysis stages

State Management

Uses React Context for global state management:

• AgentGraphContext: Main application state (traces, pipeline stages, etc.)
• ThemeContext: Theme switching (light/dark)
• NotificationContext: Toast notifications and alerts

Commands

• Cmd/Ctrl+K: Open command palette
• Upload: Drag & drop or click to upload trace files
• Pipeline: Start/stop analysis pipeline stages
• Theme: Toggle between light and dark themes

Contributing

1. Follow the existing code structure and patterns
2. Use TypeScript for all new code
3. Follow the Shadcn UI component patterns
4. Add proper error handling and loading states
5. Update types when adding new features