CLAUDE.md - Beyond CX Analytics

Project Overview

Beyond CX Analytics is a Contact Center Analytics Platform that analyzes operational data and provides AI-assisted insights. The application processes CSV data from contact centers to generate volumetry analysis, performance metrics, CSAT scores, economic models, and automation readiness scoring.

Tech Stack

Frontend: React 19 + TypeScript + Vite Backend: Python 3.11 + FastAPI Infrastructure: Docker Compose + Nginx Charts: Recharts UI Components: Radix UI + Lucide React Data Processing: Pandas, NumPy AI Integration: OpenAI API

Project Structure

BeyondCXAnalytics_Demo/
├── backend/
│   ├── beyond_api/        # FastAPI REST API
│   ├── beyond_metrics/    # Core metrics calculation library
│   ├── beyond_flows/      # AI agents and scoring engines
│   └── tests/             # pytest test suite
├── frontend/
│   ├── components/        # React components
│   ├── utils/             # Utility functions and API client
│   └── styles/            # CSS and color definitions
├── nginx/                 # Reverse proxy configuration
└── docker-compose.yml     # Service orchestration

Common Commands

Frontend

cd frontend
npm install              # Install dependencies
npm run dev              # Start dev server (port 3000)
npm run build            # Production build
npm run preview          # Preview production build

Backend

cd backend
pip install .            # Install from pyproject.toml
python -m pytest tests/  # Run tests
uvicorn beyond_api.main:app --reload  # Start dev server

Docker

docker compose build     # Build all services
docker compose up -d     # Start all services
docker compose down      # Stop all services
docker compose logs -f   # Stream logs

Deployment

./deploy.sh              # Redeploy containers
sudo ./install_beyond.sh # Full server installation

Key Entry Points

Component	File
Frontend App	`frontend/App.tsx`
Backend API	`backend/beyond_api/main.py`
Main Endpoint	`POST /analysis`
Metrics Engine	`backend/beyond_metrics/agent.py`
AI Agents	`backend/beyond_flows/agents/`

Architecture

4 Analytics Dimensions: Volumetry, Operational Performance, Satisfaction/Experience, Economy/Cost
Data Flow: CSV Upload → FastAPI → Metrics Pipeline → AI Agents → JSON Response → React Dashboard
Authentication: Basic Auth middleware

Code Style Notes

Documentation and comments are in Spanish
Follow existing patterns when adding new components
Frontend uses functional components with hooks
Backend follows FastAPI conventions with Pydantic models

Git Workflow

Main branch: main
Development branch: desarrollo
Create feature branches from desarrollo

Environment Variables

Backend expects:

OPENAI_API_KEY - For AI-powered analysis
BASIC_AUTH_USER / BASIC_AUTH_PASS - API authentication

Frontend expects:

VITE_API_BASE_URL - API endpoint (default: /api)

3.1 KiB Raw Blame History