miracles_in_motion/docs/QuickStart.md

# Quick Start Guide

Fast path to get the Miracles in Motion project running, tested, and deployed.

## 1. Prerequisites
| Tool | Recommended Version | Notes |
|------|---------------------|-------|
| Node.js | 20.x / 22.x | Functions runtime Standard supports node:20; local dev can use 22 |
| npm | 10+ | Bundled with recent Node |
| Azure CLI | >= 2.60 | For infra & Static Web Apps commands |
| SWA CLI (@azure/static-web-apps-cli) | latest | Local API + front-end emulation |
| Git | latest | Source control |
| WSL2 | Enabled | Shell environment (Ubuntu recommended) |

```bash
# Verify versions
node -v
npm -v
az version
```

## 2. Clone & Install
```bash
git clone https://github.com/Miracles-In-Motion/public-web.git
cd public-web
npm install --legacy-peer-deps
cd api && npm install --legacy-peer-deps && cd ..
```

## 3. Environment Setup
Create a `.env.local` (frontend) and `api/local.settings.json` (Azure Functions) as needed.

Example `.env.local` (do NOT commit secrets):
```
VITE_API_BASE=/api
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
VITE_DEFAULT_LANGUAGE=en
VITE_SUPPORTED_LANGUAGES=en,es,fr,de,zh,ar,pt,ru
```

Example `api/local.settings.json`:
```json
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "node"
  }
}
```

## 4. Run Locally (Integrated)
Use SWA CLI to serve front-end + Functions together.
```bash
npm run build:api       # Optional: compile API TypeScript
swa start http://localhost:5173 --api-location ./api --devserver-run-command "npm run dev" --api-language node
```
If you prefer two terminals:
```bash
npm run dev            # Front-end (Vite)
cd api && npm start   # Functions runtime
```

## 5. Testing
```bash
npm test                 # Front-end tests (Vitest / Testing Library)
```
Add more tests under `src/components/__tests__/` or `src/test`.

## 6. Build
```bash
npm run build            # Produces front-end dist/
cd api && npm run build  # Compiles Functions to dist (if configured)
```

## 7. Azure Deployment (Static Web App Standard)
```bash
# Login
az login

# Ensure resource group exists
az group create --name rg-mim-prod --location eastus2

# Create Static Web App (front-end + managed functions)
az staticwebapp create \
  --name mim-prod-web-standard \
  --resource-group rg-mim-prod \
  --location eastus2 \
  --source . \
  --branch main \
  --app-location / \
  --output-location dist
```

To deploy updates without GitHub Actions (manual token):
```bash
TOKEN=$(az staticwebapp secrets list --name mim-prod-web-standard --resource-group rg-mim-prod --query properties.apiKey -o tsv)
swa deploy ./dist --env production --deployment-token $TOKEN
```

## 8. Custom Domain
1. Add CNAME `www` → `<defaultHostname>`.
2. Set hostname:
```bash
az staticwebapp hostname set \
  --name mim-prod-web-standard \
  --resource-group rg-mim-prod \
  --hostname miraclesinmotion.org
```
Azure provisions SSL automatically.

## 9. Configuration (staticwebapp.config.json)
Key elements:
- `navigationFallback` ensures SPA routing.
- `globalHeaders` for security (CSP, HSTS). Adjust `Content-Security-Policy` as integrations evolve.

## 10. Useful Scripts
| Script | Purpose |
|--------|---------|
| `npm run dev` | Start Vite dev server |
| `npm test` | Run tests |
| `npm run build` | Build front-end |
| `npm run analyze` | (If defined) Bundle analysis |

## 11. Troubleshooting
| Issue | Resolution |
|-------|------------|
| 404 on portal route | Ensure hash routing `/#/portals` or SPA fallback set |
| Functions 500 error | Check `api` logs, run locally with `func start` if using standalone Functions |
| CSP blocking script | Update CSP in `staticwebapp.config.json` to allow required domain |
| Node version mismatch | Use Node 20 for SWA managed functions, 22 locally if desired |

## 12. Next Steps
- Configure GitHub Actions for CI/CD.
- Add monitoring (Application Insights) if using standalone Functions.
- Replace test Stripe keys with live keys in production.

---
Last updated: 2025-11-11