DEPLOYMENT.md

# Deploying BREATHE — Completely Free

This guide deploys the app using:
| Layer | Service | Cost |
|---|---|---|
| Frontend (React/Vite) | **Vercel** | Free forever |
| Backend (Flask API) | **Render** | Free tier |
| Database | **Supabase** | Free tier (500MB) |

> **Note on ML models:** PyTorch and the transformer models require ~1–2 GB RAM. Render's free tier provides only 512 MB. The app will run without the ML features on the free tier — assessments and auth still work. To enable ML inference for free, see [Option B: Hugging Face Spaces](#option-b-ml-on-hugging-face-spaces-free) below.

---

## Prerequisites

- A [GitHub](https://github.com) account (push your project there first)
- Accounts on [Vercel](https://vercel.com), [Render](https://render.com), [Supabase](https://supabase.com) — all free to sign up

---

## Step 1 — Push to GitHub

```bash
cd breathe-app
git init
git add .
git commit -m "Initial commit"
# Create a repo on github.com, then:
git remote add origin https://github.com/YOUR_USERNAME/breathe-app.git
git push -u origin main
```

Make sure `.env` is in `.gitignore` (never commit secrets).

---

## Step 2 — Set up the Database on Supabase (free)

1. Go to [supabase.com](https://supabase.com) → **New Project**
2. Give it a name (e.g. `breathe`) and set a database password
3. Once created, go to **Project Settings → Database**
4. Copy the **Connection string (URI)** — it looks like:
   ```
   postgresql://postgres:[PASSWORD]@db.xxxx.supabase.co:5432/postgres
   ```
5. Save this — you'll need it in Steps 3 and 4.

---

## Step 3 — Deploy the Backend on Render (free)

1. Go to [render.com](https://render.com) → **New → Web Service**
2. Connect your GitHub repo
3. Configure the service:
   | Setting | Value |
   |---|---|
   | **Root Directory** | `breathe-app` |
   | **Runtime** | Python 3 |
   | **Build Command** | `pip install -r requirements.txt` |
   | **Start Command** | `gunicorn app:app` |
   | **Instance Type** | Free |

4. Under **Environment Variables**, add:
   ```
   FLASK_APP=app.py
   FLASK_DEBUG=false
   SECRET_KEY=<run: python -c "import secrets; print(secrets.token_hex(32))">
   DATABASE_URL=<your Supabase connection string from Step 2>
   ```

5. Click **Create Web Service** — Render will build and deploy.
6. Your backend URL will be: `https://your-service-name.onrender.com`

> ⚠️ Free tier services spin down after 15 minutes of inactivity and take ~30s to wake up on the next request. This is normal.

---

## Step 4 — Deploy the Frontend on Vercel (free)

1. Go to [vercel.com](https://vercel.com) → **Add New Project**
2. Import your GitHub repo
3. Configure the project:
   | Setting | Value |
   |---|---|
   | **Root Directory** | `breathe-app/frontend` |
   | **Framework Preset** | Vite |
   | **Build Command** | `npm run build` |
   | **Output Directory** | `dist` |

4. Under **Environment Variables**, add:
   ```
   VITE_API_URL=https://your-service-name.onrender.com
   ```

5. Click **Deploy** — Vercel builds and publishes instantly.
6. Your app will be live at: `https://your-project.vercel.app`

---

## Option C — Deploy on Hugging Face Spaces with Docker

This repository now includes a root-level `Dockerfile` so you can deploy the full app as one Docker Space.

1. Go to [huggingface.co/spaces](https://huggingface.co/spaces) → **Create new Space**
2. Choose **Docker** as the SDK
3. Push or upload this repository to the Space
4. In Space settings, add environment variables:
   ```
   SECRET_KEY=<a strong random value>
   DATABASE_URL=<optional postgres connection string>
   PSYCHO_MODEL_DIR=models/psychometric
   ROBERTA_CKPT=models/text/roberta-model.pt
   ```

5. Build the Space. The app will start on port `7860` and serve both the React frontend and Flask API from the same domain.

> Note: If model files are missing, the app falls back to demo mode for assessments.

---

## Step 5 — Update the API Client

In `frontend/src/api/client.js`, make sure the base URL reads from the env variable:

```js
const BASE_URL = import.meta.env.VITE_API_URL || ''
```

Redeploy the frontend after making this change.

---

## Option B: ML on Hugging Face Spaces (free)

If you want the full ML-powered assessments for free:

1. Go to [huggingface.co/spaces](https://huggingface.co/spaces) → **Create new Space**
2. Choose **Docker** as the SDK
3. Upload:
   - `app.py`, `backend/`, `models/`, `requirements.txt`
   - A `Dockerfile` (see below)
4. Add the same environment variables in the Space settings

**Dockerfile for Hugging Face:**
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["gunicorn", "--bind", "0.0.0.0:7860", "app:app"]
```

HF Spaces provides 2 CPU cores and 16 GB RAM on the free tier — enough for the ML models.

---

## Summary

| Step | Action | Time |
|---|---|---|
| 1 | Push code to GitHub | 5 min |
| 2 | Create Supabase database, copy connection string | 5 min |
| 3 | Deploy Flask backend on Render | 10 min |
| 4 | Deploy React frontend on Vercel | 5 min |
| 5 | Set `VITE_API_URL` and redeploy frontend | 2 min |

Total: ~30 minutes, $0.