Skip to content

README.md

Latest commit

 

History

History
241 lines (189 loc) · 8.03 KB

README.md

File metadata and controls

241 lines (189 loc) · 8.03 KB

🎫 IT Helpdesk Ticketing System

A professional, full-stack IT helpdesk ticketing system built with Python and Flask — featuring a modern web dashboard, complete REST API, ITIL-aligned incident lifecycle, SLA tracking, and automated report generation.

Python Flask SQLite License ITIL

Built by Sandrine Uwineza — Technical Support Engineer · CCNA Certified · Computer Engineering BSc

🖥️ Dashboard Preview

The system ships with a fully-featured, responsive web dashboard — no external UI library dependencies. Deployable for free on Railway or Render in under 5 minutes.

Key dashboard features:

  • 📊 Real-time KPI cards — total, open, in-progress, critical, SLA breaches
  • 🎫 Ticket queue with priority-sorted view and SLA progress bars
  • 🔍 Live search and multi-filter (status, priority, category)
  • 📋 Ticket detail panel with full audit timeline
  • 🔴 One-click escalation, status transitions, and resolution
  • 📄 Downloadable Markdown incident reports per ticket
  • 📈 Category and priority breakdown charts

📋 What It Implements

This system covers the complete ITIL incident management lifecycle:

Ticket Submitted → Triaged → Assigned → In Progress → Resolved → Closed
                                  ↓
                             Escalated (Tier 1 → 2 → 3)
                                  ↓
                          SLA Breach Alert
Feature Detail
Ticket Lifecycle Open → In Progress → On Hold → Resolved → Closed
Priority Levels Critical · High · Medium · Low
SLA Enforcement Auto-calculated deadlines: 4h / 8h / 24h / 72h
Escalation Tier 1 → 2 → 3 with priority auto-bump
Audit Trail Full timestamped history of every action
Comments Public comments and internal notes
Root Cause Analysis Required field on resolution
Reports Markdown incident reports + SLA compliance summaries
REST API 15 endpoints — full CRUD + all operations
Categories Network · Hardware · Software · Security · 8 categories

⚡ Quick Start

# 1. Clone
git clone https://github.com/sandrineuwineza/it-helpdesk-ticketing-system.git
cd it-helpdesk-ticketing-system

# 2. Virtual environment
python -m venv venv
source venv/bin/activate   # Linux/macOS
venv\Scripts\activate      # Windows

# 3. Install
pip install -r requirements.txt

# 4. Run
python app.py

Open http://localhost:5000 — the database initialises automatically and demo tickets load on first visit.

🗂️ Project Structure

it-helpdesk-ticketing-system/
├── app.py                         # Flask app + 15 REST API endpoints
├── requirements.txt
├── Procfile                       # Railway / Render / Heroku
├── railway.toml
├── render.yaml
│
├── database/
│   ├── schema.sql                 # Full DB schema + seed data
│   └── db_manager.py             # Thread-safe connection + helpers
│
├── models/
│   ├── ticket.py                  # Ticket CRUD, SLA, transitions, stats
│   └── agent.py                   # Agent management
│
├── reports/
│   └── report_generator.py        # Markdown incident + SLA reports
│
├── templates/
│   └── index.html                 # Full SPA dashboard (no dependencies)
│
└── tests/
    └── test_tickets.py            # 30+ unit + integration tests

🔌 REST API Reference

Method Endpoint Description
GET /health Service health check
GET /api/stats Dashboard KPIs
GET /api/tickets List tickets (filterable)
POST /api/tickets Create a ticket
GET /api/tickets/:id Get ticket with history + comments
GET /api/tickets/ref/:ref Get by INC reference
PATCH /api/tickets/:id/status Update status
PATCH /api/tickets/:id/assign Assign to agent
POST /api/tickets/:id/escalate Escalate (Tier +1)
POST /api/tickets/:id/resolve Resolve with root cause
POST /api/tickets/:id/comments Add comment or note
DELETE /api/tickets/:id Delete ticket
GET /api/agents List agents
POST /api/agents Create agent
GET /api/categories List categories
GET /api/reports/incident/:id Download incident report
GET /api/reports/sla?days=7 Download SLA report
POST /api/seed Load demo data

Example — Create a ticket:

curl -X POST http://localhost:5000/api/tickets \
  -H "Content-Type: application/json" \
  -d '{
    "title": "VPN dropping connection",
    "description": "Remote user VPN drops every 20 minutes on all networks",
    "requester_name": "Carlos Mendoza",
    "requester_email": "c.mendoza@company.com",
    "priority": "high",
    "category_id": 1
  }'

Response:

{
  "id": 1,
  "reference": "INC-2026-0001",
  "status": "open",
  "priority": "high",
  "due_at": "2026-04-16T09:00:00+00:00",
  ...
}

🧪 Running Tests

# All tests
python -m pytest tests/ -v

# With coverage
python -m pytest tests/ -v --cov=. --cov-report=html

# Specific class
python -m pytest tests/ -v -k TestSLAStatus

Test coverage: 30+ tests across 9 test classes covering creation, SLA, escalation, status transitions, filtering, Flask API, and report generation.

🚀 Deployment (Free)

Railway (Recommended · 5 minutes)

  1. Push to GitHub
  2. railway.app → New Project → Deploy from GitHub
  3. Select this repo — Railway reads railway.toml automatically
  4. Settings → Networking → Generate Domain
  5. Live at https://your-app.up.railway.app

Render.com (Always-on with limits)

  1. Push to GitHub
  2. render.com → New → Web Service
  3. Connect repo — Render reads render.yaml automatically
  4. Live in ~3 minutes

📊 Database Schema

tickets          — Core ticket records with SLA deadlines
ticket_history   — Full audit log of all state changes
comments         — Public comments + internal notes
agents           — Support staff (Tier 1/2/3)
categories       — 8 predefined IT categories
sla_policies     — SLA hours by priority

All relationships enforced with foreign keys. WAL journal mode enabled for concurrent reads.

🛠️ Skills Demonstrated

Backend:          Python · Flask · SQLite · SQL · REST API Design
Database:         Schema design · JOINs · Indexes · Triggers
                  Foreign keys · WAL mode · Thread-safe connections
Engineering:      ITIL incident lifecycle · SLA management
                  Audit trails · Status state machines
                  Root cause analysis workflow
Frontend:         Vanilla JS · CSS Grid/Flexbox · Responsive design
                  Single-page app without frameworks
Testing:          pytest · Unit tests · Integration tests
                  Flask test client · 30+ test cases
Documentation:    OpenAPI-style endpoint table · Inline docstrings
Deployment:       Railway · Render · Procfile · gunicorn

📄 License

MIT License — see LICENSE

👤 Author

Sandrine Uwineza — Technical Support Engineer

🔗 LinkedIn · 📧 mrs.uwineza@gmail.com · 📍 Tlalnepantla de Baz, Estado de México

"Built from real IT support experience — the ticket lifecycle, SLA structure, escalation logic, and root cause requirement all reflect how incident management actually works in production environments."