SessionTrackr

A comprehensive user session tracking and analytics platform built with Django REST Framework. The platform provides advanced user behavior tracking, device fingerprinting, and real-time analytics capabilities for web applications.

🚀 Features

• Device Fingerprinting: Advanced browser fingerprinting for user identification
• Session Management: Complete session lifecycle tracking and management
• Event Tracking: Comprehensive user interaction and custom event tracking
• Real-time Analytics: Configurable metrics and analytics dashboards
• Multi-tenant Architecture: Support for multiple clients with API key authentication
• Scalable Backend: Built with Django, PostgreSQL, Redis, and Celery
• API Documentation: Auto-generated OpenAPI/Swagger documentation
• Docker Ready: Full containerization with Docker Compose

🏗️ Architecture

System Components

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Client    │    │   Django App    │    │   PostgreSQL    │
│                 │◄──►│                 │◄──►│                 │
│   (Frontend)    │    │   (Backend)     │    │   (Database)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │      Redis      │    │     Celery      │
                       │                 │◄──►│                 │
                       │  (Cache/Broker) │    │   (Workers)     │
                       └─────────────────┘    └─────────────────┘

Application Structure

The project follows a modular Django architecture with the following apps:

• core/ - Main Django configuration and settings
• sessions_tracking/ - Core session tracking functionality
  • Device fingerprinting
  • Session management
  • Event tracking
• clients/ - Multi-tenant client management
• analytics/ - Metrics and analytics processing
  • Session-based metrics
  • Event-based metrics
  • Conversion tracking

Database Schema

Client ──┐
         │
         ├── UserDeviceFingerprint ── UserSession ── UserEvent
         │                                       │
         └── BaseMetrics ─────────────────────────┘
             ├── SessionMetrics
             ├── EventMetrics
             └── ConversionMetrics

🛠️ Technology Stack

• Backend: Django 4.2+ with Django REST Framework
• Database: PostgreSQL 15
• Cache & Message Broker: Redis 7
• Task Queue: Celery with Redis broker
• API Documentation: drf-spectacular (OpenAPI/Swagger)
• Containerization: Docker & Docker Compose
• Code Quality: Ruff (linting), pytest (testing)

📋 Prerequisites

• Docker Desktop or Docker Engine + Docker Compose
• Git

🚀 Quick Start

1. Clone the Repository

git clone <repository-url>
cd SessionTrackr

2. Environment Configuration

Create a .env file in the project root:

# Django Settings
DJANGO_SECRET_KEY=your-secret-key-here
DJANGO_DEBUG=True

# Database Configuration
DJANGO_DB_NAME=sessiontrackr
DJANGO_DB_USER=postgres
DJANGO_DB_PASSWORD=postgres
DJANGO_DB_HOST=localhost
DJANGO_DB_PORT=5432

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=

3. Start with Docker Compose

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

4. Initialize the Database

# Create and run migrations
docker-compose exec web python manage.py migrate

# Create a superuser (optional)
docker-compose exec web python manage.py createsuperuser

5. Access the Application

• API Base URL: http://localhost:8000/api/
• Swagger Documentation: http://localhost:8000/api/docs/swagger/
• Django Admin: http://localhost:8000/admin/

🐳 Docker Services

The application consists of the following Docker services:

Service	Description	Port	Health Check
web	Django application server	8000	✅
db	PostgreSQL database	5432	✅
redis	Redis cache and message broker	6379	✅
celery_worker	Background task processor	-	✅
celery_beat	Periodic task scheduler	-	✅

📚 API Documentation

Authentication

The API uses Token Authentication. Include the token in the Authorization header:

Authorization: Token your-api-token-here

Core Endpoints

Session Tracking

• POST /api/session_tracking/UserDeviceFingerPrint/ - Create device fingerprint
• POST /api/session_tracking/UserSession/ - Start/manage sessions
• POST /api/session_tracking/UserEvent/ - Track user events

Client Management

• GET /api/clients/ - List clients
• POST /api/clients/ - Create new client

Analytics

• GET /api/metrics/ - Retrieve analytics data

Example Usage

# Create a device fingerprint
curl -X POST http://localhost:8000/api/session_tracking/UserDeviceFingerPrint/ \
  -H "Authorization: Token your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "client": 1,
    "fingerprint_hash": "abc123...",
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.1"
  }'

🔧 Development

Local Development Setup

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

# Start services (PostgreSQL and Redis required)
python manage.py runserver

Running Tests

# Using Docker
docker-compose exec web pytest

# Local development
poetry run pytest

Code Quality

# Run linting
poetry run ruff check .

# Format code
poetry run ruff format .

📊 Monitoring & Observability

Health Checks

All services include health checks for monitoring:

# Check service status
docker-compose ps

# View logs
docker-compose logs web
docker-compose logs celery_worker

Celery Monitoring

Monitor background tasks and queues:

# View active workers
docker-compose exec celery_worker celery -A core inspect active

# Monitor task queue
docker-compose exec celery_worker celery -A core inspect stats

🔐 Security Considerations

• Environment variables for sensitive configuration
• Token-based API authentication
• CORS configuration for cross-origin requests
• Database connection pooling and optimization
• Non-root user in Docker containers

📈 Scaling & Performance

Horizontal Scaling

# Scale Celery workers
docker-compose up --scale celery_worker=3

# Scale web servers (requires load balancer)
docker-compose up --scale web=2

Performance Optimization

• Redis caching for frequently accessed data
• Database indexing on critical fields
• Celery for asynchronous task processing
• Connection pooling for database connections

👨‍💻 Author

Denys Naumenko (@gominibui)

📄 License

This project is proprietary software. All rights reserved.

---