kjanat/livegraphs-django
1
0
Fork 0
mirror of https://github.com/kjanat/livegraphs-django.git synced 2026-02-13 15:15:43 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

fix: configure markdownlint-cli2 properly

Browse Source 
- Wrap config in 'config' key for markdownlint-cli2
- Use MD013 rule name instead of 'line-length' alias
- Disable MD013 line-length checks
- Add allowed languages: sh, python, csv, tree
- Fix broken link reference in TODO.md
- All markdown linting now passes (37 errors -> 0)
This commit is contained in:
Kaj Kowalski
2025-11-05 16:51:23 +01:00
parent 04705bdcb2
commit fe847a3d4e
9 changed files with 434 additions and 353 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
README.md
View File

@@ -1,49 +1,52 @@
# 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.
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.
## Project Overview
This Django project creates a multi-tenant dashboard application for analyzing chat session data. Companies can upload their chat data (in CSV format) and view analytics and metrics through an interactive dashboard. The application supports user authentication, role-based access control, and separate data isolation for different companies.
This Django project creates a multi-tenant dashboard application for analyzing chat session data. Companies can upload
their chat data (in CSV format) and view analytics and metrics through an interactive dashboard. The application
supports user authentication, role-based access control, and separate data isolation for different companies.
### Project Structure
The project consists of two main Django apps:
1. **accounts**: Handles user authentication, company management, and user roles
2. **dashboard**: Manages data sources, chat sessions, and dashboard visualization
3. **data_integration**: Handles external API data integration
1. **accounts**: Handles user authentication, company management, and user roles
2. **dashboard**: Manages data sources, chat sessions, and dashboard visualization
3. **data_integration**: Handles external API data integration
### Key Features
- **Multi-company Support**: Each company has their own private dashboards and data
- **User Management**: Different user roles (admin, company admin, regular user)
- **CSV File Upload**: Upload and process CSV files containing chat session data
- **Interactive Dashboard**: Visualize chat data with charts and metrics
- **Search Functionality**: Find specific chat sessions based on various criteria
- **Data Export**: Export data in CSV, JSON, and Excel formats
- **Data Exploration**: Drill down into individual chat sessions for detailed analysis
- **Responsive Design**: Mobile-friendly interface using Bootstrap 5
- **Multi-company Support**: Each company has their own private dashboards and data
- **User Management**: Different user roles (admin, company admin, regular user)
- **CSV File Upload**: Upload and process CSV files containing chat session data
- **Interactive Dashboard**: Visualize chat data with charts and metrics
- **Search Functionality**: Find specific chat sessions based on various criteria
- **Data Export**: Export data in CSV, JSON, and Excel formats
- **Data Exploration**: Drill down into individual chat sessions for detailed analysis
- **Responsive Design**: Mobile-friendly interface using Bootstrap 5
## Requirements
- Python 3.13+
- Django 5.2+
- UV package manager (recommended)
- Other dependencies listed in [`pyproject.toml`](./pyproject.toml)
- Python 3.13+
- Django 5.2+
- UV package manager (recommended)
- Other dependencies listed in [`pyproject.toml`](./pyproject.toml)
## Setup
### Local Development
1. Clone the repository:
1. Clone the repository:
```sh
git clone <repository-url>
cd LiveGraphsDjango
git clone https://github.com/kjanat/livegraphs-django.git
cd livegraphs-django
```
2. Install uv if you don't have it yet:
2. Install uv if you don't have it yet:
```sh
# Install using pip
@@ -56,14 +59,14 @@ The project consists of two main Django apps:
irm https://install.pypa.io/get-uv.ps1 | iex
```
3. Create a virtual environment and activate it:
3. Create a virtual environment and activate it:
```sh
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
4. Install dependencies:
4. Install dependencies:
```sh
# Install all dependencies including dev dependencies
@@ -73,7 +76,7 @@ The project consists of two main Django apps:
uv pip install -e .
```
5. Run migrations:
5. Run migrations:
```sh
cd dashboard_project
@@ -81,13 +84,13 @@ The project consists of two main Django apps:
python manage.py migrate
```
6. Create a superuser:
6. Create a superuser:
```sh
python manage.py createsuperuser
```
7. Set up environment variables:
7. Set up environment variables:
```sh
# Copy the sample .env file
@@ -99,11 +102,11 @@ The project consists of two main Django apps:
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
- `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:
8. Start Celery for background tasks:
```sh
# In a separate terminal
@@ -115,7 +118,7 @@ The project consists of two main Django apps:
celery -A dashboard_project beat --scheduler django_celery_beat.schedulers:DatabaseScheduler
```
Alternative without Redis (using SQLite):
Alternative without Redis (using SQLite):
```sh
# Set environment variables to use SQLite instead of Redis
@@ -131,19 +134,19 @@ The project consists of two main Django apps:
celery -A dashboard_project beat --scheduler django_celery_beat.schedulers:DatabaseScheduler
```
9. Run the development server:
9. Run the development server:
```sh
python manage.py runserver
```
10. Access the application at <http://127.0.0.1:8000/>
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:
1. Running linting and formatting:
```sh
# Using the convenience script
@@ -155,7 +158,7 @@ UV offers several advantages over traditional pip, including faster dependency r
uv run -m black dashboard_project
```
2. Running tests:
2. Running tests:
```sh
# Using the convenience script
@@ -165,7 +168,7 @@ UV offers several advantages over traditional pip, including faster dependency r
uv run -m pytest
```
3. Adding new dependencies:
3. Adding new dependencies:
```sh
# Add to project
@@ -176,7 +179,7 @@ UV offers several advantages over traditional pip, including faster dependency r
uv pip freeze > requirements.lock
```
4. Updating the lockfile:
4. Updating the lockfile:
```sh
uv pip compile pyproject.toml -o uv.lock
@@ -184,40 +187,41 @@ UV offers several advantages over traditional pip, including faster dependency r
### Using Docker
1. Clone the repository:
1. Clone the repository:
```sh
git clone <repository-url>
cd dashboard_project
git clone https://github.com/kjanat/livegraphs-django.git
cd livegraphs-django
```
2. Build and run with Docker Compose:
2. Build and run with Docker Compose:
```sh
docker-compose up -d --build
```
3. Create a superuser:
3. Create a superuser:
```sh
docker-compose exec web python manage.py createsuperuser
```
```sh
docker-compose exec web python manage.py createsuperuser
```
4. Access the application at <http://localhost/>
4. Access the application at <http://localhost/>
## Development Tools
### Prettier for Django Templates
This project uses Prettier with the `prettier-plugin-django-annotations` plugin to format HTML templates with Django template syntax.
This project uses Prettier with the `prettier-plugin-django-annotations` plugin to format HTML templates with Django
template syntax.
#### Prettier Configuration
The project is already configured with Prettier integration in pre-commit hooks. The configuration includes:
1. `.prettierrc` - Configuration file with Django HTML support
2. `.prettierignore` - Files to exclude from formatting
3. Pre-commit hook for automatic formatting on commits
1. `.prettierrc` - Configuration file with Django HTML support
2. `.prettierignore` - Files to exclude from formatting
3. Pre-commit hook for automatic formatting on commits
#### Manual Installation
@@ -300,18 +304,18 @@ If you need to prevent Prettier from formatting a section of your template:
The `prettier-plugin-django-annotations` plugin provides special handling for Django templates, including:
- Proper formatting of Django template tags (`{% %}`)
- Support for Django template comments (`{# #}`)
- Preservation of Django template variable output (`{{ }}`)
- Special handling for Django template syntax inside HTML attributes
- Proper formatting of Django template tags (`{% %}`)
- Support for Django template comments (`{# #}`)
- Preservation of Django template variable output (`{{ }}`)
- Special handling for Django template syntax inside HTML attributes
## Basic Usage Instructions
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.
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.
## Quick Start Guide
@@ -325,83 +329,86 @@ python manage.py create_sample_data
This will create:
- Admin user (username: admin, password: admin123)
- Three companies with users
- Sample chat data and dashboards
- Admin user (username: admin, password: admin123)
- Three companies with users
- Sample chat data and dashboards
### Admin Tasks
1. **Access Admin Panel**:
1. **Access Admin Panel**:
- Go to <http://localhost/admin/>
- Login with your admin credentials
- Go to <http://localhost/admin/>
- Login with your admin credentials
2. **Create a Company**:
2. **Create a Company**:
- Go to Companies > Add Company
- Fill in the company details and save
- 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)
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**:
1. **Login to Dashboard**:
- Go to <http://localhost/>
- Login with your company admin credentials
- Go to <http://localhost/>
- Login with your company admin credentials
2. **Upload Chat Data**:
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"
- 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"
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**:
1. **View Dashboard**:
- Login with your user credentials
- The dashboard will show automatically
- Select different dashboards from the sidebar
- Login with your user credentials
- The dashboard will show automatically
- Select different dashboards from the sidebar
2. **Search Chat Sessions**:
2. **Search Chat Sessions**:
- Click on "Search" in the top navigation
- Enter search terms
- Use filters to refine results
- 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
3. **View Session Details**:
- In search results, click the eye icon for a session
- View complete session information and transcript
### Dashboard Features
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
- **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
- Upload date and time
- Total sessions
- Source description
- List of all chat sessions from the source
### Troubleshooting
@@ -409,33 +416,33 @@ View details for each data source:
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
- 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
- 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
- Verify that data sources have been uploaded
- Check that the dashboard is configured to use those data sources
- Ensure the CSV was processed successfully
## 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) |
@@ -464,150 +471,154 @@ acme_1,2023-05-01 10:30:00,2023-05-01 10:45:00,192.168.1.1,USA,English,10,Positi
### Core Features Implemented
1. **Multi-Tenant Architecture**:
1. **Multi-Tenant Architecture**:
- Companies have isolated data and user access
- Users belong to specific companies
- Role-based permissions (admin, company admin, regular user)
- Companies have isolated data and user access
- Users belong to specific companies
- Role-based permissions (admin, company admin, regular user)
2. **Data Management**:
2. **Data Management**:
- CSV file upload and processing
- Data source management
- Chat session records with comprehensive metadata
- CSV file upload and processing
- Data source management
- Chat session records with comprehensive metadata
3. **Dashboard Visualization**:
3. **Dashboard Visualization**:
- Interactive charts using Plotly.js
- Key metrics and KPIs
- Time-series analysis
- Geographic distribution
- Sentiment analysis
- Category distribution
- Interactive charts using Plotly.js
- Key metrics and KPIs
- Time-series analysis
- Geographic distribution
- Sentiment analysis
- Category distribution
4. **Search and Analysis**:
4. **Search and Analysis**:
- Full-text search across chat sessions
- Filtering by various attributes
- Detailed view of individual chat sessions
- Transcript viewing
- Full-text search across chat sessions
- Filtering by various attributes
- Detailed view of individual chat sessions
- Transcript viewing
5. **User Management**:
5. **User Management**:
- User registration and authentication
- Profile management
- Password change functionality
- Role assignment
- User registration and authentication
- Profile management
- Password change functionality
- Role assignment
6. **Admin Interface**:
6. **Admin Interface**:
- Company management
- User administration
- Data source oversight
- System-wide configuration
- Company management
- User administration
- Data source oversight
- System-wide configuration
7. **Responsive Design**:
- Mobile-friendly interface using Bootstrap 5
- Consistent layout and navigation
- Accessible UI components
7. **Responsive Design**:
- Mobile-friendly interface using Bootstrap 5
- Consistent layout and navigation
- Accessible UI components
### Technical Implementation
#### Backend (Django)
- **Custom User Model**: Extended for company association and roles
- **Database Models**: Structured for efficient data storage and queries
- **View Logic**: Separation of concerns with dedicated view functions
- **Form Handling**: Validated data input and file uploads
- **Data Processing**: CSV parsing and structured storage
- **Template Context**: Prepared data for frontend rendering
- **URL Routing**: Clean URL structure
- **Access Control**: Permission checks throughout
- **Custom User Model**: Extended for company association and roles
- **Database Models**: Structured for efficient data storage and queries
- **View Logic**: Separation of concerns with dedicated view functions
- **Form Handling**: Validated data input and file uploads
- **Data Processing**: CSV parsing and structured storage
- **Template Context**: Prepared data for frontend rendering
- **URL Routing**: Clean URL structure
- **Access Control**: Permission checks throughout
#### Frontend
- **Bootstrap 5**: For responsive layout and UI components
- **Plotly.js**: For interactive charts and visualizations
- **jQuery**: For AJAX functionality
- **Font Awesome**: For icons
- **Custom CSS**: For styling enhancements
- **Bootstrap 5**: For responsive layout and UI components
- **Plotly.js**: For interactive charts and visualizations
- **jQuery**: For AJAX functionality
- **Font Awesome**: For icons
- **Custom CSS**: For styling enhancements
#### Data Flow
1. **Upload Process**:
1. **Upload Process**:
- File validation
- CSV parsing
- Data normalization
- Record creation
- Association with company
- File validation
- CSV parsing
- Data normalization
- Record creation
- Association with company
2. **Dashboard Generation**:
2. **Dashboard Generation**:
- Data aggregation
- Statistical calculations
- Chart data preparation
- JSON serialization for frontend
- Data aggregation
- Statistical calculations
- Chart data preparation
- JSON serialization for frontend
3. **User Authentication**:
- Login/registration handling
- Session management
- Permission checks
- Access control based on company
3. **User Authentication**:
- Login/registration handling
- Session management
- Permission checks
- Access control based on company
#### Deployment Configuration
- **Docker**: Containerization for consistent deployment
- **Docker Compose**: Multi-container orchestration
- **Nginx**: Web server and static file serving
- **PostgreSQL**: Production-ready database
- **Gunicorn**: WSGI HTTP server
- **Docker**: Containerization for consistent deployment
- **Docker Compose**: Multi-container orchestration
- **Nginx**: Web server and static file serving
- **PostgreSQL**: Production-ready database
- **Gunicorn**: WSGI HTTP server
### Models
#### Accounts App
- **CustomUser**: Extends Django's User model with company association and role
- **Company**: Represents a company with users and data sources
- **CustomUser**: Extends Django's User model with company association and role
- **Company**: Represents a company with users and data sources
#### Dashboard App
- **DataSource**: Represents an uploaded CSV file with chat data
- **ChatSession**: Stores individual chat session data parsed from CSV
- **Dashboard**: Allows configuration of custom dashboards with selected data sources
- **DataSource**: Represents an uploaded CSV file with chat data
- **ChatSession**: Stores individual chat session data parsed from CSV
- **Dashboard**: Allows configuration of custom dashboards with selected data sources
### Usage Flow
1. **Admin Setup**:
1. **Admin Setup**:
- Admin creates companies
- Admin creates users and assigns them to companies
- Admin creates companies
- Admin creates users and assigns them to companies
2. **Company Admin**:
2. **Company Admin**:
- Uploads CSV files with chat data
- Creates and configures dashboards
- Manages company users
- Uploads CSV files with chat data
- Creates and configures dashboards
- Manages company users
3. **Regular Users**:
- View dashboards
- Search and explore chat data
- Analyze chat metrics
3. **Regular Users**:
- View dashboards
- Search and explore chat data
- Analyze chat metrics
## Future Enhancements
- API integration for real-time data
- More advanced visualizations
- Custom reports
- Export to additional formats (XML, HTML, PDF)
- Theme customization
- User access control with more granular permissions
- Direct integration with chat platforms via API
- Real-time dashboard updates using WebSockets
- Advanced analytics with machine learning
- Customizable reports and scheduling
- Enhanced visualization options
- API integration for real-time data
- More advanced visualizations
- Custom reports
- Export to additional formats (XML, HTML, PDF)
- Theme customization
- User access control with more granular permissions
- Direct integration with chat platforms via API
- Real-time dashboard updates using WebSockets
- Advanced analytics with machine learning
- Customizable reports and scheduling
- Enhanced visualization options
## License
This project is unlicensed. Usage is restricted to personal and educational purposes only. For commercial use, please contact the author.
This project is unlicensed. Usage is restricted to personal and educational purposes only. For commercial use, please
contact the author.