Getting started

​

Getting Started

​

Prerequisites

• Python 3.13+ and uv
• Docker + Docker Compose (optional)
• A Supabase project with asymmetric JWT signing keys and the migrations in supabase/migrations/ applied

​

Configure

cp apps/api/.env.example apps/api/.env.development

Required: SUPABASE_URL and POSTGRES_* (Supabase session pooler). Account deletion also requires SUPABASE_SERVICE_ROLE_KEY.

​

Option A: Docker

From the repo root:

make install
make docker-up     # Postgres, Temporal dev server, API (port 8000), worker
make stack-up      # Full stack: adds Prometheus, Grafana, cAdvisor

The Compose db is plain Postgres (pgvector/pgvector:pg16) without Supabase’s auth and storage schemas. Point POSTGRES_* at your Supabase database, where the migrations are applied.

​

Option B: Local processes

From the repo root:

make dev            # API with hot reload on port 8000
make worker         # optional Temporal worker boilerplate

​

Your first requests

Sign in through the web app to get a Supabase access token, then:

TOKEN=<supabase access token>
API=http://localhost:8000/api/v1

# Health (no token)
curl -s http://localhost:8000/health

# The caller's profile
curl -s $API/profile -H "Authorization: Bearer $TOKEN"

# Update the caller's profile
curl -s -X PATCH $API/profile \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "Alex"}'

# List organizations from the discovery view
curl -s "$API/organizations?sort=momentum&limit=20" -H "Authorization: Bearer $TOKEN"

# Top-growing organizations over a rolling window
curl -s "$API/metrics/velocity?metric_type=github_stars&days=90" -H "Authorization: Bearer $TOKEN"

# Delete the caller's account
curl -X DELETE $API/account -H "Authorization: Bearer $TOKEN"

​

Code quality

make check   # API ruff (lint + format-check) + pyright + pytest, plus web checks

​

Troubleshooting

401 on every request SUPABASE_URL is missing or wrong, or the project still signs HS256 tokens.

could not translate host name "db" POSTGRES_HOST=db only resolves inside Compose. On the host, use localhost or your Supabase host.

detect-secrets blocking a commit If it’s a false positive, add # pragma: allowlist secret to the flagged line.