baic_dashboard/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Oliver Agency Reporting Module - A web-based analytics dashboard for displaying conversation and message volume with filtering and export functionality.

Architecture

Full-stack application with separated backend and frontend:

• Backend: Python Flask API (/backend/app.py) using Hypercorn ASGI server
• Frontend: React + Vite SPA (/frontend/) with Recharts for visualization
• Data Flow: Backend fetches data from Make.com webhook → processes conversations and messages → enriches messages with conversation metadata → serves via REST API

Key architectural patterns:

• Messages are enriched with parent conversation data (User_ID, Assistant_ID, Brand_Voice_Setting)
• Assistant IDs are mapped to friendly display names via assistantMapping.js
• Filtering happens client-side after data fetch
• CSV export uses PapaParse library

Setup

Environment Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env and configure the following:

   • DOMAIN: Your deployment domain
   • BASE_PATH: Your application path (keep /dashboard/ or change as needed)
   • AZURE_TENANT_ID: Your Azure AD tenant ID (from Azure portal)
   • AZURE_CLIENT_ID: Your Azure AD application ID (from Azure portal)
   • MAKE_WEBHOOK_URL: Your Make.com webhook URL
   • Duplicate the above values to their VITE_ prefixed equivalents

3. Register your Azure AD application:

   • Go to Azure Portal > Azure Active Directory > App registrations
   • Create a new registration or update an existing one
   • Add redirect URIs for your domain (e.g., https://yourdomain.com/dashboard/)
   • Note the Tenant ID and Client ID for your .env file

Development Commands

Full Application

# Start both backend and frontend simultaneously (loads .env automatically)
./run.sh

Backend (Flask + Hypercorn)

cd backend
python app.py                    # Starts on http://localhost:5001

Frontend (React + Vite)

cd frontend
npm install                      # Install dependencies
npm run dev                      # Start dev server on http://localhost:5173
npm run build                    # Build for production
npm run lint                     # Run ESLint
npm run preview                  # Preview production build

Data Structure

Conversations: Contains metadata including User_ID, Assistant_ID, Brand Voice Setting, start/end times Messages: Individual messages enriched with parent conversation data for filtering

Critical data relationships:

• Messages linked to conversations via Conversation_ID
• Assistant_ID propagation from conversations to messages is essential for filtering
• Missing Assistant_ID entries are logged as warnings

Key Components

• Dashboard.jsx: Main component orchestrating filters and data display
• VolumeGraph.jsx: Recharts-based time series visualization
• FilterPanel.jsx: User/Assistant/Brand filtering controls
• ExportButton.jsx: CSV export functionality using PapaParse
• api.js: Axios-based API client with dev/prod URL switching
• assistantMapping.js: Maps Assistant IDs to friendly display names

Environment Configuration

The application is configured using environment variables defined in a .env file at the project root. Copy .env.example to .env and configure for your deployment.

Required Environment Variables:

Domain & Path:

• DOMAIN: Your deployment domain (e.g., yourdomain.com)
• BASE_PATH: Base path for the application (e.g., /dashboard/)

Azure AD Configuration:

• AZURE_TENANT_ID: Azure AD tenant identifier
• AZURE_CLIENT_ID: Azure AD application (client) identifier

Backend Configuration:

• BACKEND_PORT: Port for the backend server (default: 5001)
• MAKE_WEBHOOK_URL: Make.com webhook endpoint for data source

Frontend Configuration (Vite):

• VITE_DOMAIN: Same as DOMAIN (for frontend build)
• VITE_BASE_PATH: Same as BASE_PATH (for frontend build)
• VITE_AZURE_TENANT_ID: Same as AZURE_TENANT_ID (for frontend auth)
• VITE_AZURE_CLIENT_ID: Same as AZURE_CLIENT_ID (for frontend auth)

API URLs (constructed from environment variables):

• Development: http://localhost:{BACKEND_PORT}/api
• Production: https://{DOMAIN}{BASE_PATH}back/api

Authentication

Azure AD (MSAL) Configuration:

Frontend Authentication:

• Uses @azure/msal-react and @azure/msal-browser
• Authentication state managed by useIsAuthenticated() hook
• Login/logout components with popup authentication flow
• Access tokens automatically included in API requests

Backend Authentication:

• JWT token validation using PyJWT library
• Fetches Microsoft public keys from JWKS endpoint
• @require_auth decorator protects API endpoints
• Validates token signature, audience, and issuer

API Endpoints

• GET /api/data: Returns processed conversations and enriched messages (requires authentication)

The backend handles data enrichment, validation, and filtering of deleted conversations before serving to the frontend.