frontend/README.md

IntegraChat Frontend

Next.js 16 / React 19 app that showcases everything wired up in backend/.
It provides a polished operator console with:

• Hero section + feature overview describing the FastAPI + MCP stack
• Live chat panel that POSTs to POST /agent/message for AI conversations
• Analytics dashboard pulling from GET /analytics/overview with real-time metrics
• Knowledge base management page (/knowledge-base) for document search and ingestion
• Document ingestion UI for uploading PDF, DOCX, TXT files or raw text
• Feature grid showcasing platform capabilities

Note: IntegraChat also includes a Gradio-based UI (app.py) with interactive visualizations, statistics cards, and Plotly charts. See the root README.md for details on running the Gradio interface.

Running Locally

cd frontend
npm install
npm run dev

Visit http://localhost:3000 for the main landing page, or http://localhost:3000/knowledge-base for document management.

API configuration

The UI calls the FastAPI service through NEXT_PUBLIC_API_URL (default http://localhost:8000).
Update .env.local if your backend runs elsewhere:

NEXT_PUBLIC_API_URL=http://localhost:8000

Tenant & Role selector

• The navbar widget now stores both the tenant ID and the MCP role (Viewer, Editor, Admin, Owner) in localStorage.
• Every API call automatically includes x-tenant-id and x-user-role headers so the backend RBAC layer can authorize ingestion, admin rule uploads, analytics, and delete operations.
• If you see a 403 "insufficient permissions" error, switch the role dropdown to a higher privilege (e.g., Admin) before retrying the action.
• Note: Analytics is now accessible to all roles (viewer, editor, admin, owner) for improved transparency.

Features

Main Landing Page (/)

• Hero section with platform introduction
• Feature grid showcasing key capabilities
• Chat panel for real-time AI conversations with reasoning visualizations
• Analytics panel with query metrics and tool usage statistics
• Ingestion card for quick document uploads

Real-Time Visualizations

The frontend includes three powerful visualization components:

1. Reasoning Path Visualizer (reasoning-visualizer.tsx)

• Step-by-step visualization of agent decision-making
• Animated progression through reasoning steps
• Status indicators and detailed metrics
• Integrated into chat panel with collapsible section

2. Tool Invocation Timeline (tool-timeline.tsx)

• Visual timeline of tool executions
• Latency and result count visualization
• Summary statistics
• Integrated into chat panel

3. Tenant Activity Heatmap (tenant-heatmap.tsx)

• Query activity heatmap (hour-by-hour, day-by-day)
• Per-tool usage trends
• Integrated into analytics page

Knowledge Base Page (/knowledge-base)

• Document listing with pagination and filtering by type (text, PDF, FAQ, link)
• Search interface for semantic search across documents
• Document ingestion with support for:
  • Raw text input
  • URL ingestion (automatic content fetching)
  • PDF file uploads
  • DOCX file uploads
  • TXT and Markdown file uploads
• Document management with tenant + role isolation:
  • Delete individual documents by ID
  • Delete all documents for a tenant (with confirmation)
  • Real-time document list updates after operations
  • Error handling with clear user feedback

Analytics Page (/analytics)

• Analytics overview with key metrics (queries, users, red flags)
• Tool usage statistics with detailed breakdowns
• Tenant activity heatmap showing query patterns over time
• Per-tool usage trends with visual bar charts
• Access: All roles can view analytics (viewer, editor, admin, owner)

Admin Rules Page (/admin-rules)

• Rule management with bulk upload and individual rule deletion
• File upload support for TXT, PDF, DOC, DOCX, MD files with drag-and-drop
• LLM-Guided Rule Explanations:
  • Automatic generation of human-readable explanations
  • Concrete examples of what would trigger the rule
  • Missing pattern suggestions for rule improvement
  • Edge cases and improvements identified by LLM
  • Intelligent fallback: When LLM times out, uses keyword extraction to generate useful explanations, examples, and suggestions
• Expandable explanations with "Explain" button for each rule
• Auto-expand for newly added rules with explanations
• Role-based access: Requires Admin or Owner role to manage rules
• Real-time updates with refresh functionality

Components

• chat-panel.tsx - Real-time chat interface with streaming responses and visualization integration
• analytics-panel.tsx - Analytics dashboard with metrics visualization
• knowledge-base-panel.tsx - Document search and ingestion component
• ingestion-card.tsx - Quick document upload card
• hero.tsx - Landing page hero section
• feature-grid.tsx - Feature showcase grid
• footer.tsx - Footer component
• reasoning-visualizer.tsx - Real-time reasoning path visualizer component
• tool-timeline.tsx - Tool invocation timeline component
• tenant-heatmap.tsx - Tenant activity heatmap component
• rule-explanation.tsx - LLM-generated rule explanation component with examples and pattern suggestions
• admin-rules-panel.tsx - Admin rules management panel component

Deploy

Deploy like any Next.js app (Vercel, Docker, etc.). Ensure the backend endpoints are reachable from the browser and CORS is enabled (already configured in backend/api/main.py).

Note: Make sure Celery workers are running in production for document ingestion and analytics processing to work properly.