# Swirl Master — Ninja Swirl Receptencompanion v1.0

> 🍦 Jouw persoonlijke receptencompanion voor de Ninja Swirl by CREAMi.
> Ontdek recepten, mix & match smaken, en leer je machine kennen.

![Status](https://img.shields.io/badge/status-production-green)
![Version](https://img.shields.io/badge/version-1.0-purple)
![License](https://img.shields.io/badge/license-MIT-blue)

---

## 🚀 Quick Start

```bash
# 1. Dependencies installeren
cd /root/projects/jg/2026-ninja-swirl-recipes/deliverables
pip3 install -r requirements.txt

# 2. Database seeden
python3 generate_seed.py

# 3. Server starten (development)
python3 api_server.py

# 4. Open in browser
# http://localhost:5060
```

Voor productie: zie [Productie Deployment](#-productie-deployment) hieronder.

---

## 📋 Inhoudsopgave

1. [Over Swirl Master](#-over-swirl-master)
2. [Features](#-features)
3. [Architectuur](#-architectuur)
4. [Bestandenlijst](#-bestandenlijst)
5. [Installatie (Productie)](#-productie-deployment)
6. [API Documentatie](#-api-documentatie)
7. [Recepten Toevoegen](#-recepten-toevoegen)
8. [Testing](#-testing)
9. [Rollback Procedure](#-rollback-procedure)
10. [Bekende Issues & Edge Cases](#-bekende-issues--edge-cases)
11. [Toekomstige Features](#-toekomstige-features)

---

## 🍦 Over Swirl Master

Swirl Master is een innovatieve webapp speciaal gebouwd voor eigenaren van de Ninja Swirl by CREAMi ijsmachine (model NC701). De app biedt:

- **30+ recepten** verdeeld over alle 13 programma's
- **Mix & Match generator** voor oneindige smaakcombinaties
- **Machine gids** met complete handleiding per type iJs
- **Quiz** die je helpt het perfecte ijstype te vinden
- **Favorieten** opslag (localStorage + API)
- **Dark mode** voor 's avonds iJs maken

Geïnspireerd door het [GreenThumb](https://mescalinerabbit.shop/greenthumb/) design.

---

## ✨ Features

### 🏠 Dashboard
- Live statistieken (aantal recepten, programma's, favorieten)
- Uitgelichte populaire recepten
- Snelle type-selector
- IJs-tip van de dag (roteert)
- "Welk type past bij jou?" quiz

### 📖 Receptenbank
- 30+ recepten over 11+ types
- Filters: type, dieet (vegan, keto, glutenvrij, etc.), moeilijkheid
- Sortering: populariteit, moeilijkheid, snelheid, beoordeling, naam
- Real-time zoekfunctie (naam, ingrediënt, tag)
- Uitgebreide receptdetail met:
  - Ingrediëntenlijst
  - Stap-voor-stap bereiding
  - Mix-in suggesties
  - Voedingsinformatie
  - Pro tips

### 🎲 Mix & Match Generator
- 4-kolom selector: Basis → Smaak → Mix-in → Topping
- Compatibility scoring algoritme (op basis van smaakpaar-theorie)
- Automatische programma-aanbeveling
- "Verras me!" random generator
- Recept opslaan als favoriet

### 📚 Machine Gids
- Overzicht van alle 13 programma's
- Stap-voor-stap uitleg hoe de machine werkt
- Voorbereiding & pint management
- Onderhoud & schoonmaak
- Probleemoplossing (7 veelvoorkomende issues)
- 10 Pro Tips van iJsmeesters

### ⭐ Favorieten
- Lokaal opgeslagen (geen account nodig)
- Snelle toegang tot opgeslagen recepten
- Werk ook offline (frontend-only)

---

## 🏗 Architectuur

```
┌─────────────────────────────────────────────────┐
│                   Browser (Client)               │
│                                                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐│
│  │ index.   │ │ style.   │ │ app.js           ││
│  │ html     │ │ css      │ │                  ││
│  │          │ │          │ │ • RECIPES[]      ││
│  │ 5 tabs:  │ │ Purple/  │ │ • PROGRAMS{}     ││
│  │ Dashboard│ │ Pink/    │ │ • MixMatch engine││
│  │ Recipes  │ │ Mint     │ │ • Quiz logic     ││
│  │ MixMatch │ │ theme    │ │ • Favorites mgr  ││
│  │ Guide    │ │          │ │ • Guide content  ││
│  │ Favorites│ │ Dark mode│ │                  ││
│  └──────────┘ └──────────┘ └──────────────────┘│
│                       │                          │
│              localStorage (favorites)            │
└──────────────────────┬───────────────────────────┘
                       │ HTTP (optional)
┌──────────────────────▼───────────────────────────┐
│              Nginx (Reverse Proxy)                │
│              Port 80/443                          │
│              Static files + API proxy             │
└──────────────────────┬───────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────┐
│           Flask API Server (PM2)                  │
│           Port 5060                               │
│                                                   │
│  ┌─────────────┐ ┌──────────┐ ┌───────────────┐│
│  │ /api/recipes│ │/api/     │ │ /api/         ││
│  │             │ │programs  │ │favorites      ││
│  │ GET (filter)│ │GET       │ │GET/POST/DELETE│ │
│  │ POST (add)  │ │          │ │               ││
│  └─────────────┘ └──────────┘ └───────────────┘│
│  ┌─────────────┐ ┌──────────┐ ┌───────────────┐│
│  │/api/mixmatch│ │/api/stats│ │ /api/health   ││
│  │ /suggest    │ │          │ │               ││
│  └─────────────┘ └──────────┘ └───────────────┘│
│                       │                          │
│              ┌────────▼────────┐                 │
│              │  SQLite DB      │                 │
│              │  swirl_master   │                 │
│              │  .db            │                 │
│              │                 │                 │
│              │ • recipes       │                 │
│              │ • favorites     │                 │
│              │ • ratings       │                 │
│              └─────────────────┘                 │
└───────────────────────────────────────────────────┘
```

### Dataflow

1. **Pagina laad**: `app.js` heeft alle recepten ingebouwd → direct renderen (geen API call nodig voor frontend-only modus)
2. **API optioneel**: Als de Flask backend draait, kan de frontend API gebruiken voor community features
3. **Favorites**: Standaard in `localStorage` (browser); optioneel gesynchroniseerd via API met SQLite
4. **Mix & Match**: Volledig client-side; geen API nodig
5. **Recept zoeken**: Client-side filtering; API endpoint beschikbaar voor externe integratie

---

## 📁 Bestandenlijst

```
2026-ninja-swirl-recipes/
├── deliverables/                # Alle productiebestanden
│   ├── index.html              # Hoofd HTML (11.8 KB)
│   ├── style.css               # Volledige stylesheet (26.8 KB)
│   ├── app.js                  # Applicatie + database (84.7 KB)
│   ├── api_server.py           # Flask REST API (22.9 KB)
│   ├── generate_seed.py        # Database seed generator (5.5 KB)
│   ├── seed_recipes.json       # Seed data (gegenereerd)
│   ├── swirl_master.db         # SQLite database (gegenereerd)
│   ├── requirements.txt        # Python dependencies
│   ├── ecosystem.config.js     # PM2 configuratie
│   ├── nginx-swirl.conf        # Nginx reverse proxy config
│   ├── .env.example            # Environment template
│   ├── test_smoke.py           # Automatische smoke tests (9.8 KB)
│   └── README.md               # Dit bestand
├── archive/                    # Oude versies
├── logs/                       # PM2 logs
├── research/                   # Onderzoek & referenties
└── working/                    # Werkbestanden
```

---

## 🔧 Productie Deployment

### Stap 1: Dependencies

```bash
# Python packages
cd /root/projects/jg/2026-ninja-swirl-recipes/deliverables
pip3 install -r requirements.txt

# PM2 (als nog niet geïnstalleerd)
npm install -g pm2
```

### Stap 2: Database Initialiseren

```bash
# Genereer seed data
python3 generate_seed.py

# Test database init (gebruikt api_server.py's init_db())
python3 -c "from api_server import init_db; init_db(); print('✅ Database OK')"
```

### Stap 3: PM2 Starten

```bash
cd /root/projects/jg/2026-ninja-swirl-recipes/deliverables
pm2 start ecosystem.config.js
pm2 save

# Check status
pm2 status swirl-master
pm2 logs swirl-master --lines 20
```

### Stap 4: Nginx Configureren

```bash
# Rate limit zone toevoegen aan nginx.conf (in http {} block)
# Voeg toe: limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# Site configureren
sudo cp nginx-swirl.conf /etc/nginx/sites-available/swirl
sudo ln -sf /etc/nginx/sites-available/swirl /etc/nginx/sites-enabled/swirl

# Of voor een subpath (mescalinerabbit.shop/swirl/):
# Pas de location blocks aan naar /swirl/ {
#   alias /root/projects/jg/2026-ninja-swirl-recipes/deliverables/;
# }

# Testen
sudo nginx -t

# Reload
sudo systemctl reload nginx
```

### Stap 5: SSL (als nodig)

```bash
# Certbot (als nog niet gedaan voor dit domein)
sudo certbot --nginx -d swirl.mescalinerabbit.shop
```

### Stap 6: Environment Variables

```bash
# Voor productie, kopieer .env en vul in
cp .env.example .env
# Bewerk .env met je instellingen

# Voor PM2, kunnen env vars in ecosystem.config.js gezet worden
```

### Stap 7: Verify

```bash
# Smoke tests
python3 test_smoke.py --host http://localhost:5060

# Manual check
curl http://localhost:5060/api/health | jq .
curl http://localhost:5060/api/recipes | jq '.count'
curl http://localhost:5060/api/programs | jq '.count'

# Browser check
# Open https://swirl.mescalinerabbit.shop (of http://localhost:5060)
```

---

## 🔌 API Documentatie

### Health
| Endpoint | Method | Beschrijving |
|----------|--------|-------------|
| `/api/health` | GET | Health check + database status |

### Recipes
| Endpoint | Method | Parameters | Beschrijving |
|----------|--------|-----------|-------------|
| `/api/recipes` | GET | `type`, `diet`, `q`, `sort`, `limit` | Recepten ophalen met filters |
| `/api/recipes/<id>` | GET | — | Eén recept ophalen |
| `/api/recipes` | POST | JSON body | Nieuw recept toevoegen |

### Programs
| Endpoint | Method | Beschrijving |
|----------|--------|-------------|
| `/api/programs` | GET | Alle 13 programma's |
| `/api/programs/<id>` | GET | Eén programma |

### Favorites
| Endpoint | Method | Headers | Beschrijving |
|----------|--------|---------|-------------|
| `/api/favorites` | GET | `X-Session-ID` | Favorieten ophalen |
| `/api/favorites/<id>` | POST | `X-Session-ID` | Toevoegen |
| `/api/favorites/<id>` | DELETE | `X-Session-ID` | Verwijderen |

### Mix & Match
| Endpoint | Method | Body | Beschrijving |
|----------|--------|------|-------------|
| `/api/mixmatch/suggest` | POST | `{"base":"...","flavor":"...","mixin":"...","topping":"..."}` | Genereer recept |

### Stats
| Endpoint | Method | Beschrijving |
|----------|--------|-------------|
| `/api/stats` | GET | App statistieken |

### Voorbeelden

```bash
# Alle vegan recepten
curl "http://localhost:5060/api/recipes?diet=vegan"

# Favoriet toevoegen
curl -X POST http://localhost:5060/api/favorites/ic-vanilla \
  -H "X-Session-ID: user-123"

# Mix & Match
curl -X POST http://localhost:5060/api/mixmatch/suggest \
  -H "Content-Type: application/json" \
  -d '{"base":"coconut-milk","flavor":"mango","mixin":"chili"}'
```

---

## 🧪 Testing

### Smoke Tests (Automatisch)

```bash
cd /root/projects/jg/2026-ninja-swirl-recipes/deliverables
python3 test_smoke.py
```

De smoke test controleert:
- ✅ Health endpoint
- ✅ Statische bestanden (HTML, CSS, JS)
- ✅ Recepten API (filteren, zoeken, sorteren)
- ✅ Programma's API
- ✅ Favorieten API (CRUD)
- ✅ Mix & Match API
- ✅ Stats API
- ✅ Edge cases (404, invalid input, lege queries)

### Post-Deployment Checklist

- [ ] PM2 proces draait: `pm2 status swirl-master`
- [ ] Health check OK: `curl localhost:5060/api/health`
- [ ] Index laadt: `curl localhost:5060/`
- [ ] CSS laadt: `curl localhost:5060/style.css`
- [ ] JS laadt: `curl localhost:5060/app.js`
- [ ] Recepten API: `curl localhost:5060/api/recipes | jq .count`
- [ ] Nginx proxy: `curl https://swirl.mescalinerabbit.shop/api/health`
- [ ] Smoke tests pass: `python3 test_smoke.py`
- [ ] Browser test: Open URL, check alle 5 tabs
- [ ] Dark mode toggle werkt
- [ ] Favorieten opslaan werkt (refresh pagina)
- [ ] Mix & Match genereert recept

---

## 🔄 Rollback Procedure

Als de deployment faalt:

### Snelle Rollback (PM2)

```bash
# Stop nieuwe versie
pm2 stop swirl-master

# Roll back naar vorige versie (als backup aanwezig)
cp -r /root/projects/jg/2026-ninja-swirl-recipes/archive/v0.9/* \
      /root/projects/jg/2026-ninja-swirl-recipes/deliverables/

# Herstart
pm2 restart swirl-master

# Verify
curl localhost:5060/api/health
```

### Database Rollback

```bash
# Backup vooraf maken!
cp swirl_master.db swirl_master.db.bak

# Rollback
cp swirl_master.db.bak swirl_master.db
pm2 restart swirl-master
```

### Nginx Rollback

```bash
# Verwijder broken config
sudo rm /etc/nginx/sites-enabled/swirl
sudo nginx -t && sudo systemctl reload nginx
```

---

## ⚠️ Bekende Issues & Edge Cases

1. **Offline modus**: De frontend werkt volledig zonder backend. Favorites worden in localStorage opgeslagen. De API is optioneel voor geavanceerde features.

2. **iOS Safari**: De `100vh` bug kan zorgen voor layout issues op oudere iPhones. Opgelost met `min-height: 100vh` in plaats van `height`.

3. **Koude vriezer**: Bij vriezer temperaturen onder -25°C kan het iJs te hard worden voor de Creamifier. De app vermeldt RE-SPIN als oplossing.

4. **Geen echte afbeeldingen**: De recepten gebruiken emoji's in plaats van foto's voor snelheid en onderhoudbaarheid.

5. **Voorraadbeheer**: Nog geen integratie met boodschappenlijstje (gepland voor v1.1).

6. **Gedeeld favorieten**: Per apparaat/browser opgeslagen. Account-systeem gepland voor v2.0.

---

## 🚀 Toekomstige Features (Roadmap)

### v1.1
- [ ] Boodschappenlijstje genereren uit recepten
- [ ] Recept foto upload (via API)
- [ ] Seizoensfilters (zomer/winter recepten)
- [ ] Recept delen via link

### v1.2
- [ ] Community recepten (met moderatie)
- [ ] Beoordelingen & reviews
- [ ] Recept vertaling (NL/EN)
- [ ] PWA / Service Worker (offline modus)

### v2.0
- [ ] Gebruikersaccounts
- [ ] Cloud synchronisatie favorieten
- [ ] Voeding tracker integratie
- [ ] Maandelijkse iJs-challenge

---

## 📜 License

MIT — Vrij te gebruiken en aan te passen.

Gebouwd door Jorick van Gemert voor de Ninja Swirl by CREAMi community.
Niet geaffilieerd met SharkNinja. Alle merknamen zijn eigendom van hun respectievelijke eigenaren.

---

*🍦 Swirl Master v1.0 — Because every day is ice cream day.*