# Resto·Ka

Tous les restaurants du Québec — menus complets et prix réels, dans les 17 régions.

# Description

Resto·Ka (www.resto-ka.com) est l'agrégateur exhaustif des restaurants du Québec : chaque resto, chaque plat, chaque prix — dans les 17 régions administratives, au même endroit, comparable et cherchable par resto ou par plat.

• 14 091 restaurants référencés (découverte OpenStreetMap, 17/17 régions)
• 79 159 plats avec prix — des prix takeout réels, non majorés, captés sur la plateforme de commande des restos eux-mêmes (pas sur les apps de livraison, +25-30 %)
• 738 restos avec menu complet, 24 chaînes suivies
• 98 % des items avec photo, 69 % avec options, 99 % géolocalisés

Plateforme de la famille ·Ka (Lou·Ka, Immo·Ka, Auto·Ka, Food·Ka, Fabri·Ka, Sorti·Ka…). Architecture des connecteurs calquée sur Lou·Ka, identité visuelle « éditorial sharp » du Groupe KA (Space Grotesk / Inter / JetBrains Mono, papier-encre-lime, bordures encre + ombres décalées). CLAUDE.md est la source de vérité du projet.

# Fonctionnalités

• Prix réels et contextualisés : un prix n'est JAMAIS présenté sans son contexte (dine-in / takeout / delivery) — un menu sans price_context/price_source est rejeté à l'ingestion, et un menu salle n'est jamais écrasé par un menu livraison.
• Recherche par plat dans les 79 159 items, groupée par marque (pour ne pas répéter 76 fois la même poutine de chaîne).
• Options & formats capturés avec leurs suppléments (« Mini +3,70 $ ») — ils changent le prix réel.
• Historique des prix par item (item_price_log) à chaque changement.
• Alerte de dérive : chute anormale du volume d'une source ou du nombre d'items d'un menu → retraits suspendus / ancien menu conservé.
• Déduplication inter-sources (les succursales ne sont jamais fusionnées) et géocodage à 99 % (Nominatim + Adresses Québec, cache persistant).
• Connexion KA ID (SSO Groupe Ka), favoris, tableau de bord Stats + rapport PDF, widget KA Agent (chat IA).

Accueil — recherche de restos	Recherche par plat

Fiche resto — menu, photos, options & prix	Couverture en direct

# Stack technique

• Backend : Python 3.14 · FastAPI · Uvicorn · SQLite (menus par contexte + historique de prix)
• Frontend : React 18 · Vite · TypeScript — design éditorial sharp Groupe KA
• Scraping/ingestion : requests direct / Firecrawl / Scrapfly, API Overpass (OSM), API GraphQL UEAT
• Tests : 45 tests pytest (fixtures réelles hors ligne)

# Structure (patron Lou·Ka)

restoka/
├── connectors/       # un module par source/plateforme, auto-enregistrés
│   ├── base.py       #   requests direct / Firecrawl / Scrapfly + cache détail
│   └── ueat.py       #   UEAT (templatisé) — API GraphQL, prix TAKEOUT réels
├── schema.py         # Restaurant + menu imbriqué (sections→items→options) + finalize()
├── normalize.py      # prix, cuisines, type d'établissement, diètes, $-$$$$
├── regions.py        # ville → 17 régions (+ repli postal, + repli lat/lng)
├── db.py             # SQLite : restos, menus PAR CONTEXTE, historique de prix
├── ingest.py         # pipeline sync → geocode → dedup (délai de grâce, alertes)
├── dedup.py          # identité resto inter-sources (succursales jamais fusionnées)
├── geocode.py        # Nominatim + Adresses Québec, cache persistant
├── auth.py           # connexion KA ID (SSO Groupe Ka)
└── web.py            # FastAPI + frontend React (frontend/dist)
frontend/             # Vite + React 18 + TS — design éditorial sharp Groupe KA

# Sources connectées

Registre : data/sources.json (à consulter AVANT d'ajouter quoi que ce soit).

# Démarrage local

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
cd frontend && npm install && npm run build && cd ..

.venv/bin/python run.py sync            # synchronise (+ géocode + dédup)
.venv/bin/python run.py serve 8115      # API + frontend sur :8115
.venv/bin/python run.py watch 168       # boucle hebdomadaire
.venv/bin/python -m pytest tests/       # 45 tests (fixtures réelles hors ligne)

# Déploiement

• Nœud : M3U96b (cluster MacLustr), répertoire ~/apps/resto-ka
• Port : 8115
• Domaine : www.resto-ka.com (tunnel ngrok)
• PM2 (3 process) : resto-ka (serveur :8115) + resto-ka-sync (synchro hebdomadaire) + resto-ka-ngrok (tunnel → www.resto-ka.com)
• Registre cross-session : ~/Desktop/cluster-skill/cluster-deployments.json

# Développement remote-first

La source de vérité est le repo git sur le nœud M3U96b (~/apps/resto-ka), PAS les copies laptop. Toute modification se fait sur le nœud via SSH : édition, build, pm2 restart resto-ka, puis git add/commit/push origin main sur le nœud (agent forwarding actif).

• Remote origin = spbgit (git perso git.spboucher.ai — bare repo ~/srv/git/resto-ka.git sur M3U96a, alias SSH gitsrv). PAS GitHub.
• Référence complète : ~/Desktop/cluster-skill/KA-REMOTE-DEV.md.

Un service Groupe Ka — Auteur : Simon-Pierre Boucher <contact@spboucher.ai>.