livegraphs-django/README.md

Chat Analytics Dashboard

A Django application that creates an analytics dashboard for chat session data. The application allows different companies to have their own dashboards and view their own data.

Features

• Multi-company support with user authentication
• CSV file upload and processing
• Interactive dashboard with charts and visualizations
• Detailed data views for chat sessions
• Search functionality to find specific chat sessions
• Admin interface for managing users and companies
• Responsive design using Bootstrap 5

Requirements

• Python 3.13+
• Django 5.2+
• UV package manager (recommended)
• Other dependencies listed in pyproject.toml

Setup

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd LiveGraphsDjango
   

2. Install uv if you don't have it yet:

   # Install using pip
   pip install uv
   
   # Or with curl (Unix/macOS)
   curl -sSf https://install.pypa.io/get-uv.py | python3 -
   
   # Or on Windows with PowerShell
   irm https://install.pypa.io/get-uv.ps1 | iex
   

3. Create a virtual environment and activate it:

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install dependencies:

   # Install all dependencies including dev dependencies
   uv pip install -e ".[dev]"
   
   # Or just runtime dependencies
   uv pip install -e .
   

5. Run migrations:

   cd dashboard_project
   python manage.py makemigrations
   python manage.py migrate
   

6. Create a superuser:

   python manage.py createsuperuser
   

7. Set up environment variables:

   # Copy the sample .env file
   cp .env.sample .env
   
   # Edit the .env file with your credentials
   nano .env
   

   Be sure to update:

   • EXTERNAL_API_USERNAME and EXTERNAL_API_PASSWORD for the data integration API
   • DJANGO_SECRET_KEY for production environments
   • Redis URL if using a different configuration for Celery

8. Start Celery for background tasks:

   # In a separate terminal
   cd dashboard_project
   celery -A dashboard_project worker --loglevel=info
   
   # Start the Celery Beat scheduler in another terminal
   cd dashboard_project
   celery -A dashboard_project beat --scheduler django_celery_beat.schedulers:DatabaseScheduler
   

   Alternative without Redis (using SQLite):

   # Set environment variables to use SQLite instead of Redis
   export CELERY_BROKER_URL=sqla+sqlite:///celery.sqlite
   export CELERY_RESULT_BACKEND=db+sqlite:///results.sqlite
   
   # In a separate terminal
   cd dashboard_project
   celery -A dashboard_project worker --loglevel=info
   
   # Start the Celery Beat scheduler in another terminal with the same env vars
   cd dashboard_project
   celery -A dashboard_project beat --scheduler django_celery_beat.schedulers:DatabaseScheduler
   

9. Run the development server:

   python manage.py runserver
   

10. Access the application at http://127.0.0.1:8000/

Development Workflow with UV

UV offers several advantages over traditional pip, including faster dependency resolution and installation:

1. Running linting and formatting:

   # Using the convenience script
   ./.scripts/lint.sh
   
   # Or directly
   uv run -m ruff check dashboard_project
   uv run -m ruff format dashboard_project
   uv run -m black dashboard_project
   

2. Running tests:

   # Using the convenience script
   ./.scripts/test.sh
   
   # Or directly
   uv run -m pytest
   

3. Adding new dependencies:

   # Add to project
   uv pip install package_name
   
   # Then update pyproject.toml manually
   # And update the lockfile
   uv pip freeze > requirements.lock
   

4. Updating the lockfile:

   uv pip compile pyproject.toml -o uv.lock
   

Using Docker

1. Clone the repository:

   git clone <repository-url>
   cd dashboard_project
   

2. Build and run with Docker Compose:

   docker-compose up -d --build
   

3. Create a superuser:

   docker-compose exec web python manage.py createsuperuser
   

4. Access the application at http://localhost/

Usage

1. Login as the superuser you created.
2. Go to the admin interface (http://localhost/admin/) and create companies and users.
3. Assign users to companies.
4. Upload CSV files for each company.
5. View the analytics dashboard.

CSV File Format

The CSV file should contain the following columns:

Column	Description
session_id	Unique identifier for the chat session
start_time	When the session started (datetime)
end_time	When the session ended (datetime)
ip_address	IP address of the user
country	Country of the user
language	Language used in the conversation
messages_sent	Number of messages in the conversation (integer)
sentiment	Sentiment analysis of the conversation (string)
escalated	Whether the conversation was escalated (boolean)
forwarded_hr	Whether the conversation was forwarded to HR (boolean)
full_transcript	Full transcript of the conversation (text)
avg_response_time	Average response time in seconds (float)
tokens	Total number of tokens used (integer)
tokens_eur	Cost of tokens in EUR (float)
category	Category of the conversation (string)
initial_msg	First message from the user (text)
user_rating	User rating of the conversation (string)

Future Enhancements

• API integration for real-time data
• More advanced visualizations
• Custom reports
• Export functionality
• Theme customization
• User access control with more granular permissions

License

This project is unlicensed. Usage is restricted to personal and educational purposes only. For commercial use, please contact the author.