Smart IT Helpdesk 🚀
Enterprise IT Service Management & AI-Powered Triage Platform
An enterprise-grade IT Support Ticket Management System built with Next.js 16 (App Router), TypeScript, Prisma ORM + PostgreSQL, Tailwind CSS, and Google Gemini (gemini-2.5-flash by default) for ticket triage suggestions, ticket summaries for IT staff, and on-demand translation.
Live demo: https://smart-helpdesk-tan.vercel.app (one-click demo logins for each role)
Built with AI coding tools: Antigravity IDE with Claude 3.5 Sonnet and Gemini for the first version, then Claude Code for the review and rework. AI-USAGE.md explains what was delegated, what I decided, and how the generated code was validated.
📑 Table of Contents
🌟 Executive Overview
Smart IT Helpdesk bridges the gap between end-user frustration and IT service resolution. Traditional ticketing systems suffer from vague problem descriptions, misrouted tickets, and manual triage delays.
This platform solves these challenges through:
- AI-Assisted Triage & Self-Help: Google Gemini suggests a category, a priority and a few safe self-help steps while the employee writes the ticket. The employee decides whether to use the suggestion.
- Deterministic Lifecycle Enforcement: Tickets adhere strictly to a verified one-way state transition machine (
OPEN → ASSIGNED → IN_PROGRESS → RESOLVED → CLOSED) with immutable historical audit logs.
- Bilingual Enterprise Usability: Complete native Arabic (RTL) and English (LTR) localization coupled with on-demand Zendesk/Jira-style AI translation for global IT operations.
- Agent Productivity Suite: Fast sliding drawer interfaces, skill-based automated dispatch, SLA breach indicators, and rich visual KPI analytics.
🛠 System Architecture & Tech Stack
| Layer | Technology | Details / Rationale |
|---|
| Framework | Next.js 16.3+ (App Router) | React Server Components (RSC), Turbopack, and Server Actions |
| Language | TypeScript 5 | Strict typing throughout models, APIs, and UI components |
| Database & ORM | Prisma ORM 7 (node-postgres adapter) + PostgreSQL (Neon) | Versioned migrations (prisma/migrations), check constraints on roles, statuses and ratings; CLI settings in prisma.config.ts |
| Authentication | jose (JWT) + bcryptjs | Stateless encrypted HTTP-only session cookies with 12-round salt hashing |
| AI Engine | Google Gemini via @google/genai (gemini-2.5-flash, falls back to gemini-2.5-flash-lite) | Schema-validated JSON output for triage and summaries; translation |
| Styling & Design | Tailwind CSS + CSS Design Tokens | Clean typography, dark/light adaptive surfaces, and zero-border minimalism |
| Motion & Charts | Framer Motion & Recharts | Micro-animations, interactive layout transitions, and queue distribution graphs |
| Internationalization | Custom Context Engine + Cookies | Instant zero-reload locale toggling, bidirectional layout (rtl/ltr) |
| File Storage | Vercel Blob (private) or local disk | Attachments are never public; /api/files/[id] checks who may see them |
| Testing & CI | Vitest + GitHub Actions | Integration tests against a real PostgreSQL test database; lint, types, tests and build on every push |
📊 Entity-Relationship (ER) Diagram
The system uses a relational database schema (PostgreSQL) designed for auditability and operational integrity. It matches prisma/schema.prisma and the SQL in prisma/migrations/.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
