DevRadar

Open-source developer opportunity intelligence — online hackathons & free AI offers, with multi-tier verification.

---

What it is

DevRadar aggregates hackathons / challenges and AI free tiers / credits / promos, then tries to verify them against official pages when possible.

Principle	Meaning
No end-user login	Browse, filter, bookmark (localStorage), submit URLs without an account
No user API keys	Visitors never paste OpenAI/X keys into the browser
X is discovery, not truth	Social posts are Tier-3 signals; official URLs are preferred
Human-in-the-loop	Admin review queue for publish/reject (Google OAuth, optional)

This is not a claim of perfect accuracy. Listings carry verification status (verified_active, likely_active, registration_closed, …) and prize labels that may say TBA when the pool is unknown.

---

Architecture (short)

Browser (React/Vite)  →  FastAPI (/api/v1)  →  PostgreSQL
                              ↓
                     Redis · Celery (fetch queue)
                              ↓
              Connectors: official site, Devpost, MLH, RSS, X (optional)

Piece	Role in local dev
Docker Compose (infra/compose.yaml)	Postgres 5434, Redis 6379, optional MinIO 9000 — infra only
API (host, :8000)	FastAPI via uv run uvicorn
Worker (host)	Celery fetch queue — submission review, discovery, rechecks
Frontend (host, :5173)	Vite; proxies /api and /health to the API

• Frontend-only works with offline mock data; the real catalogue needs the API + Postgres.
• Celery worker required for automatic submission review: without a fetch worker, community submissions stay queued.
• Seed demo mode (recommended first run): no OpenAI / no X keys — load curated JSON into Postgres.
• Object storage default is local files under backend/data/raw (OBJECT_STORAGE_BACKEND=local). MinIO is optional if you switch to s3.

---

Quick start (full stack)

Prerequisites

• Docker Desktop (or Docker Engine + Compose)
• uv (Python 3.12+)
• Node.js 20+ and npm (CI uses Node 22)

Windows (PowerShell)

git clone https://github.com/bagusardin25/DevRadar.git
cd DevRadar
.\scripts\dev.ps1

Then three terminals:

# Terminal A — API
cd backend
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Terminal B — UI
npm run dev

# Terminal C — Celery fetch/review worker (--pool=solo required on Windows)
cd backend
uv run celery -A app.worker.celery_app worker -Q fetch -l info --pool=solo

macOS / Linux

git clone https://github.com/bagusardin25/DevRadar.git
cd DevRadar
chmod +x scripts/dev.sh
./scripts/dev.sh

Then either three terminals (same commands as above, omit --pool=solo on Linux/macOS) or:

make api       # terminal A
make frontend  # terminal B
make worker    # terminal C

URL	Purpose
http://localhost:5173/	App
http://127.0.0.1:8000/health/ready	API + Postgres + Redis

What bootstrap does

scripts/dev.ps1 / scripts/dev.sh (or make bootstrap):

1. docker compose -f infra/compose.yaml up -d
2. Creates backend/.env from backend/.env.example (random local secrets; keeps LLM_PROVIDER=disabled)
3. uv sync --all-extras + alembic upgrade head
4. Seeds demo catalogue + default aggregator sources
5. npm install if needed

Refresh catalogue after editing seed data:

cd backend
uv run python scripts/seed_listings.py --update
uv run python scripts/seed_default_sources.py

Optional re-fetch of AI offer official pages (rules; LLM if configured):

cd backend
uv run python scripts/recheck_listings.py --kind ai_offer --limit 25

Environment templates

File	Purpose
backend/.env.example	Development — copy to backend/.env (Compose ports, seed-demo)
backend/.env.production.example	Production checklist — set via host secrets; APP_ENV=production hardens startup
.env.example	Optional frontend Vite vars (VITE_*) — root .env if needed

Defaults match Compose (Postgres on host port 5434). Prefer localhost for the app URL and OAuth callback host notes (localhost ≠ 127.0.0.1 for cookies).

With APP_ENV=production the API refuses placeholder secrets and Compose DB passwords, requires HTTPS frontend/OAuth origins, sets Secure session cookies, and disables /docs. Details: SECURITY.md.

Docker notes

• Day-to-day dev: Compose for infra only (127.0.0.1 binds); API/worker/frontend run on the host (as above).

• Optional MinIO: docker compose -f infra/compose.yaml --profile object-storage up -d

• API image (secrets never baked in; non-root multi-stage build):

  docker build -f backend/Dockerfile -t devradar-api:local backend
  docker run --rm -p 127.0.0.1:8000:8000 --env-file backend/.env devradar-api:local

  Prefer a production env file from backend/.env.production.example (not the seed-demo .env). See SECURITY.md.

---

Modes of operation

Mode	Keys needed	Use case
Seed demo	None (Docker + generated secrets only)	Local try-out, OSS contributors, demos
Ingestion + LLM	LLM_API_KEY (OpenAI-compatible)	Extract structured fields from official pages
X discovery	X_BEARER_TOKEN	Find new candidate URLs (pay-per-use; optional)
Admin review	Google OAuth + ADMIN_GOOGLE_EMAILS	Approve/reject listings, catalogue CRUD

End users of a hosted instance still never need those keys — only the operator does.

---

Features (honest list)

Public

• Hackathon catalogue (search, filters, compare, bookmarks)
• AI offer catalogue
• Community Submit URL → review queue (AI initial review when worker runs)
• Email alert subscribe (needs operator email provider; default console)
• Provenance hints (source tier on cards)

Operator / admin (behind Google login)

• Review queue (with AI initial review)
• Catalogue manager (hackathons & AI offers)
• Pipeline viewer
• Sources manager

Not a production Chrome extension — the side-panel UI is a simulator / preview, not a store package.

---

CI & local checks

PRs to main run .github/workflows/ci.yml. Locally, after infra is up:

make check              # Linux/macOS — same lint/build/migrate/test order as CI
# Windows:  .\scripts\check.ps1   or   npm run check:all

CI job	Local equivalent
Secret scan (Gitleaks)	— (runs only on GitHub)
Frontend (npm ci → npm run check)	npm run check / make check-frontend
Backend (ruff → migrate → pytest)	make check-backend

Full command matrix: CONTRIBUTING.md.

---

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Preferred ways to add opportunities:

1. In-app Submit (URL → review pipeline)
2. PR against curated seed: data/manual-collection/seed_listings.json (not src/data/mockData.ts)
3. Connector / docs / bugfix PRs

---

Security

See SECURITY.md. Never commit .env or live API keys.

---

License

MIT — Copyright (c) 2026 DevRadar Contributors