🎫 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.

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."