Easy Queue Management System

A production-style Queue Management REST API built with Django REST Framework. This system allows organizations to manage departments, counters, queues, and customer tickets efficiently.

---

What is Easy Queue?

Easy Queue is a backend API system that digitizes the physical queue/token system used in banks, hospitals, government offices, and service centers. Customers take a ticket, wait for their number to be called, and get served at a counter.

---

Roles

Role	Description
ADMIN	Full access. Can create/update/delete departments, counters, queues. Can manage users.
STAFF	Can serve, complete, skip, and cancel tickets. Cannot manage departments or counters.
CUSTOMER	Can register, take a ticket, and view queue status.

---

What Each Role Can Do

Admin

• Create, update, delete Departments
• Create, update, delete Counters
• Create, update, delete Queues
• View all tickets and their history
• Manage all users
• View all notifications

Staff

• View departments, counters, queues
• Serve a ticket (assign to counter)
• Complete a ticket
• Skip a ticket
• Cancel a ticket
• View queue history

Customer

• Register an account
• Login and get JWT token
• Take a ticket from a queue
• View their ticket status
• View their notifications

---

How The Queue Process Works

1. Admin creates a Department (e.g. Finance)
2. Admin creates a Counter under that Department (e.g. Counter 1)
3. Admin creates a Queue under that Department (e.g. Finance Queue)
4. Customer registers and logs in
5. Customer takes a ticket → system auto-generates ticket number (A001, A002...)
6. Staff calls next ticket → ticket status changes to SERVING
7. Staff completes the ticket → ticket status changes to COMPLETED
8. Every status change is recorded in Queue History

---

Tech Stack

Technology	Purpose
Python	Programming language
Django 6.0.6	Web framework
Django REST Framework	API layer
PostgreSQL	Database
JWT (SimpleJWT)	Authentication
django-filter	Filtering

---

Project Structure

easy_queue/
│
├── config/
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
│
└── apps/
    ├── accounts/         # User model, registration, profile
    ├── department_app/   # Department management
    ├── counter_app/      # Counter management
    ├── queue_app/        # Queue, Ticket, Queue History
    ├── notification_app/ # User notifications
    └── common/           # Shared base model

---

Architecture

Request
    ↓
APIView / GenericView / ViewSet
    ↓
Serializer
    ↓
Service Layer (services.py)
    ↓
Selector Layer (selectors.py)
    ↓
Model (ORM)
    ↓
PostgreSQL

---

Installation & Setup

1. Clone the repository

git clone https://github.com/yourusername/easy-queue.git
cd easy-queue

2. Create and activate virtual environment

python -m venv qenv
qenv\Scripts\activate  # Windows

3. Install dependencies

pip install -r requirements.txt

4. Create PostgreSQL database

CREATE DATABASE easy_queue;

5. Configure environment variables

Update config/settings.py with your database credentials:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'easy_queue',
        'USER': 'postgres',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

6. Run migrations

python manage.py migrate

7. Create superuser

python manage.py createsuperuser

8. Run the server

python manage.py runserver

---

API Reference

Authentication

Method	Endpoint	Description	Auth Required
POST	/api/token/	Get JWT access and refresh token	No
POST	/api/token/refresh/	Refresh access token	No

Accounts

Method	Endpoint	Description	Auth Required
POST	/api/accounts/register/	Register a new user	No
GET	/api/accounts/profile/	Get logged in user profile	Yes
PUT	/api/accounts/profile/	Update logged in user profile	Yes

Departments

Method	Endpoint	Description	Role Required
GET	/api/departments/	List all departments	Authenticated
POST	/api/departments/	Create a department	Admin
GET	/api/departments/{id}/	Get a department	Authenticated
PUT	/api/departments/{id}/	Update a department	Admin
DELETE	/api/departments/{id}/	Delete a department	Admin

Counters

Method	Endpoint	Description	Role Required
GET	/api/counters/	List all counters	Authenticated
POST	/api/counters/	Create a counter	Admin
GET	/api/counters/{id}/	Get a counter	Authenticated
PUT	/api/counters/{id}/	Update a counter	Admin
DELETE	/api/counters/{id}/	Delete a counter	Admin

Queues

Method	Endpoint	Description	Role Required
GET	/api/queues/	List all queues	Authenticated
POST	/api/queues/	Create a queue	Admin
GET	/api/queues/{id}/	Get a queue	Authenticated
PUT	/api/queues/{id}/	Update a queue	Admin
DELETE	/api/queues/{id}/	Delete a queue	Admin

Tickets

Method	Endpoint	Description	Role Required
GET	/api/tickets/	List all tickets	Authenticated
POST	/api/tickets/	Create a ticket (auto generates ticket number)	Authenticated
GET	/api/tickets/{id}/	Get a ticket	Authenticated
DELETE	/api/tickets/{id}/	Delete a ticket	Admin
GET	/api/tickets/next/?queue={id}	Get next waiting ticket in queue	Authenticated
GET	/api/tickets/waiting/?queue={id}	Get all waiting tickets in queue	Authenticated
POST	/api/tickets/{id}/serve/	Assign ticket to counter (SERVING)	Admin, Staff
POST	/api/tickets/{id}/complete/	Mark ticket as completed	Admin, Staff
POST	/api/tickets/{id}/skip/	Skip a ticket	Admin, Staff
POST	/api/tickets/{id}/cancel/	Cancel a ticket	Admin, Staff

Queue History

Method	Endpoint	Description	Role Required
GET	/api/queue-history/	List all history records	Authenticated
GET	/api/queue-history/{id}/	Get a history record	Authenticated

Notifications

Method	Endpoint	Description	Auth Required
GET	/api/notifications/	List logged in user notifications	Yes
POST	/api/notifications/{id}/mark_read/	Mark a notification as read	Yes
POST	/api/notifications/mark_all_read/	Mark all notifications as read	Yes

---

Filtering, Searching & Ordering

Tickets

GET /api/tickets/?status=WAITING
GET /api/tickets/?queue=1
GET /api/tickets/?search=Nafis
GET /api/tickets/?ordering=-created_at

Queues

GET /api/queues/?department=1
GET /api/queues/?is_active=true
GET /api/queues/?search=General

---

Ticket Status Flow

WAITING → SERVING → COMPLETED
WAITING → SKIPPED
WAITING → CANCELLED
SERVING → CANCELLED

---

Throttling

User Type	Rate Limit
Anonymous	50 requests/day
Authenticated	500 requests/day

---

Future Updates

🔴 High Priority

• Docker — Containerize the application with Docker and docker-compose for easy deployment
• Celery — Async task queue for background jobs (sending emails, processing notifications)
• Redis — Message broker for Celery and caching layer for frequently accessed data

🟡 Medium Priority

• Swagger/OpenAPI — Auto-generated API documentation UI
• Email Notifications — Send email when ticket is called via Celery
• Unit Tests — Full test coverage for services, selectors, and APIs
• Real-time Updates — Django Channels + WebSocket for live queue status

🟢 Nice To Have

• Rate limiting per endpoint — Custom throttling for specific APIs
• Token Authentication — Alternative to JWT for learning purposes
• Deployment — Deploy to Railway or Render with PostgreSQL

---

License

MIT License