livegraphs-django/QUICK_START_GUIDE.md

Chat Analytics Dashboard: Quick Start Guide

Getting Started

This guide will help you quickly set up and start using the Chat Analytics Dashboard.

Installation

Option 1: Local Development

1. Clone the repository:

   git clone <repository-url>
   cd dashboard_project
   

2. Set up a virtual environment:

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

3. Install dependencies: # from pyproject.toml

   uv pip install -r requirements.txt
   

4. Set up the database:

   python manage.py migrate
   

5. Create admin user:

   python manage.py createsuperuser
   

6. Start the development server:

   python manage.py runserver
   

7. Access the application: Open your browser and go to http://127.0.0.1:8000/

Option 2: Docker Deployment

1. Clone the repository:

   git clone <repository-url>
   cd dashboard_project
   

2. Build and start the containers:

   docker-compose up -d --build
   

3. Create admin user:

   docker-compose exec web python manage.py createsuperuser
   

4. Access the application: Open your browser and go to http://localhost/

Creating Sample Data (Optional)

To quickly populate the system with sample data:

python manage.py create_sample_data

This will create:

• Admin user (username: admin, password: admin123)
• Three companies with users
• Sample chat data and dashboards

Basic Usage

Admin Tasks

1. Access Admin Panel:

   • Go to http://localhost/admin/
   • Login with your admin credentials

2. Create a Company:

   • Go to Companies > Add Company
   • Fill in the company details and save

3. Create Users:

   • Go to Users > Add User
   • Fill in user details
   • Assign the user to a company
   • Set appropriate permissions (staff status, company admin)

Company Admin Tasks

1. Login to Dashboard:

   • Go to http://localhost/
   • Login with your company admin credentials

2. Upload Chat Data:

   • Click on "Upload Data" in the sidebar
   • Fill in the data source details
   • Select a CSV file containing chat data
   • Click "Upload"

3. Create a Dashboard:

   • Click on "New Dashboard" in the sidebar
   • Fill in the dashboard details
   • Select data sources to include
   • Click "Create Dashboard"

Regular User Tasks

1. View Dashboard:

   • Login with your user credentials
   • The dashboard will show automatically
   • Select different dashboards from the sidebar

2. Search Chat Sessions:

   • Click on "Search" in the top navigation
   • Enter search terms
   • Use filters to refine results

3. View Session Details:

   • In search results, click the eye icon for a session
   • View complete session information and transcript

CSV Format

Your CSV files should include the following columns:

Column	Description	Type
session_id	Unique ID for the chat	String
start_time	Session start time	Datetime
end_time	Session end time	Datetime
ip_address	User's IP address	String
country	User's country	String
language	Chat language	String
messages_sent	Number of messages	Integer
sentiment	Sentiment analysis result	String
escalated	Whether chat was escalated	Boolean
forwarded_hr	Whether chat was sent to HR	Boolean
full_transcript	Complete chat text	Text
avg_response_time	Average response time (seconds)	Float
tokens	Number of tokens used	Integer
tokens_eur	Cost in EUR	Float
category	Chat category	String
initial_msg	First user message	Text
user_rating	User satisfaction rating	String

Example CSV row:

acme_1,2023-05-01 10:30:00,2023-05-01 10:45:00,192.168.1.1,USA,English,10,Positive,FALSE,FALSE,"User: Hello\nAgent: Hi there!",2.5,500,0.01,Support,Hello I need help,Good

Dashboard Features

Overview Panel

The main dashboard shows:

• Total chat sessions
• Average response time
• Total tokens used
• Total cost

Charts

The dashboard includes:

• Sessions Over Time: Line chart showing chat volume trends
• Sentiment Analysis: Pie chart of positive/negative/neutral chats
• Top Countries: Bar chart of user countries
• Categories: Distribution of chat categories

Data Source Details

View details for each data source:

• Upload date and time
• Total sessions
• Source description
• List of all chat sessions from the source

Session Details

For each chat session, you can view:

• Session metadata (time, location, etc.)
• Full chat transcript
• Performance metrics
• User sentiment and rating

Troubleshooting

CSV Upload Issues

If your CSV upload fails:

• Ensure all required columns are present
• Check date formats (should be YYYY-MM-DD HH:MM:SS)
• Verify boolean values (TRUE/FALSE, Yes/No, 1/0)
• Check for special characters in text fields

Access Issues

If you can't access certain features:

• Verify your user role (admin, company admin, or regular user)
• Ensure you're assigned to the correct company
• Check if you're trying to access another company's data

Empty Dashboard

If your dashboard is empty:

• Verify that data sources have been uploaded
• Check that the dashboard is configured to use those data sources
• Ensure the CSV was processed successfully

Getting Help

If you encounter any issues:

• Check the documentation
• Contact your system administrator
• File an issue in the project repository