# Frontend Architecture Guide

**Last Updated**: 2026-06-29  
**Change Log**:
- 2026-06-29: Initial version generated after cloning the repository.

---

## 🎯 Overview

The frontend is a multi-tenant React application bundled with **Vite** and styled using **Tailwind CSS**. It serves as the visual analytics dashboard for businesses to monitor call quality metrics, BANT parameters, lead profiles, speaker timelines, and customer onboarding. It also supports seamless iframe embedding.

---

## 📁 File Structure Map

```
dashboard-frontend/
├── index.html
├── vite.config.js
├── tailwind.config.js
├── src/
│   ├── main.jsx                 # Application entry point
│   ├── App.jsx                  # Main router, navigation layout, and global states
│   ├── App.css
│   ├── index.css                # Base Tailwind styles and customized UI classes
│   ├── components/              # Reusable UI components
│   │   ├── Dashboard.jsx        # Main analytics overview dashboard (large container)
│   │   ├── McubeAiPanel.jsx     # Side panel interface for RAG-driven AI assistant
│   │   ├── SpeakerSegments.jsx  # Display of conversation turns (Speaker 1, Speaker 2)
│   │   ├── TimelineVisualization.jsx # Talk/Listen ratio timeline visualizer
│   │   ├── SupportTicketsPanel.jsx   # Support and ticket tracking panel
│   │   └── ...                  # Reusable widgets (BantQualificationCard, IntentChart, etc.)
│   ├── pages/                   # Main page views
│   │   ├── Login.jsx            # Sign-in page (multi-tenant mapping)
│   │   ├── CallDetail.jsx       # Exhaustive transcript, timeline, and AI agent analysis view
│   │   ├── LeadsList.jsx        # Table of synchronized CRM leads and activity indicators
│   │   ├── LeadDetail.jsx       # Detailed profile, timeline, and insights for a specific lead
│   │   ├── Settings.jsx         # Custom brand configurations, rules, and scoring parameters
│   │   ├── Agents.jsx           # Team/agent performance leaderboard and insights
│   │   ├── CustomerOnboarding.jsx    # Step-by-step business setup wizard
│   │   ├── PCAMasterPanel.jsx   # Admin portal for support and multi-tenant management
│   │   └── embed/               # Chromeless views for iframe integrations
│   ├── services/
│   │   └── api.js               # Centralized Axios client for backend API communication
│   └── utils/                   # Helper functions (Auth, Session, RBAC, Embed, Multi-Bid)
```

---

## 🧭 Routing & Navigation

- **Router**: React Router (`HashRouter` as `Router` in `App.jsx`).
- **Main Layout**: Navigation sidebar (Lucide icons) on the left, top navbar with tenant context/user actions, and a main contents container.
- **Embed Mode**: Detects if url has `?embed=true` or hash contains `/embed/`. If so, uses a chromeless layout (hiding sidebar and headers) via `EmbedShell.jsx` for native-like rendering within external CRMs (like LeadSquared).
- **RBAC**: Handled in `src/utils/rbac.js`. Restricts tabs/pages based on roles:
  - `SuperMaster` / `SupportStaff` can access `PCAMasterPanel`.
  - Business Admins can manage settings and agents.
  - Standard Users are restricted to dashboards and leads.

---

## 🔄 Component Hierarchy & Data Flow

```mermaid
graph TD
    App[App.jsx] --> Router[HashRouter]
    Router --> Dashboard[components/Dashboard.jsx]
    Router --> CallDetail[pages/CallDetail.jsx]
    Router --> LeadsList[pages/LeadsList.jsx]
    Router --> LeadDetail[pages/LeadDetail.jsx]
    Router --> SettingsPage[pages/Settings.jsx]
    Router --> PCAMasterPanel[pages/PCAMasterPanel.jsx]
    Router --> Onboarding[pages/CustomerOnboarding.jsx]

    CallDetail --> TimelineVisualization[components/TimelineVisualization.jsx]
    CallDetail --> SpeakerSegments[components/SpeakerSegments.jsx]
    CallDetail --> BantCard[components/BantQualificationCard.jsx]
    CallDetail --> ScoreRing[components/ScoreRing.jsx]

    Dashboard --> RecentCalls[components/RecentCalls.jsx]
    Dashboard --> SentimentChart[components/SentimentChart.jsx]
    Dashboard --> IntentChart[components/IntentChart.jsx]

    App --> McubeAiPanel[components/McubeAiPanel.jsx]
```

---

## ⚡ Rendering & Lifecycle Decisions

1. **Client-Side Rendering (CSR)**: The application is fully client-side rendered. It dynamically fetches all analytics datasets from the backend APIs on route change.
2. **Context & Local Storage Persistence**:
   - Authentication tokens, business IDs (`bid`), and user permissions are kept in LocalStorage (see `authSession.js` & `sessionReconcile.js`).
   - Multiple `bid` identities are supported for multi-tenant users.
3. **Optimized Rerendering**: Charts (using Recharts or similar library) and large call lists use pagination and filters stored in LocalStorage to preserve state during details navigation.

---

## 🔌 API Call Integration Patterns

All communications route through the `src/services/api.js` Axios wrapper:
- Attaches the JWT authorization header on every request automatically.
- Translates API host addresses based on the environment config.
- **Core Endpoints**:
  - `GET /calls/{bid}`: Fetch paginated call analysis list.
  - `GET /calls/{bid}/{callid}`: Exhaustive details for a call (transcripts, speaker timelines, quality checks).
  - `POST /auth/login`: Authenticate and load the tenant's permissions.
  - `POST /rag/{bid}/query`: Ask the vector database RAG assistant questions in the sidebar panel.