# CLAUDE.md

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

## High-Level Architecture

This project is a Python Flask-based web application called "TSP Assistant". It's an intelligent customer service system designed for Telematics Service Providers (TSP).

The backend is built with Flask and utilizes a modular structure with Blueprints. The core application logic resides in the `src/` directory.

Key components of the architecture include:

*   **Web Framework**: The web interface and APIs are built using **Flask**. The main Flask app is likely configured in `src/web/app.py`.
*   **Modular Routing**: The application uses Flask **Blueprints** for organizing routes. These are located in `src/web/blueprints/`. Each file in this directory corresponds to a feature area (e.g., `agent.py`, `workorders.py`, `analytics.py`).
*   **Intelligent Agent**: A core feature is the AI agent. Its logic is contained within the `src/agent/` directory, which includes components for planning (`planner.py`), tool management (`tool_manager.py`), and execution (`executor.py`).
*   **Database**: The application uses a relational database (likely MySQL) with **SQLAlchemy** as the ORM. Models are defined in `src/core/models.py`.
*   **Configuration**: A unified configuration center (`src/config/unified_config.py`) manages all settings via environment variables and `.env` files.
*   **Real-time Communication**: **WebSockets** are used for real-time features like the intelligent chat. The server logic is in `src/web/websocket_server.py`.
*   **Data Analytics**: The system has a dedicated data analysis module located in `src/analytics/`.
*   **Frontend**: The frontend is built with Bootstrap 5, Chart.js, and vanilla JavaScript (ES6+). Frontend assets are in `src/web/static/` and templates are in `src/web/templates/`.

## Common Commands

### Environment Setup

The project can be run using Docker (recommended) or locally.

**1. Install Dependencies:**
```bash
pip install -r requirements.txt
```

**2. Initialize the Database:**
This script sets up the necessary database tables.
```bash
python init_database.py
```

### Running the Application

**Local Development:**
To start the Flask development server:
```bash
python start_dashboard.py
```
The application will be available at `http://localhost:5000`.

**Docker Deployment:**
The project includes a `docker-compose.yml` for easy setup of all services (application, database, cache, monitoring).

To start all services:
```bash
docker-compose up -d
```
Or use the provided script:
```bash
chmod +x scripts/docker_deploy.sh
./scripts/docker_deploy.sh start
```

To stop services:
```bash
./scripts/docker_deploy.sh stop
```

### Running Tests

The project uses `pytest` for testing.
```bash
pytest
```
To run tests with coverage:
```bash
pytest --cov
```

## Key File Locations

*   **Main Application Entry Point**: `start_dashboard.py` (local) or `src/web/app.py` (via WSGI in production).
*   **Flask Blueprints (Routes)**: `src/web/blueprints/`
*   **Agent Core Logic**: `src/agent/`
*   **Database Models**: `src/core/models.py`
*   **Frontend Static Assets**: `src/web/static/` (JS, CSS, images)
*   **Frontend HTML Templates**: `src/web/templates/`
*   **WebSocket Server**: `src/web/websocket_server.py`
*   **Configuration Files**: `config/`
*   **Deployment Scripts**: `scripts/`
*   **Database Initialization**: `init_database.py`