c3560b43fd
- Added documentation for audit tracking (IP address, invocation method). - Updated database model descriptions for enhanced WorkOrder and Conversation fields. - Documented the new UnifiedConfig system. - Reflected enhanced logging transparency for knowledge base parsing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
89 lines
3.4 KiB
Markdown
89 lines
3.4 KiB
Markdown
# 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`
|