# yuvisidhu19/queue-management-system architecture

> Architecture diagram of the GitHub repository yuvisidhu19/queue-management-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuvisidhu19/queue-management-system
- Repository: https://github.com/yuvisidhu19/queue-management-system

## Overview

##### Project Type & Purpose
- This is a monolithic, full-stack Django web application with three user roles (Customer, Employee, Admin) and an underlying queue-balancing algorithm.
- It exposes HTML/CSS/JS front-ends via Django templates, serves static assets, persists data in a relational store (SQLite), and integrates with two external services (Twilio SMS API and SMTP email).

##### File Structure
- Top-level:
- manage.py – Django CLI entry
- qms/ – Django project config (settings.py, urls.py, wsgi/asgi)
- app1/ – Main Django app (models.py, views.py, urls.py, admin.py, migrations)
- templates/ – HTML templates for user, employee, admin flows
- staticfiles/ – Compiled static assets (CSS/JS/fonts/images for Django admin)
- db.sqlite3 – Local database file
- Patterns & concerns:
- MVC (Model = app1/models.py, Views = app1/views.py & templates, Controller = Django URL dispatcher)
- Three logical “sub-applications” share the same codebase: Customer UI, Employee UI, Admin UI (Django admin).
- External integrations are isolated in views.py (Twilio & smtplib).

##### Extract Architecture Insights from README
- Three “flows”:
a. Customer registers via a web page; receives OTP via SMS+email; queries queue status; gets notifications when it’s their turn.
b. Employee logs in, selects a counter, serves “next customer” which triggers the queue balancing algorithm.
c. Admin uses Django admin to manage employee accounts and counter count.
- Dynamic queue rebalancing algorithm is the business-logic core.

##### Main Components & Their Interactions

A. Client Layer
- Mobile Browser (Customer)
- Web Browser (Employee & Admin)

B. Presentation Layer (Django server)
- Django URL Router (qms/urls.py → app1/urls.py)
- Templates Renderer (Django template engine)
- Static Files Server (staticfiles via WhiteNoise or Django’s staticfiles)

C. Application Layer (app1)
- Authentication & Authorization (Django auth for employees & admin; custom OTP logic for customers)
- Views / Controllers (app1/views.py)
- Queue Management Logic
- Token assignment
- Counter assignment (smallest-queue strategy)
- Dynamic rebalancing algorithm (on “next customer” clicks)
- Email/SMS Notification Module (Twilio REST client & smtplib)

D. Data Layer
- Relational DB (SQLite db.sqlite3)
- Models (app1/models.py)
- UserData (customers)
- Employee & Admin users (Django auth, extended)
- Counter & Queue tables

E. External Services
- Twilio SMS API (REST calls)
- SMTP Mail Server (smtplib)

##### Architectural Patterns & Design Principles
- MVC / MTV (Model-Template-View) in Django
- Layered architecture: Presentation → Application → Data
- Single monolith: All logical modules share one process and one DB
- External integration via well-defined adapters (views.py segments)

a. URL Router & Middleware
b. Templates Renderer + Static File server
c. app1 View Functions (annotate OTP flow, queue logic, next-customer algorithm)
d. Auth subsystem (Django auth & OTP)
6. At the bottom or side, note the “Dynamic Queue Allocation Algorithm” as a highlighted component inside app1, with a short annotation of its logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    Customer(("Customer")):::actor
    Employee(("Employee")):::actor
    Admin(("Admin")):::actor

    %% Client Layer
    subgraph "Client Layer"
        CustUI["Customer Interface"]:::presentation
        EmpUI["Employee Interface"]:::presentation
        AdminUI["Admin Interface"]:::presentation
    end

    Customer -->|"HTTP(S) requests/responses"| CustUI
    Employee -->|"HTTP(S) requests/responses"| EmpUI
    Admin -->|"HTTP(S) requests/responses"| AdminUI

    %% Django Web Server
    subgraph "Django Web Server"
        subgraph "Presentation Layer"
            Router["URL Router & Middleware"]:::presentation
            Templates["Templates Renderer"]:::presentation
            Static["Static Files Server"]:::presentation
        end

        subgraph "Application Layer"
            Auth["Authentication & Authorization"]:::app
            Views["View Functions"]:::app
            QueueLogic["Queue Management & Rebalancing"]:::app
            Notify["Email/SMS Notification Module"]:::app
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["SQLite Database"]:::data
        Models["Models"]:::data
    end

    %% External Services
    subgraph "External Services"
        Twilio["Twilio SMS API"]:::external
        SMTP["SMTP Mail Server"]:::external
    end

    %% Connections
    CustUI -->|"requests"| Router
    EmpUI -->|"requests"| Router
    AdminUI -->|"requests"| Router

    Router -->|routes to| Views
    Views -->|executes| QueueLogic
    Views -->|uses| Auth
    QueueLogic -->|queries/updates| Models
    Auth -->|validates| Models
    Views -->|sends notifications| Notify
    Notify -->|REST API calls| Twilio
    Notify -->|SMTP sessions| SMTP

    Router -->|renders| Templates
    Router -->|serves| Static
    QueueLogic -->|reads/writes| DB
    Models -->|persist data| DB

    %% Click Events
    click CustUI "https://github.com/yuvisidhu19/queue-management-system/blob/master/templates/index.html"
    click EmpUI "https://github.com/yuvisidhu19/queue-management-system/blob/master/templates/login.html"
    click AdminUI "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/admin.py"
    click Router "https://github.com/yuvisidhu19/queue-management-system/blob/master/qms/urls.py"
    click Templates "https://github.com/yuvisidhu19/queue-management-system/tree/master/templates/"
    click Static "https://github.com/yuvisidhu19/queue-management-system/tree/master/staticfiles/"
    click Auth "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"
    click Views "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"
    click QueueLogic "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"
    click Notify "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"
    click DB "https://github.com/yuvisidhu19/queue-management-system/blob/master/db.sqlite3"
    click Models "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/models.py"
    click Twilio "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"
    click SMTP "https://github.com/yuvisidhu19/queue-management-system/blob/master/app1/views.py"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,color:#1B2631
    classDef app fill:#ABEBC6,stroke:#196F3D,color:#145A32
    classDef data fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef external fill:#F5CBA7,stroke:#BA4A00,color:#78281F
    classDef actor fill:#D7BDE2,stroke:#6C3483,color:#4A235A
```
