Getting Started

Overview

Internal IT Ticket Dashboard is a full-stack web application for managing internal IT support requests within an organization.

Use case. Employees need a way to report IT issues (hardware, software, access requests, and so on) without going through informal channels, while the IT team needs a shared queue to triage, assign, and resolve those issues.

Main workflow. An Employee creates a ticket describing the issue. An Admin can assign it to a specific IT Staff member. IT Staff update the ticket status as work progresses (Open → In Progress → Resolved → Closed). Employees can track their own tickets, and Admins have full visibility and control across the system.

Technologies

Only technologies present in package.json are listed.

Next.js 16 (App Router)

Provides file-based routing, server components, and Server Actions used throughout the app, including the dashboard and ticket forms.

React 19

Underlying UI library for all client and server components.

TypeScript

Static typing across services, repositories, and components.

NextAuth.js v4 (Credentials Provider)

Handles authentication with email/password, issues JWT sessions, and exposes the session used for authorization checks.

Prisma ORM (@prisma/client, @prisma/adapter-pg)

Type-safe database access layer for the User and Ticket models, and migration management.

PostgreSQL (pg)

Relational database storing users and tickets.

Zod

Validates input to ticket Server Actions (create, update, status update) before it reaches the repository layer.

React Hook Form + @hookform/resolvers

Manages ticket form state and wires Zod validation into forms.

Tailwind CSS 4

Utility-first styling for every page and component.

shadcn/ui + @base-ui/react

Accessible, unstyled UI primitives (dialog, select, sheet, avatar, etc.) styled with Tailwind.

@tanstack/react-table

Table utilities used by the ticket list.

bcryptjs

Hashes and verifies user passwords during authentication.

sonner

Toast notifications for ticket actions.

lucide-react

Icon set used across the UI.

date-fns

Date formatting for ticket timestamps.

next-themes

Theme handling infrastructure.

Technology	Why it's used
Next.js 16 (App Router)	Provides file-based routing, server components, and Server Actions used throughout the app, including the dashboard and ticket forms.
React 19	Underlying UI library for all client and server components.
TypeScript	Static typing across services, repositories, and components.
NextAuth.js v4 (Credentials Provider)	Handles authentication with email/password, issues JWT sessions, and exposes the session used for authorization checks.
Prisma ORM (@prisma/client, @prisma/adapter-pg)	Type-safe database access layer for the User and Ticket models, and migration management.
PostgreSQL (pg)	Relational database storing users and tickets.
Zod	Validates input to ticket Server Actions (create, update, status update) before it reaches the repository layer.
React Hook Form + @hookform/resolvers	Manages ticket form state and wires Zod validation into forms.
Tailwind CSS 4	Utility-first styling for every page and component.
shadcn/ui + @base-ui/react	Accessible, unstyled UI primitives (dialog, select, sheet, avatar, etc.) styled with Tailwind.
@tanstack/react-table	Table utilities used by the ticket list.
bcryptjs	Hashes and verifies user passwords during authentication.
sonner	Toast notifications for ticket actions.
lucide-react	Icon set used across the UI.
date-fns	Date formatting for ticket timestamps.
next-themes	Theme handling infrastructure.

Features

Authentication

Email/password sign-in via NextAuth Credentials Provider
Passwords verified with bcrypt
JWT-based sessions
Quick-login demo accounts for each role
Route protection in proxy.ts (redirects unauthenticated users away from /dashboard, and authenticated users away from /login)

Dashboard

Role-specific stat cards (global stats for Admin; scoped stats for IT Staff and Employees)
Role-specific tabs for IT Staff and Employees (My Tickets / All Tickets)
Ticket creation entry point for Employees

Ticket Management

Create tickets (Employees)
View ticket details
Edit ticket (owner, while status is OPEN)
Delete ticket (Admin, or owner while status is OPEN)
Update ticket status
Assign a ticket (Admin)

Authorization

Role-based access control for ADMIN, IT_STAFF, and EMPLOYEE
Server-side permission checks for every ticket mutation (create, view, edit, delete, assign, change status)
Employees restricted to viewing/editing their own tickets
IT Staff restricted to changing status only on tickets assigned to them

Search

Search tickets by title, category, or assignee name

Filter

Filter tickets by status
Filter tickets by priority

Sorting

Sort tickets by created date, priority, or status
Toggle ascending / descending order

Responsive Design

Responsive dashboard layout, tables, and dialogs using Tailwind breakpoints

Setup

1. Install dependencies

npm install

2. Configure environment variables

cp .env.example .env

3. Generate the Prisma client

npx prisma generate

4. Run database migrations

npx prisma migrate dev

5. Seed the database

npm run db:seed

6. Run the development server

npm run dev

Environment variables required in .env: DATABASE_URL, AUTH_SECRET, and NEXTAUTH_URL (see .env.example).

Architecture

The app uses the Next.js App Router with a feature-based module structure under lib/modules (auth, ticket, user). Each module separates concerns into a repository and a service layer:

Repository pattern — ticket.repository.ts and user.repository.ts are the only files that talk to Prisma directly.
Service layer — ticket.service.ts and user.service.ts are marked "use server" and exposed to the UI as Next.js Server Actions. This is where authentication and authorization checks run before a repository call is made.
Prisma ORM + PostgreSQL — schema is defined in prisma/schema.prisma with User and Ticket models, accessed via @prisma/adapter-pg.
Authentication — NextAuth Credentials Provider checks email/password against the User table (bcrypt), and issues a JWT session.
Authorization — role-based permission functions in lib/modules/auth/auth.helpers.ts (canCreateTicket, canEditTicket, canDeleteTicket, canAssignTicket, canChangeStatus) are called from the service layer for every mutation. Route-level protection is handled separately in proxy.ts, which redirects unauthenticated requests away from /dashboard.
Feature-based module structure — UI components mirror the same boundaries, grouped under components/dashboard and components/ticket.

Browser

React Client Components

Next.js App Router

Pages · Server Components

Server Actions

ticket.service.ts · user.service.ts

Repository Layer

ticket.repository.ts · user.repository.ts

Prisma ORM

@prisma/client + @prisma/adapter-pg

PostgreSQL

users · tickets

Authentication (NextAuth) sits alongside the App Router layer and the User repository: it verifies credentials against the database and issues the session that the Server Actions and lib/modules/auth/auth.helpers.ts use for role-based authorization checks on every ticket mutation.

Folder Structure

app/
  api/auth/[...nextauth]/   # NextAuth route handler
  dashboard/                # Dashboard page and layout (protected)
  login/                    # Login page
  documentation/            # This documentation page
components/
  dashboard/                # Dashboard cards, tabs, sign-out button
  ticket/                   # Ticket list, filters, sorting, dialogs, badges
  ui/                       # shadcn/ui primitives
lib/
  db/                       # Prisma client instance
  modules/
    auth/                   # NextAuth config, session helpers, permission checks
    ticket/                 # Ticket repository, service (Server Actions), validation
    user/                   # User repository, service
  utils/                    # Shared utilities
prisma/
  schema.prisma             # Database schema
  migrations/                # Prisma migrations
  seed.ts                   # Database seed script
types/                      # Shared TypeScript types / DTOs
proxy.ts                    # Route-protection middleware