# Web App Blueprint

This document outlines the architecture used for the Trivia and Survey apps, optimized for rapid development and seamless deployment behind Cloudflare Tunnels or Reverse Proxies.

## 1. Directory Structure
```text
project-root/
├── docker-compose.yml
├── backend/
│   ├── Dockerfile
│   ├── index.js      # Express API
│   ├── database.js   # SQLite/Better-SQLite3 logic
│   └── package.json
└── frontend/
    ├── Dockerfile
    ├── vite.config.js
    ├── src/
    │   ├── App.jsx   # Main logic
    │   └── assets/   # Branding/Logos
    └── index.html
```

## 2. The Connectivity Secret (Relative Paths)
To avoid "Mixed Content" blocks and port-forwarding headaches on mobile:
- **Frontend Code:** Always call API endpoints using relative paths: `fetch('/api/endpoint')`.
- **Vite Configuration:** Use a proxy in `vite.config.js` to route these calls to the backend container.

```javascript
// frontend/vite.config.js
export default defineConfig({
  server: {
    host: '0.0.0.0', // Required for Docker
    allowedHosts: ['your-domain.com'],
    proxy: {
      '/api': {
        target: 'http://backend:3001', // Internal Docker Network URL
        changeOrigin: true
      }
    }
  }
})
```

## 3. Docker Compose Pattern
Orchestrate the internal network so the frontend can "see" the backend by its service name.

```yaml
services:
  backend:
    build: ./backend
    ports:
      - "3001:3001" # Host port : Container port
  frontend:
    build: ./frontend
    ports:
      - "3005:3000" # Cloudflare Tunnel should point to 3005
    depends_on:
      - backend
```

## 4. Cloudflare Tunnel Compatibility
- **Single Public Hostname:** Point your Cloudflare Public Hostname (e.g., trivia.domain.com) to `http://localhost:3005` (the frontend port).
- **Zero-Config Routing:** Because of the Vite Proxy (Step 2), Cloudflare doesn't need to know the backend exists. Requests to `/api` hit the frontend and are silently forwarded to the backend container.

## 5. Security Checklist
- **Backend Sanitization:** Use the `xss` library for all user-submitted text.
- **Payload Limits:** Use `bodyParser.json({ limit: '10kb' })` to prevent DoS.
- **SQL Safety:** Use parameterized queries (standard in `better-sqlite3`).
- **Mobile UX:** 
    - Set input font-size to `16px` to prevent iOS auto-zoom.
    - Use `@media (hover: hover)` to disable sticky button highlights on touch devices.

## 6. Fast-Start Command
```bash
docker compose up -d --build
```
This pattern ensures that as soon as you have your domain mapped in Cloudflare, your app is fully operational with zero networking tweaks required on the server.