nicolabs/mosh-helpdesk
1
0
Fork 0
mirror of https://github.com/mosh-hamedani/helpdesk.git synced 2026-05-21 11:58:19 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
mosh-helpdesk/README.md
avosa a6b469ad1b
docs: add missing Prisma generate step to setup instructions 
Updated the README to include `prisma generate` in the database setup steps. 
This ensures the Prisma client is generated before running the seed command, preventing module resolution errors during initial setup.
2026-04-17 15:50:41 -04:00

3.6 KiB
Raw Blame History

Helpdesk

This project is built as part of my Claude Code course, showing how to build and ship a production-ready full-stack app with AI-assisted development.

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 generate
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