# QuitSure Quiz Funnel — Deployment Guide

## For the backend team to deploy to test server

---

## Prerequisites

- Python 3.9+
- pip

## Quick Start

```bash
# 1. Clone / copy the project
cd quitsure-chatbot-onboarding

# 2. Install dependencies
pip install -r requirements.txt

# 3. Create .env file with API keys
cp .env.example .env
# Edit .env and add your Gemini API key

# 4. Run the server
python -m uvicorn app:app --host 0.0.0.0 --port 8080

# 5. Open http://your-server:8080
```

## Environment Variables

Create a `.env` file in the project root:

```
GEMINI_API_KEY=your_gemini_api_key_here
```

To get a Gemini API key:
1. Go to https://aistudio.google.com/apikey
2. Sign in with Google account
3. Click "Create API key"
4. Copy the key

## File Structure

```
quitsure-chatbot-onboarding/
├── app.py                  ← FastAPI backend (start here)
├── requirements.txt        ← Python dependencies
├── .env                    ← API keys (NOT committed to git)
├── .env.example            ← Template for .env
├── .gitignore              
├── templates/
│   └── index.html          ← Full frontend (CSS + HTML + JS inline)
├── static/
│   ├── facts.json          ← Content library (smoker types, denial patterns, etc.)
│   ├── quincy-avatar.png   ← Quincy's avatar image
│   ├── logo-horiz-white.png← QuitSure logo (white, for teal backgrounds)
│   └── icon.png            ← Favicon
├── CLAUDE.md               ← Full project documentation
├── DEPLOYMENT.md           ← This file
└── FLOW_MAP.html           ← Visual flow map (open in browser to review questions)
```

## Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/` | Serves the quiz page |
| POST | `/api/chat` | LLM endpoint — Quincy's responses |
| POST | `/api/profile` | Server-side classification (smoker type, probability, program routing) |
| POST | `/api/complete` | Receives final user data (currently logs to console) |

## Configuration

### Port
Default: 8080. Change with: `--port 3000`

### Workers
For production, use multiple workers:
```bash
uvicorn app:app --host 0.0.0.0 --port 8080 --workers 4
```
Note: `--reload` is for development only. Do NOT use in production.

### HTTPS
The server runs HTTP. Use a reverse proxy (nginx, Caddy) for HTTPS in production.

## What `/api/complete` Should Do (for production)

Currently the `/api/complete` endpoint just logs the user data to console. For production, it should:

1. Save user data to the QuitSure database:
   - `name`, `age`, `gender` → `tbl_Users`
   - `email` → for retargeting / email campaigns
   - `smoker_type`, `program` → for program routing
   - `cigs_per_day`, `triggers`, `fears` → `tbl_UserData`

2. Redirect to the correct subscription page:
   - If `profile.program === 'six_day'` → route to Program 3 (iProgramId=3) paywall
   - If `profile.program === 'sixteen_week'` → route to Program 9 (iProgramId=9) paywall

3. Pass the user's data to the paywall for personalization

## Rate Limiting

Basic in-memory rate limiter: 30 requests per 60 seconds per IP. For production, consider:
- Redis-based rate limiting
- Cloudflare rate limiting at the edge
- Per-user (not per-IP) limits after email capture

## Testing

Open FLOW_MAP.html in a browser to see the full question flow visually.

Run the server and test:
```bash
# Test profile classification
curl -s http://localhost:8080/api/profile \
  -H "Content-Type: application/json" \
  -d '{"cigs_per_day":15,"first_cig_minutes":20,"readiness":7,"likes_about_smoking":["relax"],"triggers":["stress","work"]}' \
  | python -m json.tool

# Test LLM
curl -s http://localhost:8080/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"I smoke 10 a day","context":"Acknowledge","userData":{"name":"Test"},"stage":"test","conversation":[]}' \
  | python -m json.tool
```

## Known Limitations

- No session persistence — refresh = restart
- In-memory rate limiting resets on server restart
- No CORS middleware (add if frontend is on different domain)
- No authentication on endpoints
- Email is captured but not sent anywhere yet