# Deployment Guidance

This release is designed for a public demo, not a production launch. It can be deployed as two services: a Node API and a static web app.

## Build commands

From the repository root:

```bash
npm install
npm run build
```

This creates:

- `packages/shared/dist`
- `apps/api/dist`
- `apps/web/dist`

## API deployment

Recommended services:

- Render Web Service
- Railway Service
- Fly.io Node app
- Heroku-style Node runtime

### API settings

Working directory:

```text
apps/api
```

Build command from repository root:

```bash
npm install && npm run build -w @fan-passport/shared && npm run build -w @fan-passport/api
```

Start command:

```bash
npm start -w @fan-passport/api
```

Environment variables:

```text
PORT=4000
HOST=0.0.0.0
CORS_ORIGIN=https://YOUR_WEB_DEMO_DOMAIN
```

If the platform injects `PORT`, use the injected value and do not hard-code `4000`.

### API persistence warning

`DemoStore` is in-memory. This is intentional for a resettable public demo. For production:

1. Keep the shared API contracts.
2. Replace `DemoStore` with a database-backed store.
3. Persist users, collections, trivia answers, predictions, memories, achievements, badges, and challenge completions.
4. Add authentication and rate limiting.

## Web deployment

Recommended services:

- Vercel static build
- Netlify static build
- Cloudflare Pages
- Render Static Site

Working directory:

```text
apps/web
```

Build command from repository root:

```bash
npm install && npm run build
```

Publish directory:

```text
apps/web/dist
```

Environment variable:

```text
VITE_API_BASE_URL=https://YOUR_API_DOMAIN/api
```

The web build bakes `VITE_API_BASE_URL` into the client bundle. Set it before building.

## Single-domain option

If deploying API and web behind one reverse proxy:

- Serve `apps/web/dist` at `/`
- Proxy `/api/*` to the Node API
- Set `VITE_API_BASE_URL=/api`
- Set API `CORS_ORIGIN` to the public origin, or rely on same-origin requests

Example reverse-proxy routing:

```text
/        -> static web dist
/api/*   -> Node API
```

## Public demo hardening

Before sharing widely:

- [ ] Run `npm run release:check`
- [ ] Run `npm run test:e2e`
- [ ] Confirm CORS origin matches the deployed web domain
- [ ] Confirm reset endpoint is acceptable for the public demo environment
- [ ] Confirm the API process memory limit is enough for expected demo traffic
- [ ] Add platform-level request logging
- [ ] Add uptime monitoring for `/api/health`
- [ ] Generate and commit a real `package-lock.json` from `npm install`
- [ ] Replace demo fixture copy if official data usage rights require changes

## Suggested production evolution

The milestone intentionally leaves production concerns behind stable interfaces. The next production phase should add:

- Authenticated accounts
- Database migrations
- Admin content management
- Prediction settlement jobs
- Push/email notification hooks
- Anti-cheat checks for leaderboards
- CDN-hosted badge and sticker art
- Analytics events for retention funnels