Paksa AI Assistant - Developer Setup Guide

Prerequisites

  • Python 3.11+ (Required)
  • Node.js 18+ (For frontend development)
  • Git (For version control)
  • SQLite (Built-in database - no setup required)

Quick Start (Recommended)

Automated Setup (One Command)

# Clone and setup everything automatically
git clone https://github.com/paksaitsolutions/PaksaAIAssistant.git
cd PaksaAIAssistant
python setup.py

Manual Setup (Step by Step)

1. Clone Repository

git clone https://github.com/paksaitsolutions/PaksaAIAssistant.git
cd PaksaAIAssistant

2. Python Environment Setup

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Database Setup

# Create helpdesk tables with demo data
python create_helpdesk_tables.py

# Optional: Create additional demo data
python create_super_admin_simple.py

4. Start the Server

# Method 1: Using startup script (Recommended)
python start_helpdesk_server.py

# Method 2: Direct uvicorn
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Method 3: Windows batch file
start-helpdesk.bat

5. Access the Application

Demo Credentials

Helpdesk Staff Login

Client Portal Access

  • Demo Email: john@techcorp.com
  • Access: Direct email-based login (no password required)

Super Admin

Frontend Development (Optional)

Next.js Frontend Setup

cd frontend
npm install
npm run dev

Database Information

SQLite Database Files

  • Main DB: paksa_ai_assistant.db
  • Backup DB: paksa_ai.db
  • Location: Project root directory

Key Tables

  • support_tickets - Support ticket management
  • ticket_messages - Chat messages between CSR and customers
  • team_members - Helpdesk staff
  • team_roles - Staff permissions
  • companies - Client companies
  • company_users - Client users

Testing the System

1. Test API Endpoints

# Test helpdesk API
python test_helpdesk_api.py

# Test basic functionality
python quick-test.py

2. Test Helpdesk Workflow

  1. Login as CSR at /test_helpdesk.html
  2. View tickets in dashboard
  3. Click ticket to open chat interface
  4. Send replies to customers
  5. Change ticket status

3. Test Client Portal

  1. Access /client_portal.html
  2. Login with demo email
  3. View existing tickets
  4. Create new ticket
  5. Reply to CSR messages

Key Features Implemented

✅ Helpdesk System

  • Real-time ticket management
  • CSR chat interface
  • Status updates (Open → In Progress → Resolved → Closed)
  • Customer information display
  • Message history

✅ Client Portal

  • Customer ticket access
  • New ticket creation
  • Live chat with CSR
  • Ticket status tracking

✅ API Endpoints

  • /api/helpdesk/login - CSR authentication
  • /api/helpdesk/tickets - Ticket listing
  • /api/helpdesk/tickets/{id} - Ticket details
  • /api/helpdesk/tickets/{id}/messages - Add messages
  • /api/client/tickets - Customer tickets
  • /api/client/tickets/{id}/reply - Customer replies

Troubleshooting

Common Issues

  1. Port 8000 in use: Change port in startup script
  2. Database errors: Run create_helpdesk_tables.py
  3. Import errors: Check virtual environment activation
  4. JSON parsing errors: Ensure server is running on correct port

Development Tips

  • Use --reload flag for auto-restart during development
  • Check app/error.log for detailed error messages
  • SQLite browser tools can help inspect database
  • Use browser dev tools to debug frontend issues

Production Deployment

Docker Deployment

docker-compose -f infrastructure/docker-compose.prod.yml up -d

Manual Deployment

# Install production dependencies
pip install -r requirements.txt

# Set production environment
export ENVIRONMENT=production

# Run with gunicorn
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker