Hack-A-Cure

Hack-A-Cure is a full-stack evaluation platform for RAG-based healthcare assistants.

It includes:

• a Next.js client for authentication, team dashboard, submissions, and leaderboard
• a FastAPI server that queues and runs automated RAG evaluations in the background

---

What this project does

Teams submit a public RAG endpoint. The server evaluates it on sampled QA pairs and computes quality metrics (via RAGAS-oriented workflow), while the client shows team progress and leaderboard information.

High-level flow:

1. Team signs in and submits their endpoint URL.
2. Server creates an evaluation job and enqueues it in Redis/RQ.
3. Worker processes questions, calls participant endpoint, and computes metrics.
4. Results are stored in MongoDB.
5. Client fetches and displays scores/submission status.

---

Monorepo structure

HackACure/
├─ client/                     # Next.js + TypeScript frontend
│  ├─ src/app/                 # App Router pages and API routes
│  ├─ src/components/          # UI components
│  ├─ src/db/                  # MongoDB connection (mongoose)
│  ├─ src/lib/                 # Auth, API helpers, shared utilities
│  ├─ src/models/              # Client-side Mongo user model
│  └─ src/stores/              # Zustand state stores
├─ server/                     # FastAPI backend and evaluation worker logic
│  ├─ app/main.py              # API entrypoint
│  ├─ app/models/              # Pydantic + Beanie schemas
│  ├─ app/services/            # Queue, tasks, LLM, evaluation logic
│  └─ scripts/                 # Utility scripts (e.g., dataset extraction)
└─ README.md                   # You are here

---

Tech stack

Client (client/)

• Next.js 15 (App Router, TypeScript)
• NextAuth (Credentials provider)
• Mongoose
• Tailwind CSS + Radix UI primitives + Zustand

Server (server/)

• FastAPI + Uvicorn
• Redis + RQ for background jobs
• MongoDB + Beanie/Motor
• RAGAS-based evaluation pipeline with LLM integrations

---

Prerequisites

• Node.js 18+
• Python 3.11+
• MongoDB 5+
• Redis 6+

---

Environment variables

Client (client/.env.local)

Minimum variables:

MONGODB_URI=mongodb://localhost:27017/hackacure
NEXTAUTH_SECRET=replace_with_a_strong_secret
NEXTAUTH_URL=http://localhost:3000

Server (server/.env)

Typical local setup:

MONGO_URI=mongodb://localhost:27017/hackacure

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
# REDIS_USERNAME=
# REDIS_PASSWORD=

GOOGLE_API_KEY=your_google_api_key
GROQ_API_KEY=your_groq_api_key
GROQ_API_MODEL=openai/gpt-oss-20b

CLIENT_URL=http://localhost:3000
RQ_QUEUE_NAME=evaluation_jobs

---

Local development

1) Start infrastructure

Make sure MongoDB and Redis are running.

2) Run backend API

cd server
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
uvicorn app.main:app --reload

Server runs on http://localhost:8000 by default.

3) Run background worker (separate terminal)

cd server
source venv/bin/activate
rq worker evaluation_jobs

4) Run frontend

cd client
npm install
npm run dev

Client runs on http://localhost:3000.

---

API overview (server)

• GET / → health/info message
• POST /jobs → create and enqueue a new evaluation job
• GET /jobs/{job_id} → fetch job status/details
• GET /jobs/team/{team_id} → list all jobs for a team

Submission payload (POST /jobs)

{
  "team_id": "team-foo",
  "submission_url": "https://your-public-endpoint.example.com/ask",
  "top_k": 5
}

---

Participant endpoint contract

The evaluated endpoint should accept a question and return answer + contexts.

Expected request body shape:

{
  "question": "...",
  "top_k": 5
}

Expected response shape:

{
  "answer": "...",
  "contexts": ["context chunk 1", "context chunk 2"]
}

---

Useful commands

Client

cd client
npm run dev
npm run build
npm run lint

Server

cd server
uvicorn app.main:app --reload
rq worker evaluation_jobs

---

Notes

• client/src/config/auth.config.ts currently exists but is empty in this workspace.
• If pip install -r requirements.txt fails, inspect server/requirements.txt for merge-conflict markers and resolve them.

---

License

Add your preferred license here (e.g., MIT) if/when the project is open-sourced.