🎫 NESK Help Desk

Enterprise-Grade Customer Support Platform

A modern, full-stack help desk system built with cutting-edge technologies.
Featuring real-time ticket management, knowledge base, and comprehensive admin controls.

Features • Tech Stack • Quick Start • Architecture • Screenshots

✨ Features

🎯 Core Functionality

Multi-Role System - User, Staff, and Admin roles with granular permissions
Smart Ticket Management - Priority-based routing, status tracking, and rich-text responses
Knowledge Base - Searchable, categorized articles with draft/published workflow
Real-Time Updates - Server Actions for instant UI updates without page reloads
Rich Text Editor - Full-featured WYSIWYG editor with React Quill integration
Dark/Light Theme - System preference detection with user override and persistent storage
Internationalization - Multi-language support (English, Arabic, Spanish, French) with locale switching

👥 User Portal

Ticket submission with file attachments
Real-time ticket status tracking
Searchable knowledge base
Ticket history and thread views

🛠️ Staff Dashboard

Unified ticket queue with advanced filtering
Inline ticket management (status, priority, assignment)
Knowledge base article authoring
Customer communication tools

⚙️ Admin Panel

Team Management - User roles, permissions, and email verification
System Settings - Configurable business rules and email templates
Analytics & Reporting - Ticket metrics, response times, and performance KPIs
Category Management - Organize tickets and KB articles
Email Templates - Customizable notification templates

🔐 Security & Auth

Better Auth integration for secure authentication
Math-based CAPTCHA on login and signup to prevent abuse
Password reset flow with email verification
Session management with role-based access control
Protected routes and API endpoints
Graceful email fallback when API keys are not configured

🚀 Tech Stack

Frontend

Next.js 16 (App Router, Turbopack, Server Components)
React 19 (Latest features including Server Actions)
TypeScript 5 (Type safety across the stack)
Tailwind CSS v4 (Utility-first styling)
React Quill (Rich text editing)
next-themes (Dark/Light mode support)

Backend

Next.js API Routes (RESTful endpoints)
Server Actions (Type-safe mutations)
Better Auth 1.4 (Authentication & authorization)
Prisma ORM 7.1 (Type-safe database client)

Database & Infrastructure

PostgreSQL (Primary database)
Prisma Migrations (Schema versioning)
Bun (Fast package manager and runtime)

Developer Experience

Biome (Lightning-fast linting & formatting)
TypeScript strict mode (Maximum type safety)
Prisma Studio (Database GUI)

🏃 Quick Start

Prerequisites

node >= 18.17.0
bun >= 1.0.0 (or npm/yarn/pnpm)
postgresql >= 14

Installation

Clone the repository

git clone https://github.com/tarpagad/nesk.git
cd nesk

Install dependencies

bun install

Set up environment variables

cp .env.example .env

Edit .env with your configuration:

# Database
DATABASE_URL="postgresql://user:password@localhost:5432/nesk"

# Auth
BETTER_AUTH_SECRET="your-secret-key-here"
BETTER_AUTH_URL="http://localhost:3000"

# Email (Optional - defaults to console logging in dev)
RESEND_API_KEY="your-resend-api-key"

# PUBLIC URL
NEXT_PUBLIC_URL="your-deployed-public-url"

Initialize the database

# Generate Prisma client
bun run db:generate

# Push schema to database
bun run db:push

# Seed with sample data
bun run db:seed

Start the development server

bun dev

Visit http://localhost:3000 🎉

Default Users (from seed data)

Admin: admin@nesk.example.com
Staff: sarah.tech@nesk.example.com
Staff: mike.support@nesk.example.com

Note: Create passwords via signup flow or update roles in Prisma Studio

🏗️ Architecture

Project Structure

nesk/
├── src/
│   ├── app/
│   │   ├── actions/          # Server Actions (type-safe mutations)
│   │   ├── admin/            # Admin panel pages
│   │   ├── staff/            # Staff dashboard pages
│   │   ├── auth/             # Authentication flows
│   │   ├── tickets/          # Public ticket pages
│   │   ├── kb/               # Knowledge base
│   │   └── api/              # API routes
│   ├── components/           # Reusable React components
│   ├── lib/                  # Utilities & configurations
│   │   ├── auth.ts           # Better Auth setup
│   │   ├── auth-client.ts    # Client-side auth hooks
│   │   ├── i18n.tsx          # Client i18n provider & hooks
│   │   ├── i18n-server.ts    # Server-side locale detection
│   │   ├── prisma.ts         # Prisma client instance
│   │   └── email.ts          # Email service
│   ├── locales/              # Translation JSON files (en, ar, es, fr)
│   ├── prisma/
│   │   ├── schema.prisma     # Database schema
│   │   └── seed.ts           # Sample data seeder
│   └── types/                # TypeScript type definitions
├── public/                   # Static assets
└── prisma.config.ts          # Prisma configuration

Key Design Patterns

Server Components - Default for data fetching and SEO
Client Components - Interactive UI with "use client" directive
Server Actions - Type-safe form submissions and mutations
Route Handlers - RESTful API endpoints for Better Auth
Middleware - Session validation and route protection

Database Schema Highlights

User (Better Auth)
├── Tickets (Customer support requests)
├── Accounts (OAuth providers)
└── Sessions (Active user sessions)

Ticket
├── Category (Categorization)
├── Priority (Urgency levels)
└── TicketReply (Conversation threads)

KbArticle (Knowledge base)
├── Category
└── TeamMember (Author)

Settings (System configuration)
EmailTemplate (Notification templates)

🏗️ Routes & Navigation

Public Routes

/ - Homepage with KB search and ticket submission
/kb - Knowledge base articles listing
/kb/[id] - View individual KB article
/tickets/submit - Submit new support ticket
/tickets/status - Check ticket status by ID and email

Authentication Routes

/auth/signin - User login (with CAPTCHA protection)
/auth/signup - User registration (with CAPTCHA protection)
/auth/forgot-password - Password reset request
/auth/reset-password - Set new password

Staff Portal (Protected)

/staff - Dashboard with ticket overview and statistics
/staff/tickets - All tickets with filtering and search
/staff/tickets/[id] - Individual ticket view and management
/staff/kb - Knowledge base management
/staff/kb/new - Create new KB article
/staff/kb/edit/[id] - Edit existing KB article

Admin Panel (Protected)

/admin - Admin dashboard with analytics
/admin/team - Team member management (roles, permissions)
/admin/categories - Ticket and KB category management
/admin/email-templates - Email notification templates
/admin/settings - System configuration (email, security, etc.)
/admin/reports - Performance analytics and metrics

📊 Database Schema

Core Models

User - Customer accounts (with Better Auth)
TeamMember - Staff user accounts (email, name, role)
Ticket - Support tickets (status, priority, category, replies)
TicketReply - Ticket messages and notes (internal/public)
TicketAttachment - File attachments on tickets
KbArticle - Knowledge base articles (title, content, keywords, status)
Category - Categorization for tickets and KB articles
Priority - Ticket priority levels (Low, Medium, High, Critical)
Settings - System configuration (key-value pairs)
EmailTemplate - Customizable email notification templates

Database Commands

# Generate Prisma Client
bun run db:generate

# Create migration
bun run db:migrate

# Push schema (dev only)
bun run db:push

# Open Prisma Studio (GUI)
bun run db:studio

# Seed database with sample data
bun run db:seed

🎨 Development Workflow

Theme Management

The application includes built-in dark/light theme support powered by next-themes:

Theme Toggle: Located in the top navbar on all pages
Persistence: User preference is saved to localStorage
System Detection: Defaults to OS preference (dark/light) on first visit
Override: Users can manually toggle theme which persists across sessions
Coverage: All pages, components, and custom styles support both themes

Language Support

The application supports multiple languages with a complete i18n infrastructure:

Supported Languages: English (en), Arabic (ar), Spanish (es), French (fr)
Language Switcher: Dropdown selector in the navbar for easy switching
Persistence: Selected language saved in cookies and persists across sessions
Auto-Detection: Falls back to browser's Accept-Language header
Locale-Aware: Date/time formatting respects the selected language
Complete Coverage: All UI strings, labels, and messages are fully translated
Translation Files: Located in src/locales/ as JSON dictionaries

Code Quality

# Lint & format check
bun run lint

# Auto-fix formatting
bun run format

Environment-Specific Configs

Development: Console logging for emails, hot reload enabled
Production: Real email sending via Resend, optimized builds

🔒 Security Features

✅ Password hashing with bcrypt
✅ Math-based CAPTCHA on authentication forms to prevent bot abuse
✅ CSRF protection via Better Auth
✅ SQL injection prevention via Prisma
✅ XSS protection via React's built-in escaping
✅ Role-based access control (RBAC)
✅ Secure session management
✅ Email verification workflow
✅ Password reset with token expiration
✅ Graceful fallback when email service is unavailable (logs user intent instead of sending)

🚢 Deployment

Recommended Platforms

Vercel - Zero-config deployment for Next.js
Railway - Simple PostgreSQL hosting
Render - Full-stack deployments
Fly.io - Global edge deployment

Production Checklist

Set NODE_ENV=production
Configure production database URL
Set secure BETTER_AUTH_SECRET
Enable real email sending (Resend API key)
Run database migrations
Set up monitoring (Sentry, LogRocket)
Configure CDN for static assets

🤝 Contributing

Contributions are welcome! This project demonstrates:

Modern Next.js 16 patterns
Production-grade TypeScript
Clean architecture principles
Comprehensive feature implementation

📝 License

MIT License - feel free to use this project for learning or commercial purposes.

📝 Implementation Highlights

Phase 1: Foundation ✅

Next.js 16 with App Router setup
PostgreSQL + Prisma ORM configuration
Tailwind CSS v4 + shadcn/ui components

Phase 2: Customer Portal ✅

Ticket submission and tracking
Knowledge base with search and categories
Email notifications (Resend integration)

Phase 3: Staff Portal ✅

Authentication system (Better Auth)
Ticket management dashboard
Knowledge base management
Team collaboration features

Phase 4: Admin Features ✅

Role-based access control (Admin, Agent, User)
Team member management
Email template customization
System settings and configuration
Analytics and reporting dashboard

Phase 5: Dark/Light Theme ✅

System preference detection
Theme toggle with persistent storage
Full application coverage

Phase 6: Internationalization (i18n) ✅

Multi-language support (English, Arabic, Spanish, French)
Language switcher with cookie-based persistence
Server-side locale detection from Accept-Language header
Fully translated UI across all pages and components
Locale-aware date/time formatting
Translation infrastructure with JSON dictionaries

Phase 7: Coming Soon

File attachments (Cloudflare R2)
SLA tracking and automation
Customer satisfaction surveys
Additional language support

🙏 Acknowledgments

Built with:

Next.js - React framework
Better Auth - Authentication
Prisma - Database ORM
Tailwind CSS - Styling
React Quill - Rich text editor

Made with ❤️ using Next.js 16 and React 19

⭐ Star this repo if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
public		public
src		src
.gitignore		.gitignore
PROJECT_STATUS.md		PROJECT_STATUS.md
README.md		README.md
SETUP.md		SETUP.md
biome.json		biome.json
bun.lock		bun.lock
next.config.ts		next.config.ts
package.json		package.json
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🎫 NESK Help Desk

✨ Features

🎯 Core Functionality

👥 User Portal

🛠️ Staff Dashboard

⚙️ Admin Panel

🔐 Security & Auth

🚀 Tech Stack

Frontend

Backend

Database & Infrastructure

Developer Experience

🏃 Quick Start

Prerequisites

Installation

Default Users (from seed data)

🏗️ Architecture

Project Structure

Key Design Patterns

Database Schema Highlights

🏗️ Routes & Navigation

Public Routes

Authentication Routes

Staff Portal (Protected)

Admin Panel (Protected)

📊 Database Schema

Core Models

Database Commands

🎨 Development Workflow

Theme Management

Language Support

Code Quality

Environment-Specific Configs

🔒 Security Features

🚢 Deployment

Recommended Platforms

Production Checklist

🤝 Contributing

📝 License

📝 Implementation Highlights

Phase 1: Foundation ✅

Phase 2: Customer Portal ✅

Phase 3: Staff Portal ✅

Phase 4: Admin Features ✅

Phase 5: Dark/Light Theme ✅

Phase 6: Internationalization (i18n) ✅

Phase 7: Coming Soon

🙏 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages