HackathonFeed Backend

Production REST API for the HackathonFeed platform. Sits on top of the existing Supabase hackathons table populated by the scraper pipeline.

Architecture

Frontend → FastAPI Routes → Services → Repositories → Supabase/PostgreSQL

Quick Start

1. Copy environment file:

cp .env.example .env

2. Set DATABASE_URL to your Supabase PostgreSQL connection string and configure JWT secrets.

3. Install dependencies with uv:

uv sync

4. Run database migrations (creates user tables, bookmarks, analytics, and tracked projects):

uv run alembic upgrade head

Or run database/backend_schema.sql in the Supabase SQL Editor, then verify:

uv run python scripts/verify_tables.py

5. Start the API:

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Open Swagger docs at http://localhost:8000/docs.

API Overview

Area	Endpoints
Auth	POST /api/v1/auth/register, /login, /refresh, GET /me
Users	GET/PATCH /api/v1/users/me
Hackathons	GET /api/v1/hackathons, /search, /trending, /{id}
Bookmarks	POST/GET/DELETE /api/v1/bookmarks
Tracked projects	GET/POST/PATCH/DELETE /api/v1/tracked-projects, register, steps, milestones, notes, team
Themes	GET /api/v1/themes, /themes/platforms
Trends	GET /api/v1/trends/hackathons, /themes, /platforms
Admin	GET /api/v1/admin/stats, POST /scrape, DELETE /hackathon/{id}

All successful responses follow:

{
  "success": true,
  "message": "...",
  "data": {}
}

Project Structure

• app/api/ – HTTP routes and dependencies
• app/services/ – business logic
• app/repositories/ – database access
• app/models/ – SQLAlchemy ORM models
• app/schemas/ – Pydantic DTOs
• app/core/ – config, security, database, logging
• app/middleware/ – logging and rate limiting

Notes

• The hackathons table is owned by the scraper; this backend reads it and adds user-facing features.
• Redis caching and background analytics jobs can be wired through APScheduler in a later phase.
• Create an admin user by updating the role column in Supabase after registration.