Helpdesk

An AI-powered ticket management system that automatically classifies, responds to, and routes support tickets.

Features

• Receive support emails and create tickets via SendGrid inbound parse
• AI-powered ticket classification (General Question, Technical Question, Refund Request)
• AI-suggested replies and summaries
• Ticket list with filtering and sorting
• Ticket detail view with reply thread
• User management (admin only)
• Dashboard with stats

Tech Stack

• Frontend: React, TypeScript, Vite, shadcn/ui, TanStack Query
• Backend: Express 5, TypeScript, Bun
• Database: PostgreSQL, Prisma ORM
• AI: OpenAI GPT via Vercel AI SDK
• Auth: Better Auth (email/password, database sessions)
• Job Queue: pg-boss
• Error Tracking: Sentry
• Email: SendGrid (inbound + outbound)

Project Structure

client/   - React frontend (Vite)
server/   - Express backend
core/     - Shared code (Zod schemas, types, constants)
e2e/      - Playwright E2E tests

Prerequisites

• Bun (runtime and package manager)
• PostgreSQL

Getting Started

1. Install dependencies

   bun install
   

2. Set up environment variables

   cp server/.env.example server/.env
   cp client/.env.example client/.env
   

   Edit server/.env and fill in the required values. At minimum:

   • DATABASE_URL - PostgreSQL connection string
   • BETTER_AUTH_SECRET - generate with openssl rand -base64 32
   • OPENAI_API_KEY - for AI features

3. Set up the database

   cd server
   bunx prisma migrate dev
   bunx prisma db seed
   

4. Start the dev servers

   # Terminal 1 - backend
   cd server && bun run dev
   
   # Terminal 2 - frontend
   cd client && bun run dev
   

   The client runs on http://localhost:5173 and proxies API requests to the server on port 3000.

Testing

# Component tests
cd client && bun run test

# E2E tests (requires both servers running)
bun run test:e2e

Deployment (Railway)

The app is configured for single-service deployment on Railway. The Express server serves the built React client as static files in production.

1. Build the Docker image

   docker build -t helpdesk .
   

2. Run locally with Docker

   docker run -p 3000:3000 --env-file server/.env -e NODE_ENV=production helpdesk
   

3. Deploy to Railway

   • Create a new project and link this repo
   • Add a PostgreSQL database
   • Set the required environment variables (see server/.env.example)
   • After the first deploy, seed the database:

     railway run -- bun run --cwd server prisma db seed
     

Required Environment Variables (Production)

Variable	Description
DATABASE_URL	PostgreSQL connection string (auto-provided by Railway)
BETTER_AUTH_SECRET	Auth secret key
BETTER_AUTH_URL	App URL (e.g. https://yourapp.up.railway.app)
TRUSTED_ORIGINS	Same as BETTER_AUTH_URL
WEBHOOK_SECRET	For inbound email webhook verification
OPENAI_API_KEY	OpenAI API key for AI features
SENDGRID_API_KEY	SendGrid API key for outbound email
SENDGRID_FROM_EMAIL	Verified sender email address
SEED_ADMIN_EMAIL	Initial admin user email
SEED_ADMIN_PASSWORD	Initial admin user password

Optional: SENTRY_DSN, SENTRY_ENVIRONMENT