# Service Desk Application Documentation ## 1. Project Summary The Service Desk Application is a web-based system for managing support requests and ticket workflows. It will be built with: - **Frontend:** React + Vite + Tailwind CSS - **Backend:** Node.js + Express - **Database:** MySQL The platform is intended to help teams capture, assign, track, and resolve service issues efficiently. --- ## 2. Objectives ### Primary Objectives - Provide a simple and reliable ticket management system - Support role-based workflows for admins, agents, and requesters - Maintain clear ticket history and communication logs - Offer dashboard visibility into workload and ticket statuses ### MVP Objectives - Secure login and role-based access - Ticket CRUD and assignment workflow - Comments and internal notes - User administration - Basic operational reporting --- ## 3. Users and Roles ### Admin Responsibilities: - manage users - assign roles - manage categories and priorities - view all tickets - review dashboard metrics ### Agent Responsibilities: - view assigned or accessible tickets - update ticket status - add comments and internal notes - resolve tickets ### Requester Responsibilities: - create service tickets - view own tickets - reply to tickets - track progress --- ## 4. Functional Requirements ### 4.1 Authentication and Authorization - user login - secure password handling - JWT-based session/auth flow - protected routes in frontend and backend - role-based permissions ### 4.2 Ticket Management - create new ticket - list tickets - filter/search tickets - view ticket detail - update ticket fields - assign ticket to agent - change ticket status - close or resolve ticket ### 4.3 Ticket Communication - add ticket comments/replies - internal notes for agents/admins - timeline/history of changes ### 4.4 Administration - create/edit/deactivate users - manage categories - manage priorities - review system dashboard ### 4.5 Dashboard and Reporting - ticket totals by status - ticket totals by priority - agent workload summary - recently updated tickets --- ## 5. Non-Functional Requirements - responsive UI - basic accessibility support - clean, maintainable code structure - secure API handling - scalable architecture for future modules - clear documentation for setup and feature growth --- ## 6. Recommended Architecture ## Frontend Architecture **Stack:** React + Vite + Tailwind CSS Suggested libraries: - React Router - Axios - React Hook Form - Zod/Yup - TanStack Query Suggested module structure: ```text frontend/ src/ api/ components/ features/ auth/ dashboard/ tickets/ users/ layouts/ pages/ routes/ hooks/ utils/ ``` ## Backend Architecture **Stack:** Node.js + Express + MySQL Suggested modules: - route layer - controller layer - service layer - validation layer - middleware layer - db/config layer Suggested structure: ```text backend/ src/ config/ controllers/ middleware/ routes/ services/ models/ validators/ utils/ ``` --- ## 7. Database Specification ### Core Entities #### `roles` - `id` - `name` - `created_at` #### `users` - `id` - `name` - `email` - `password_hash` - `role_id` - `is_active` - `created_at` - `updated_at` #### `categories` - `id` - `name` - `description` - `created_at` #### `priorities` - `id` - `name` - `level` - `created_at` #### `tickets` - `id` - `ticket_number` - `title` - `description` - `status` - `category_id` - `priority_id` - `created_by` - `assigned_to` - `resolved_at` - `created_at` - `updated_at` #### `ticket_comments` - `id` - `ticket_id` - `user_id` - `comment` - `is_internal` - `created_at` #### `ticket_history` - `id` - `ticket_id` - `user_id` - `field_name` - `old_value` - `new_value` - `action_type` - `created_at` --- ## 8. Ticket Workflow Recommended initial statuses: - `Open` - `In Progress` - `Pending` - `Resolved` - `Closed` ### Example Flow 1. requester creates ticket 2. ticket starts as `Open` 3. admin or system assigns ticket to agent 4. agent sets status to `In Progress` 5. if waiting on requester, status may become `Pending` 6. when fixed, status becomes `Resolved` 7. after confirmation or closure rules, status becomes `Closed` --- ## 9. API Specification ## Auth - `POST /api/auth/login` - `POST /api/auth/logout` - `GET /api/auth/me` ## Users - `GET /api/users` - `POST /api/users` - `PUT /api/users/:id` - `DELETE /api/users/:id` ## Tickets - `GET /api/tickets` - `POST /api/tickets` - `GET /api/tickets/:id` - `PUT /api/tickets/:id` - `PATCH /api/tickets/:id/status` - `PATCH /api/tickets/:id/assign` ## Ticket Comments - `GET /api/tickets/:id/comments` - `POST /api/tickets/:id/comments` ## Categories - `GET /api/categories` - `POST /api/categories` - `PUT /api/categories/:id` - `DELETE /api/categories/:id` ## Priorities - `GET /api/priorities` - `POST /api/priorities` - `PUT /api/priorities/:id` - `DELETE /api/priorities/:id` ## Dashboard - `GET /api/dashboard/stats` --- ## 10. Frontend Pages ### Public / Auth - Login ### Protected - Dashboard - Ticket List - Ticket Detail - Create Ticket - User Management - Category/Priority Management - Profile / Settings --- ## 11. UI/UX Notes - Use a dashboard layout with sidebar + topbar - Use cards and tables for ticket summaries - Keep forms simple and validated - Design for desktop first, but maintain mobile responsiveness - Use consistent badge colors for statuses and priorities --- ## 12. Environment Variables ### Backend Expected variables: ```env PORT=5000 NODE_ENV=development DB_HOST=localhost DB_PORT=3306 DB_NAME=service_desk DB_USER=root DB_PASSWORD= JWT_SECRET=change_this_secret JWT_EXPIRES_IN=1d ``` ### Frontend Expected variables: ```env VITE_API_BASE_URL=http://localhost:5000/api ``` --- ## 13. Development Phases ### Phase 1 — Setup - create frontend and backend projects - configure Tailwind - configure Express - connect MySQL - define initial schema ### Phase 2 — Auth Foundation - login API - password hashing - JWT auth middleware - protected frontend routes ### Phase 3 — Ticket Module - ticket create/list/detail/update - filtering and assignment - status handling ### Phase 4 — Communication and History - comments - internal notes - audit/history tracking ### Phase 5 — Admin Module - user management - category and priority management - dashboard stats ### Phase 6 — Testing and Deployment - API tests - UI validation - deployment setup - production documentation --- ## 14. Risks and Scope Control ### Risks - unclear business rules for ticket lifecycle - permission changes during development - schema changes late in implementation - scope creep from notifications/attachments/SLA features ### Scope Control Recommendations - keep attachments out of MVP unless required - keep notifications optional for phase 2 - lock ticket statuses early - finalize role permissions before coding deep workflows --- ## 15. Future Enhancements Potential post-MVP features: - file attachments - email notifications - SLA tracking - escalation rules - canned responses - knowledge base / FAQ - customer satisfaction survey - real-time updates with websockets - multi-department routing --- ## 16. Definition of Done for MVP The MVP is considered complete when: - users can authenticate securely - requester can create and track tickets - agent can manage ticket progress - admin can manage users and metadata - ticket comments/history work correctly - dashboard shows useful operational metrics - frontend and backend run successfully in a local environment --- ## 17. Suggested Next Implementation Step The best next step is to scaffold the repository with: 1. `frontend/` using React + Vite + Tailwind 2. `backend/` using Node.js + Express 3. initial MySQL schema 4. base authentication flow That foundation will make the rest of the application much easier to build consistently.