Internal Service Desk Backend

A lightweight, role-based IT Service Desk backend built as an MVP for small and mid-sized organizations that need structured, auditable incident management without the overhead of enterprise ITSM tools.

---

📌 Project Overview

Many organizations rely on emails, chat messages, or spreadsheets to handle internal IT issues. These approaches lack traceability, accountability, and consistency.

This project delivers a clean, minimal, and extensible backend that supports:

• Centralized ticket management
• Clear ownership and role-based access
• Full lifecycle traceability
• Simple deployment and operation

The system is intentionally scoped to incident management only, avoiding enterprise complexity.

---

🎯 Business Objectives

• Provide a centralized system for managing IT incidents
• Ensure visibility into ticket ownership and status
• Enable traceability across the ticket lifecycle
• Offer a solid foundation that can be extended in future phases

---

👥 User Roles & Capabilities

Roles (Fixed Enum)

• EMPLOYEE
• IT_ADMIN
• SUPPORT_AGENT

Role Capabilities

Role	Capabilities
EMPLOYEE	Create tickets, view and comment only on their own tickets
IT_ADMIN	View all tickets system-wide, assign tickets, update any status
SUPPORT_AGENT	View and work only on tickets assigned to them

---

🔐 Authentication & Authorization

Authentication

• Internal authentication only
• Employee ID + password
• Stateless JWT-based authentication
• No refresh tokens (MVP scope)
• No external identity providers

Authorization

• Role-based authorization
• Enforced inside the service layer (not controllers)
• JWT used only for identity propagation

---

🧱 Domain Model

User

• id (UUID)
• employeeId (unique, immutable)
• passwordHash
• role (EMPLOYEE | IT_ADMIN | SUPPORT_AGENT)
• fullName
• email (unique)
• active
• createdAt, updatedAt

Users cannot be deleted in MVP. Only soft-disable is supported.

---

Ticket

• id (UUID)
• title
• description
• status (OPEN, IN_PROGRESS, RESOLVED, CLOSED)
• createdBy (EMPLOYEE)
• assignedTo (SUPPORT_AGENT, nullable)
• createdAt, updatedAt, resolvedAt

---

Ticket Comment

• id (UUID)
• ticket
• author
• commentText
• createdAt

Comments are immutable in MVP.

---

🔄 Ticket Lifecycle

OPEN → IN_PROGRESS → RESOLVED → CLOSED

• EMPLOYEE: cannot change status
• SUPPORT_AGENT: OPEN → IN_PROGRESS → RESOLVED
• IT_ADMIN: any transition

Invalid transitions are rejected via business rule validation.

---

📦 API Design

Authentication

• POST /api/auth/login

Users (IT_ADMIN only)

• POST /api/users
• GET /api/users/{id}
• GET /api/users?role=...

Tickets

• POST /api/tickets (EMPLOYEE)
• GET /api/tickets/{id}
• GET /api/tickets (role-aware)
• POST /api/tickets/{id}/assign (IT_ADMIN)
• PATCH /api/tickets/{id}/status (SUPPORT_AGENT / IT_ADMIN)

Ticket Comments

• POST /api/tickets/{id}/comments
• GET /api/tickets/{id}/comments

All endpoints are documented via OpenAPI / Swagger UI.

---

🚨 Error Handling

Centralized exception handling using @ControllerAdvice.

Custom Exceptions

• AuthenticationException → 401
• AuthorizationException → 403
• ResourceNotFoundException → 404
• ValidationException → 400
• BusinessRuleException → 409
• DuplicateResourceException → 409

Error Response Format

{
  "timestamp": "ISO-8601",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied",
  "path": "/api/..."
}

---

🛠️ Technology Stack

• Java 21
• Spring Boot 3.x
• Spring Security (JWT, stateless)
• Spring Data JPA
• PostgreSQL
• Hibernate ORM
• Springdoc OpenAPI (Swagger)

---

📄 API Documentation

Swagger UI is available at:

http://localhost:8080/swagger-ui/index.html

JWT Bearer authentication is supported directly from Swagger UI.

---

🧪 Testing

• Manual testing performed using Postman
• All role-based access scenarios verified
• Negative cases (authorization, invalid transitions) validated
• No known failing test cases at MVP closure

---

🚫 Explicitly Out of Scope (MVP)

• SLAs, escalation rules, priorities
• Workflow engines or approvals
• Notifications (email/chat)
• Reporting dashboards
• Knowledge base
• Asset management / CMDB
• Multi-tenancy

---

🚀 Future Enhancements (Post-MVP)

• Pagination and filtering
• Attachments
• Audit logs
• SLA support
• Reporting APIs
• Soft-delete for tickets

---

✅ MVP Status

This project is complete at MVP scope:

• All planned use cases implemented
• Architecture aligned with LLD
• Clean separation of concerns
• Secure, testable, and extensible

The backend is ready for handoff, deployment, or future iteration.

---

Project Name: internal-service-desk

---

📬 Contact

Chandra Sekhar Vipparla
📧 Email: code.chandrasekhar@gmail.com
🔗 LinkedIn: https://www.linkedin.com/in/chandra-sekhar-vipparla/