Ticket Analyzer

A minimal full-stack web app for submitting customer support tickets, analyzing their sentiment with a Hugging Face model, and storing them in PostgreSQL. Built for the SUST CSE Carnival 2026 Codex Community Hackathon.

Overview

• Frontend: React + Vite, served by Nginx on port 80 inside the container (published as host port 3000 by Compose).
• Backend: FastAPI + Uvicorn on port 8000, with a DistilBERT sentiment model loaded once at startup.
• Database: PostgreSQL with a named Docker volume.
• Orchestration: Docker Compose (one command to run everything).

Architecture

React/Vite Frontend  ->  Nginx (:80)  -- /api/* -->  FastAPI (:8000)  ->  PostgreSQL (:5432)
                                                    |
                                                    +-> Hugging Face DistilBERT (baked into image)

Local Setup

Requirements: Docker and Docker Compose.

docker compose up --build

Then open http://localhost:3000.

To stop and remove containers (keeping the database volume):

docker compose down

To wipe the database volume too:

docker compose down -v

Environment Variables

These defaults are baked into docker-compose.yml and the Dockerfiles — change them there if needed.

Service	Variable	Default
backend	DATABASE_URL	postgresql://postgres:postgres@db:5432/ticket_db
backend	MODEL_NAME	distilbert-base-uncased-finetuned-sst-2-english
backend	HF_HOME	/opt/hf-cache
backend	TRANSFORMERS_OFFLINE	1 (no network access to HuggingFace at runtime)
frontend	VITE_API_BASE_URL	/api (build-time, baked into the React bundle)

API Reference

GET /health

Returns {"status": "ok"} when the backend is up.

POST /tickets

Body:

{ "title": "Lab VM issue", "message": "My VM is not opening.", "category": "lab" }

category is optional.

Response (the saved ticket):

{
  "id": 1,
  "title": "Lab VM issue",
  "message": "My VM is not opening.",
  "category": "lab",
  "sentiment": "NEGATIVE",
  "confidence": 0.998,
  "created_at": "2026-05-20T10:30:00"
}

GET /tickets

Returns all saved tickets, newest first.

Docker Build & Run

# Build images
docker compose build

# Run in foreground
docker compose up

# Run in background
docker compose up -d

# Push to DockerHub (replace <dockerhub-username>)
docker tag ticket-analyzer-backend <dockerhub-username>/ticket-analyzer-backend:v1
docker tag ticket-analyzer-frontend <dockerhub-username>/ticket-analyzer-frontend:v1
docker push <dockerhub-username>/ticket-analyzer-backend:v1
docker push <dockerhub-username>/ticket-analyzer-frontend:v1

The backend image bakes the Hugging Face model weights during build, so the running container does not need internet access to HuggingFace.

Deployment (AWS / Poridhi Cloud VM)

1. Push the two images to DockerHub as shown above.
2. SSH into the VM and install Docker + Docker Compose.
3. Copy docker-compose.yml to the VM.
4. On the VM, override the image names in a small override file or edit the compose file:

   services:
     backend:
       image: <dockerhub-username>/ticket-analyzer-backend:v1
     frontend:
       image: <dockerhub-username>/ticket-analyzer-frontend:v1
       ports:
         - "80:80"
     db:
       image: postgres:16-alpine
       ...

5. Run docker compose up -d.
6. Open http://<vm-public-ip> in a browser.

Project Layout

ticket-analyzer/
  PRD.md
  README.md
  docker-compose.yml
  .env.example
  backend/
    Dockerfile
    requirements.txt
    app/
      __init__.py
      main.py
      database.py
      models.py
      schemas.py
      sentiment.py
  frontend/
    Dockerfile
    nginx.conf
    package.json
    index.html
    src/
      main.jsx
      App.jsx
      styles.css

Troubleshooting

• "Failed to download model" at build time — the backend Dockerfile needs internet access to HuggingFace during docker compose build. This only happens at build; the running container does not need it (TRANSFORMERS_OFFLINE=1).
• Backend logs show DB connection errors on first start — the compose file uses a db healthcheck, so the backend waits for PostgreSQL to be ready. If you started containers out of order, run docker compose restart backend.
• Frontend cannot reach the backend — confirm Nginx is reverse-proxying /api/ to http://backend:8000/. The browser should hit /api/health and see {"status":"ok"}.
• Reset everything — docker compose down -v removes containers and the pgdata volume.

Links

• GitHub repository: add your link here
• DockerHub images: add your links here
• Live deployed URL: add your URL here