DEPLOY.md

# Deployment Guide — CourtMitra MissionOS

> **Target:** Vercel (frontend) + Hugging Face Spaces (backend + worker) + Google OAuth (Clerk) + Neon (Postgres)

---

## Architecture Overview

```
┌─────────────────────────┐         ┌──────────────────────────────────────────┐
│   Vercel (Next.js 15)   │────────▶│   Hugging Face Spaces (Docker)           │
│   - Clerk auth          │  HTTPS  │   - NestJS API + Inngest Worker          │
│   - Hero page           │         │   - Port 7860                            │
│   - Profile page        │         │                                            │
│   - Mission dashboard   │         │   /api/*  → API routes                  │
│   - Static assets       │         │   /api/inngest → Worker functions        │
└─────────────────────────┘         └────────────────────┬─────────────────────┘
                                                         │
                                                         │  postgres://...
                                                         ▼
                                            ┌────────────────────────────┐
                                            │   Neon Postgres (Cloud)    │
                                            │   - 55 tables              │
                                            │   - pgvector + FTS         │
                                            │   - Legal chunks seeded    │
                                            └────────────────────────────┘
```

---

## Env Files (Where Secrets Live)

> **Crucial for your partner:** There are TWO separate env files. One is gitignored (real secrets), the other is a committed template.

| File | In Git? | Where | Purpose |
|------|---------|-------|---------|
| `apps/web/.env.local` | ❌ **NO** — gitignored | Your laptop / partner's laptop | **Frontend local dev** — Clerk keys + API URL. You MUST create this and fill in real keys. |
| `apps/web/.env.local.example` | ✅ YES | In repo as template | Shows exactly what `.env.local` should contain. |
| `.env` | ❌ **NO** — gitignored | Your laptop / partner's laptop | **Backend local dev** — DB, AI, Inngest, secrets. Copy from `.env.example` and fill in. |
| `.env.example` | ✅ YES | In repo as template | Comprehensive backend env template. |

**What your partner needs to do before `pnpm dev`:**

1. Create `apps/web/.env.local` (copy from `apps/web/.env.local.example`)
2. Paste in `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` from Clerk dashboard
3. Create `.env` at repo root (copy from `.env.example`)
4. Fill in `DATABASE_URL`, `OPENROUTER_API_KEY`, etc.

---

## Prerequisites

| Service | Purpose | Free Tier |
|---------|---------|-----------|
| [Vercel](https://vercel.com) | Frontend hosting | Hobby (unlimited) |
| [Clerk](https://clerk.com) | Auth + Google OAuth | 10,000 MAU |
| [Hugging Face Spaces](https://huggingface.co/spaces) | Backend API + Worker | CPU Basic (free) |
| [Neon](https://neon.tech) | Postgres database | 500 MB, 200 hrs |
| [Inngest](https://inngest.com) | Background workflows | 50k events/mo |
| [OpenRouter](https://openrouter.ai) | LLM API | $5 free credits |

---

## Step 1: Clerk + Google OAuth (10 min)

1. Go to [dashboard.clerk.com](https://dashboard.clerk.com) → Create Application.
2. **Social Connections** → enable **Google**.
   - Development: toggle on (uses Clerk's shared OAuth credentials).
   - Production: add your own Google Client ID/Secret.
3. Copy keys from **API Keys** tab:
   - `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...`
   - `CLERK_SECRET_KEY=sk_test_...`
4. Add your Vercel domain to **URLs** → **Allowed Origins**:
   - `https://your-project.vercel.app`
   - `http://localhost:3000` (for local dev)

---

## Step 2: Neon Postgres (10 min)

1. [neon.tech](https://neon.tech) → New Project → copy **connection string**.
2. Run migrations from your local machine:
   ```bash
   export DATABASE_URL="postgres://courtmitra:password@host.neon.tech/courtmitra"
   export DIRECT_DATABASE_URL="$DATABASE_URL"
   pnpm db:migrate
   pnpm db:seed
   ```
3. Verify: check that `users`, `missions`, `route_rules`, `legal_chunks` tables exist.

---

## Step 3: Frontend → Vercel (5 min)

1. Push repo to GitHub.
2. Vercel → **Add New Project** → import repo.
3. Set **Environment Variables**:

   | Variable | Value | Notes |
   |----------|-------|-------|
   | `NEXT_PUBLIC_API_BASE_URL` | `https://your-hf-space.hf.space/api` | Your HF Spaces URL |
   | `INTERNAL_API_BASE_URL` | `https://your-hf-space.hf.space/api` | Same as above |
   | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | `pk_test_...` | From Clerk dashboard |
   | `CLERK_SECRET_KEY` | `sk_test_...` | From Clerk dashboard |
   | `NEXT_PUBLIC_CLERK_SIGN_IN_URL` | `/en/sign-in` | Or `/hi/sign-in` |
   | `NEXT_PUBLIC_CLERK_SIGN_UP_URL` | `/en/sign-up` | Or `/hi/sign-up` |

4. Deploy.

---

## Step 4: Backend → Hugging Face Spaces (20 min)

### 4a. Create Space
1. [huggingface.co/spaces](https://huggingface.co/spaces) → **Create new Space**.
2. **Space name:** `courtmitra-api`
3. **SDK:** `Docker`
4. **Visibility:** Public
5. **Hardware:** Free CPU

### 4b. Link GitHub Repo
In Space Settings → **Repository** → link your GitHub repo.

The `Dockerfile.hf` at repo root builds the monorepo and runs API + Worker in one container.

### 4c. Set Environment Variables

In Space → **Settings** → **Variables & Secrets**:

#### Required (App won't start without these)
```
PORT=7860
API_PORT=7860
DATABASE_URL=postgres://courtmitra:password@host.neon.tech/courtmitra
DIRECT_DATABASE_URL=postgres://courtmitra:password@host.neon.tech/courtmitra
APP_BASE_URL=https://your-hf-space.hf.space
API_BASE_URL=https://your-hf-space.hf.space
WEBHOOK_BASE_URL=https://your-hf-space.hf.space
JWT_SECRET=change-me-32-chars-minimum!!
PII_HASH_SALT=change-me-salt
TOKEN_ENCRYPTION_KEY=change-me-32-chars-minimum!!
```

#### Required for AI (Intake, route-plan, evidence parsing)
```
AI_PROVIDER=openrouter
OPENROUTER_API_KEY=sk-or-v1-...
AI_MODEL=google/gemini-2.0-flash-exp:free
AI_VISION_MODEL=google/gemini-2.0-flash-exp:free
```

#### Clerk (for JWT verification)
```
CLERK_SECRET_KEY=sk_test_...
# Optional: for networkless JWT verification (faster, no Clerk API call per request)
CLERK_JWT_KEY=...
# Optional: restrict which domains can use your API
CLERK_AUTHORIZED_PARTIES=https://your-project.vercel.app,http://localhost:3000
```

#### Optional (Email actions — Resend)
```
RESEND_API_KEY=re_...
RESEND_FROM=noreply@yourdomain.com
```

#### Optional (Inngest background workflows)
```
INNGEST_EVENT_KEY=...
INNGEST_SIGNING_KEY=...
INNGEST_BASE_URL=https://api.inngest.com
```

#### Optional (Local dev helper — NOT for production)
```
DEMO_MODE=true
```
> ⚠️ **Never set `DEMO_MODE=true` in production.** It bypasses all auth.

#### Optional (Object storage — for evidence files)
```
OBJECT_STORAGE_ENDPOINT=https://...
OBJECT_STORAGE_BUCKET=courtmitra
OBJECT_STORAGE_ACCESS_KEY=...
OBJECT_STORAGE_SECRET_KEY=...
```
> If not set, evidence files are stored locally in `/app/.storage` (lost on Space restart).

#### Optional (Other channels)
```
WHATSAPP_VERIFY_TOKEN=...
WHATSAPP_APP_SECRET=...
WHATSAPP_ACCESS_TOKEN=...
WHATSAPP_PHONE_NUMBER_ID=...
TELEGRAM_BOT_TOKEN=...
```

#### Optional (Phase 2 features — not needed for hackathon)
```
QDRANT_URL=https://...
QDRANT_API_KEY=...
QDRANT_COLLECTION=courtmitra_legal
OPENAI_API_KEY=...
BROWSERBASE_API_KEY=...
BROWSERBASE_PROJECT_ID=...
SUREPASS_API_KEY=...
ENABLE_PORTAL_AUTOMATION=1
```

### 4d. Verify

Once built, test:
```bash
curl https://your-space.hf.space/api/admin/health
# Expected: {"status":"ok","ts":"..."}

curl https://your-space.hf.space/api/capabilities
# Expected: JSON with adapter capabilities

curl https://your-space.hf.space/api/inngest
# Expected: Inngest registration JSON
```

---

## Step 5: Wire Frontend → Backend

1. In Vercel dashboard, update:
   ```
   NEXT_PUBLIC_API_BASE_URL=https://your-hf-space.hf.space/api
   ```
2. Redeploy frontend.

---

## Complete Environment Variable Reference

### Vercel (Frontend)

| Variable | Required | Description |
|----------|----------|-------------|
| `NEXT_PUBLIC_API_BASE_URL` | ✅ | HF Spaces API URL |
| `INTERNAL_API_BASE_URL` | ✅ | Same as above (for SSR) |
| `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | ✅ | Clerk public key |
| `CLERK_SECRET_KEY` | ✅ | Clerk secret key |
| `NEXT_PUBLIC_CLERK_SIGN_IN_URL` | ✅ | `/en/sign-in` |
| `NEXT_PUBLIC_CLERK_SIGN_UP_URL` | ✅ | `/en/sign-up` |

### Hugging Face Spaces (Backend)

| Variable | Required | Description |
|----------|----------|-------------|
| `PORT` | ✅ | Must be `7860` |
| `API_PORT` | ✅ | Must be `7860` |
| `DATABASE_URL` | ✅ | Neon connection string |
| `DIRECT_DATABASE_URL` | ✅ | Same as `DATABASE_URL` |
| `APP_BASE_URL` | ✅ | HF Spaces URL |
| `API_BASE_URL` | ✅ | Same |
| `WEBHOOK_BASE_URL` | ✅ | Same |
| `JWT_SECRET` | ✅ | Min 32 chars |
| `PII_HASH_SALT` | ✅ | Any string |
| `TOKEN_ENCRYPTION_KEY` | ✅ | Min 32 chars |
| `AI_PROVIDER` | ✅ | `openrouter` or `opencode` |
| `OPENROUTER_API_KEY` | ✅ | If `AI_PROVIDER=openrouter` |
| `AI_MODEL` | ✅ | e.g. `google/gemini-2.0-flash-exp:free` |
| `AI_VISION_MODEL` | ✅ | e.g. `google/gemini-2.0-flash-exp:free` |
| `CLERK_SECRET_KEY` | ✅ | Same as Vercel |
| `CLERK_JWT_KEY` | ⬜ | Optional, for faster JWT verification |
| `RESEND_API_KEY` | ⬜ | For email actions |
| `RESEND_FROM` | ⬜ | Sender email |
| `INNGEST_EVENT_KEY` | ⬜ | For background workflows |
| `INNGEST_SIGNING_KEY` | ⬜ | For background workflows |
| `LOCAL_STORAGE_DIR` | ⬜ | Defaults to `/app/.storage` |
| `DEMO_MODE` | ⬜ | `true` = bypass auth (dev only!) |

---

## Quick Smoke Test

After deploying both services:

1. Open Vercel URL → click **Sign In** → choose **Google**.
2. After signing in, you should see your avatar in the top-right.
3. On the hero page, click **Get Started** → create a mission.
4. Visit `/{locale}/profile` → you should see:
   - Your Google name + email + avatar
   - Editable phone number
   - Language preference dropdown
   - Your mission listed under "My Missions"
5. The API calls should show `200 OK` in browser DevTools Network tab with `Authorization: Bearer <token>` header.

---

## For Your Partner: Quick Local Dev Setup

**Before they can run `pnpm dev`, they MUST create two env files:**

### 1. Frontend env: `apps/web/.env.local`

Create this file (it's gitignored, so it won't exist after clone):

```bash
cp apps/web/.env.local.example apps/web/.env.local
```

Then paste in your Clerk keys:
```
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...   # from Clerk dashboard
CLERK_SECRET_KEY=sk_test_...                    # from Clerk dashboard
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/en/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/en/sign-up
NEXT_PUBLIC_API_BASE_URL=http://localhost:3001/api
INTERNAL_API_BASE_URL=http://localhost:3001/api
```

### 2. Backend env: `.env` (at repo root)

```bash
cp .env.example .env
```

Fill in at minimum:
```
DATABASE_URL=postgres://courtmitra:courtmitra@localhost:5432/courtmitra
DIRECT_DATABASE_URL=postgres://courtmitra:courtmitra@localhost:5432/courtmitra
OPENROUTER_API_KEY=sk-or-v1-...
AI_PROVIDER=openrouter
AI_MODEL=google/gemini-2.0-flash-exp:free
AI_VISION_MODEL=google/gemini-2.0-flash-exp:free
CLERK_SECRET_KEY=sk_test_...
JWT_SECRET=change-me-32-chars-minimum!!
PII_HASH_SALT=change-me-salt
TOKEN_ENCRYPTION_KEY=change-me-32-chars-minimum!!
```

### 3. Run it

```bash
# Terminal 1: start Postgres + Inngest
pnpm infra:up

# Terminal 2: migrate and seed
pnpm db:migrate
pnpm db:seed

# Terminal 3: run all apps
pnpm dev
```

- Web: http://localhost:3000
- API: http://localhost:3001/api
- Inngest Dev: http://localhost:8288

**No Clerk keys yet?** Add `DEMO_MODE=true` to `.env` to bypass auth for local testing.

---

## Local Development

```bash
# 1. Start local Postgres + Inngest
pnpm infra:up

# 2. Copy env and fill in keys
cp .env.example .env
# Edit .env with your keys

# 3. Run everything
pnpm dev
```

- Web: http://localhost:3000
- API: http://localhost:3001/api
- Inngest Dev Server: http://localhost:8288

**For local dev without Clerk keys**, add to `.env`:
```
DEMO_MODE=true
```

---

## Troubleshooting

### HF Space build fails
- Check **Factory Logs** in HF dashboard.
- Common: `pnpm` not found → Dockerfile installs via `corepack`.
- Common: out of disk → free tier has ~50GB. Dockerfile strips `next`/`react` packages.

### API returns 401 Unauthorized
- Make sure `CLERK_SECRET_KEY` is set in HF Space.
- Make sure frontend sends `Authorization: Bearer <token>` header (check DevTools).
- If testing with curl, you need a valid Clerk JWT token.

### API returns 500
- Check HF **Application Logs**.
- Common: `DATABASE_URL` not set → can't connect to Neon.
- Common: `OPENROUTER_API_KEY` not set → AI endpoints fail.
- Common: `JWT_SECRET` too short → must be ≥32 characters.

### CORS errors from frontend
- API has `app.enableCors({ origin: true })` which reflects the request origin.
- If still blocked, add your Vercel domain explicitly in `apps/api/src/main.ts`.

### Clerk sign-in fails
- Verify `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` are set in Vercel.
- In Clerk Dashboard → **Social Connections** → **Google** must be enabled.
- Add your Vercel domain to Clerk Dashboard → **URLs** → **Allowed Origins**.

### Background workflows not running
- HF free-tier Spaces **sleep after inactivity**. When the Space sleeps, Inngest can't invoke your worker.
- **Fix:** Use a paid HF Space (Always On), or use Inngest's `serve` with a keep-alive ping.
- Alternatively: trigger workflows manually via API for demo purposes.

### Database connection errors
- Neon databases have a **connection limit**. If you see "too many clients", restart the HF Space.
- Use Neon's **connection pooling** (add `?pgbouncer=true` to connection string).

---

## Known Limitations

| Feature | Status |
|---------|--------|
| Google OAuth + user profiles | ✅ Works |
| Mission CRUD (user-scoped) | ✅ Works |
| Evidence upload | ✅ Works (if storage configured) |
| Background AI workflows | ⚠️ Needs Inngest + always-on Space |
| Email sending | ⚠️ Needs Resend key |
| WhatsApp/Telegram | ❌ Needs Meta Business verification (days) |
| Portal automation | ❌ Phase 2 only |

---

## Security Checklist

Before going live:
- [ ] `DEMO_MODE` is NOT set (or set to `false`)
- [ ] `JWT_SECRET` is ≥32 random characters
- [ ] `TOKEN_ENCRYPTION_KEY` is ≥32 random characters
- [ ] `CLERK_JWT_KEY` is set (optional but recommended for performance)
- [ ] Database uses SSL (Neon does this by default)
- [ ] HF Space is set to **private** if you don't want public API access
- [ ] Vercel domain is in Clerk's **Allowed Origins**

---

*Good luck at the hackathon! 🚀*