update the readme file

README.md

@@ -102,6 +102,7 @@ Then access:
   - Per-tenant query volume and active users
   - Red-flag violations with timestamps and confidence scores
   - LLM token logs and latency metrics
+  - **Real-Time Visualizations**: Reasoning path visualizer, tool invocation timeline, and tenant activity heatmap
 - 🌐 **Live Web Search** – Google Programmable Search (Custom Search API) with tenant-aware MCP tooling
 - 🏢 **Multi-Tenant Isolation** – Complete tenant isolation with centralized tenant ID management; backend enforces strict isolation for chat, ingestion, and admin ops
 - 🔐 **Fine-Grained Role-Based Access Control (RBAC)** – Four-tier role system (viewer, editor, admin, owner) with dynamic UI visibility and backend permission enforcement; frontend automatically shows/hides features based on role
@@ -121,6 +122,10 @@ Then access:
 - 🧠 **Agent Debug & Planning** – `/agent/debug` and `/agent/plan` endpoints for observability and tool selection inspection
 - 💾 **Persistent Analytics Storage** – Supabase-backed analytics store (with automatic SQLite fallback) for fast, multi-tenant queries
 - 🗄️ **Supabase Integration** – Production-ready Supabase support for admin rules with automatic table creation
+- 📈 **Real-Time Visualization Components** – Interactive visualizations for agent reasoning, tool execution, and tenant activity:
+  - **Reasoning Path Visualizer**: Step-by-step visualization of agent decision-making with animated progression
+  - **Tool Invocation Timeline**: Visual timeline showing tool execution order, latency, and result counts
+  - **Tenant Activity Heatmap**: Query activity heatmap and per-tool usage trends over time
 
 ### Conversation Memory System
 
@@ -189,7 +194,7 @@ The system supports four roles with increasing privileges:
 | Chat Bot | ✅ | ✅ | ✅ | ✅ |
 | Ingest Documents | ❌ | ✅ | ✅ | ✅ |
 | Delete Documents | ❌ | ❌ | ✅ | ✅ |
-| View Analytics | ❌ | ❌ | ✅ | ✅ |
+| View Analytics | ✅ | ✅ | ✅ | ✅ |
 | Manage Rules | ❌ | ❌ | ✅ | ✅ |
 
 ### Backend RBAC
@@ -210,7 +215,7 @@ PERMISSIONS = {
 - `/admin/rules` - Requires `admin` or `owner` role
 - `/rag/ingest*` - Requires `editor`, `admin`, or `owner` role
 - `/rag/delete*` - Requires `admin` or `owner` role
-- `/analytics/*` - Requires `admin` or `owner` role
+- `/analytics/*` - All roles can view (viewer, editor, admin, owner)
 
 **Example Request:**
 ```bash
@@ -241,7 +246,7 @@ The frontend UI dynamically shows/hides features based on the selected role:
 
 **Protected Routes:**
 - `/ingestion` - Editor, Admin, Owner only
-- `/analytics` - Admin, Owner only
+- `/analytics` - All roles can view (viewer, editor, admin, owner)
 - `/admin-rules` - Admin, Owner only
 
 **Implementation:**
@@ -260,6 +265,50 @@ The frontend UI dynamically shows/hides features based on the selected role:
 
 ---
 
+## Real-Time Visualization Features
+
+IntegraChat includes three powerful visualization components that provide real-time insights into agent behavior and system activity:
+
+### 1. Reasoning Path Visualizer
+- **What it shows**: Step-by-step visualization of how the agent makes decisions
+- **Features**:
+  - Animated progression through reasoning steps
+  - Status indicators (pending, running, completed, error)
+  - Detailed metrics per step (latency, hit counts, token estimates)
+  - Visual icons for each step type
+- **Where to find it**: 
+  - Next.js frontend: Chat panel (expand "Visualizations" section)
+  - Gradio app: Debug & Reasoning tab
+- **Data source**: `reasoning_trace` from agent responses
+
+### 2. Tool Invocation Timeline
+- **What it shows**: Visual timeline of all tool executions during an agent interaction
+- **Features**:
+  - Color-coded bars showing tool status (success/error)
+  - Latency visualization per tool
+  - Result count badges
+  - Summary statistics (total tools, total time, average latency)
+- **Where to find it**: 
+  - Next.js frontend: Chat panel (expand "Visualizations" section)
+  - Gradio app: Debug & Reasoning tab
+- **Data source**: `tool_traces` from agent responses
+
+### 3. Tenant Activity Heatmap
+- **What it shows**: Query activity patterns and tool usage trends over time
+- **Features**:
+  - Hour-by-hour, day-by-day activity heatmap
+  - Color intensity based on activity level
+  - Per-tool usage trends with bar charts
+  - Trend indicators (up/down/stable)
+- **Where to find it**: 
+  - Next.js frontend: Analytics page (`/analytics`)
+  - Configurable time window (default: 7 days)
+- **Data source**: `/analytics/activity` and `/analytics/tool-usage` endpoints
+
+**Access**: All visualization features are available to all roles (viewer, editor, admin, owner).
+
+---
+
 ## Installation & Setup
 
 ### Prerequisites
@@ -477,6 +526,45 @@ All endpoints are served by the FastAPI backend at `http://localhost:8000`. Most
 | `GET` | `/analytics/activity?days=30` | Tenant activity summary: queries, active users, last query timestamp |
 | `GET` | `/analytics/rag-quality?days=30` | RAG quality metrics: avg hits, scores, latency (recall/precision indicators) |
 
+### Visualization Features
+
+IntegraChat includes three powerful visualization components that provide real-time insights into agent behavior and system activity:
+
+#### 1. Real-Time Reasoning Visualizer
+- **Location**: Chat panel (Next.js frontend) and Debug tab (Gradio app)
+- **Features**:
+  - Step-by-step visualization of agent reasoning path
+  - Animated progression through reasoning steps
+  - Status indicators (pending, running, completed, error)
+  - Detailed metrics per step (latency, hit counts, token estimates)
+  - Visual icons for each step type (admin rules check, RAG prefetch, tool selection, etc.)
+- **Data Source**: `reasoning_trace` from `/agent/message` or `/agent/debug` endpoints
+- **Usage**: Automatically appears in chat panel when agent responses include reasoning traces
+
+#### 2. Tool Invocation Timeline
+- **Location**: Chat panel (Next.js frontend) and Debug tab (Gradio app)
+- **Features**:
+  - Visual timeline showing tool execution order
+  - Color-coded bars indicating tool status (success/error)
+  - Latency visualization per tool
+  - Result count badges
+  - Summary statistics (total tools, total time, average latency)
+- **Data Source**: `tool_traces` from `/agent/message` or `/agent/debug` endpoints
+- **Usage**: Automatically appears in chat panel when agent responses include tool traces
+
+#### 3. Live Tenant Heatmap
+- **Location**: Analytics page (`/analytics`)
+- **Features**:
+  - Query activity heatmap (hour-by-hour, day-by-day visualization)
+  - Color intensity based on activity level
+  - Per-tool usage trends with bar charts
+  - Trend indicators (up/down/stable)
+  - Configurable time window (default: 7 days)
+- **Data Source**: `/analytics/activity` and `/analytics/tool-usage` endpoints
+- **Usage**: Navigate to Analytics page to view tenant activity patterns
+
+**Access**: All visualization features are available to all roles (viewer, editor, admin, owner).
+
 ### Request Headers
 
 Most endpoints require:

backend/README.md

@@ -147,6 +147,13 @@ Use the helper scripts in the repo root when validating backend changes:
   - Detailed tool usage table with performance metrics
   - Formatted summary with dark theme styling
   - Real-time data fetching and visualization
+  - **Access**: All roles can view analytics (viewer, editor, admin, owner)
+
+- **Debug & Reasoning Tab**:
+  - Reasoning trace analyzer showing step-by-step agent decision-making
+  - Tool invocation timeline with latency visualization
+  - Formatted markdown output with detailed metrics
+  - Uses `/agent/debug` endpoint for comprehensive insights
 
 - **Modern UI/UX**:
   - Dark theme with white text for better readability
@@ -154,6 +161,16 @@ Use the helper scripts in the repo root when validating backend changes:
   - Improved error handling and status messages
   - Responsive layout with proper component scaling
 
+### Real-Time Visualization Components (Next.js Frontend)
+
+The Next.js frontend includes three powerful visualization components:
+
+- **Reasoning Path Visualizer**: Step-by-step visualization of agent reasoning with animated progression, status indicators, and detailed metrics. Integrated into chat panel.
+- **Tool Invocation Timeline**: Visual timeline showing tool execution order, latency, and result counts. Integrated into chat panel.
+- **Tenant Activity Heatmap**: Query activity heatmap and per-tool usage trends. Integrated into analytics page.
+
+All visualizations are accessible to all roles and automatically populate when agent responses include `reasoning_trace` and `tool_traces` data.
+
 ## Environment Variables (excerpt)
 
 Defined in `env.example`:

frontend/README.md

@@ -36,16 +36,38 @@ NEXT_PUBLIC_API_URL=http://localhost:8000
 - 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
+- **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
@@ -61,15 +83,25 @@ NEXT_PUBLIC_API_URL=http://localhost:8000
   - 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)
+
 ### Components
 
-- `chat-panel.tsx` - Real-time chat interface with streaming responses
+- `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
 
 ## Deploy