DISPATCHUMS

Medical priority dispatch system streamlines medical case management, resource allocation, determinant codes and emergency response coordination between dispatchers, admins and responders.

📋 Table of Contents

• Overview
• Features
• Technology Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Running the Application
• API Documentation
• Testing
• Database Management

🎯 Overview

DISPATCHUMS is a modern, full-stack medical priority dispatch system designed to help emergency services manage cases efficiently. The system provides real-time case tracking, admin management, call card display, and chatbox feedback testimonial features.

✨ Features

Core Features

• 🔐 User Authentication & Authorization: Secure JWT-based authentication with role-based access control (Admin/User)
• 📊 Dashboard: Comprehensive overview with analytics & insights with charts and line bars
• 🚨 Case Management: Create, update, track, and manage emergency cases
• 🔍 Diagnostic Tools: Advanced diagnostic features for case analysis
• 👤 User Profile Management: Profile updates and password management
• 📝 Feedback System: Interactive chat-based feedback mechanism
• 📧 Email Notifications: Automated email notifications for password recovery and verification
• 📈 Reporting & Analytics: Visual analytics using charts and graphs
• 🗑️ Trash Management: Delete functionality with restore capabilities

Additional Features

• Responsive design for mobile and desktop
• Real-time data updates
• Haversine Formula for shortest distance determination
• PDF export & download functionality
• Timeline tracking for cases
• Work info management

🛠 Technology Stack

Frontend

• Framework: Next.js 15.5.4
• UI Library: React 19.1.0
• Language: TypeScript 5.9.3
• Styling:
  • Tailwind CSS 4.x
  • Chakra UI 3.28.1
  • Emotion
• Icons:
  • Heroicons 2.2.0
  • Lucide React 0.544.0
  • React Icons 5.5.0
• Charts: Recharts 3.5.1
• Animation: Framer Motion 12.23.24
• PDF Generation: jsPDF 4.0.0

Backend

• Framework: FastAPI 0.104.0+
• Server: Uvicorn 0.24.0+
• Language: Python 3.8+
• ORM: SQLAlchemy 2.0.25+
• Database: SQLite (development) / PostgreSQL (production ready)
• Authentication:
  • python-jose (JWT)
  • passlib (password hashing with bcrypt)
• Environment Management: python-dotenv
• File Uploads: python-multipart

Development Tools

• Linting: ESLint
• Process Management: Concurrently
• Version Control: Git

📁 Project Structure

dispatchums
├── frontend/                      # Next.js frontend application
│   ├── app/                       # App directory (Next.js 13+ App Router)
│   │   ├── dashboard/            # Dashboard pages
│   │   │   ├── admin/           # Admin-specific pages
│   │   │   │   ├── design/      # Design management
│   │   │   │   └── users/       # User management
│   │   │   └── user/            # User-specific pages
│   │   ├── diagnostic/          # Diagnostic tools
│   │   ├── entry/               # Entry pages
│   │   ├── login/               # Login page
│   │   ├── profile/             # User profile pages
│   │   ├── questions/           # Questions/FAQ section
│   │   ├── register/            # Registration page
│   │   ├── layout.tsx           # Root layout
│   │   ├── page.tsx             # Landing page
│   │   └── globals.css          # Global styles
│   ├── components/              # React components
│   │   ├── landing/            # Landing page components
│   │   └── shared/             # Shared/reusable components
│   ├── contexts/               # React contexts
│   ├── lib/                    # Utility functions and API clients
│   │   └── api.ts              # API integration
│   ├── public/                 # Static assets
│   ├── types/                  # TypeScript type definitions
│   ├── next.config.ts          # Next.js configuration
│   ├── tailwind.config.ts      # Tailwind CSS configuration
│   ├── tsconfig.json           # TypeScript configuration
│   └── package.json            # Frontend dependencies
│
├── my-fastapi-backend/          # FastAPI backend application
│   ├── app/                     # Application source code
│   │   ├── database/           # Database configuration
│   │   ├── models/             # SQLAlchemy models
│   │   ├── routers/            # API route handlers
│   │   │   ├── auth.py         # Authentication endpoints
│   │   │   ├── cases.py        # Case management endpoints
│   │   │   └── feedback.py     # Feedback endpoints
│   │   ├── auth.py             # Authentication utilities
│   │   ├── email_service.py    # Email service
│   │   ├── main.py             # FastAPI application entry point
│   │   └── __init__.py
│   ├── tests/                  # Test files (in root)
│   ├── init_database.py        # Database initialization script
│   ├── migrate_*.py            # Database migration scripts
│   ├── requirements.txt        # Backend dependencies
│   ├── run_server_simple.bat   # Simple server start script
│   └── start_server.bat        # Server start script
│
├── components/                  # Shared components (if any)
│   └── shared/
│
├── package.json                # Root package.json with scripts
└── README.md                   # This file

📋 Prerequisites

Before begin, ensure the following installed:

Required

• Node.js: >= 18.0.0
• npm: >= 9.0.0
• Python: >= 3.8
• pip: Latest version

Recommended

• Git: For version control
• VS Code: With recommended extensions (ESLint, Pylance, Prettier)

🚀 Installation

1. Clone Repository

git clone <repository-url>
cd https://github.com/claygiraf/dispatchums/

2. Install All Dependencies

Using the root package.json:

npm run install:all

Or install separately:

Frontend Dependencies

cd frontend
npm install

Backend Dependencies

cd my-fastapi-backend
pip install -r requirements.txt

⚙️ Configuration

Backend Configuration

1. Create a .env file in the my-fastapi-backend directory:

# Application Settings
PROJECT_NAME=Dispatchums API
DEBUG=True

# Database
DATABASE_URL=sqlite:///./dispatchums.db
# For PostgreSQL: postgresql://user:password@localhost/dbname

# JWT Authentication
SECRET_KEY=your-secret-key-here-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Email Settings (for password recovery)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password
EMAIL_FROM=[email protected]

# CORS Settings
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

2. Initialize the database:

cd my-fastapi-backend
python init_database.py

Frontend Configuration

The frontend is configured to connect to http://localhost:8000 by default. Update the API base URL in frontend/lib/api.ts if needed.

🏃 Running the Application

Development Mode

Option 1: Run Both Together (Recommended)

From the root directory:

npm run dev

This will start:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000

Option 2: Run Separately

Backend:

cd my-fastapi-backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend:

cd frontend
npm run dev

Production Mode

Build Frontend

npm run build

Start Production Servers

npm run start

Or manually:

# Backend
cd my-fastapi-backend
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Frontend
cd frontend
npm run build
npm start

📚 API Documentation

Once the backend is running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/api/v1/openapi.json

Main API Endpoints

Authentication

• POST /api/v1/login - User login
• POST /api/v1/register - User registration
• POST /api/v1/forgot-password - Request password reset
• POST /api/v1/verify-email - Verify email address
• GET /api/v1/me - Get current user info

Cases

• GET /api/v1/cases - List all cases
• POST /api/v1/cases - Create new case
• GET /api/v1/cases/{id} - Get case details
• PUT /api/v1/cases/{id} - Update case
• DELETE /api/v1/cases/{id} - Delete case (soft delete)

Feedback

• POST /api/v1/feedback - Submit feedback
• GET /api/v1/feedback - List feedback (admin only)

🧪 Testing

Backend Tests

The backend includes comprehensive test suites:

cd my-fastapi-backend

# Test specific functionality
python test_login.py
python test_registration.py
python test_api.py
python test_complete_flow.py
python test_password_change.py
python test_user_management.py
python test_feedback_chat.py

# Test email functionality
python test_email_sending.py
python test_forgot_password.py
python test_verification_flow.py

# Test profile and persistence
python test_profile_persistence.py
python test_profile_update.py

Frontend Tests

Run ESLint to check for code quality:

cd frontend
npm run lint

🗄️ Database Management

Database Migrations

The project includes several migration scripts:

cd my-fastapi-backend

# Add specific columns
python add_missing_columns.py
python add_username_column.py
python migrate_timeline_columns.py

# Migrate data
python migrate_db.py
python migrate_feedback_chat.py
python migrate_id_system.py
python migrate_user_fields.py

# Fix data
python fix_password_changed_field.py
python fix_usernames.py

Database Inspection

# Check database state
python check_users.py
python check_users_data.py
python check_db_users.py
python check_id_sync.py

# Verify data
python verify_sync.py

Reset Admin Password

python reset_admin_password.py

Setup Test Users

python setup_test_users.py

👥 User Roles

The system supports multiple user roles:

• Admin: Full access to all features including user management, case configuration and unit creation.
• Responder: Emergency response personnel with access to ambulance status management and feedback chatbox.
• Dispatcher: Create new case, case entry, post dispatch instruction, ambulance dispatch and feedback chatbox.

🔒 Security Features

• JWT-based authentication
• Password hashing with bcrypt
• Role-based access control (RBAC)
• CORS configuration
• SQL injection prevention (SQLAlchemy ORM)
• Environment variable protection

🤝 Contributing

All Rights Reserved. Academic project under MIT license.