> ## Documentation Index
> Fetch the complete documentation index at: https://blue-chip.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

# Getting Started

## Prerequisites

* Python 3.13+ and [uv](https://docs.astral.sh/uv/)
* Docker + Docker Compose (optional)
* A Supabase project with asymmetric JWT signing keys and the migrations in `supabase/migrations/` applied

## Configure

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.