docs: README v2 — galerie multi-pages, style du site, documentation, contact · 89195ec · sorti-ka

4

Desc: Documentation du dépôt Sorti-Ka — agrégateur de sorties & événements

5

-->

6

7

−# Sorti·Ka

7

+

8

+ <a href="https://www.sorti-ka.com"><img src="https://www.sorti-ka.com/og.png" width="760" alt="Sorti·Ka — Toutes les sorties, dans les 17 régions"></a>

9

+

10

+

11

+<h1 align="center">Sorti·Ka</h1>

8

12

9

−**Toutes les sorties et tous les événements du Québec — concerts, festivals, spectacles, expos, sport, famille — au même endroit.**

13

+Toutes les sorties, dans les 17 régions

10

14

11

−[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.sorti-ka.com&style=flat-square&label=www.sorti-ka.com)](https://www.sorti-ka.com)

15

+<div align="center">

16

+

17

+[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.sorti-ka.com&style=flat-square&label=www.sorti-ka.com&up_color=d6336c)](https://www.sorti-ka.com)

18

+[![Documentation](https://img.shields.io/badge/📖_documentation-%2Fdoc-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/)

19

+[![PDF](https://img.shields.io/badge/guide-PDF-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf)

12

20

![Nœud](https://img.shields.io/badge/n%C5%93ud-M3U96a-1f6feb?style=flat-square)

13

−![Port](https://img.shields.io/badge/port-8120-e8590c?style=flat-square)

21

+![Port](https://img.shields.io/badge/port-8120-d6336c?style=flat-square)

14

22

![PM2](https://img.shields.io/badge/process-PM2-2b037a?style=flat-square)

15

23

![Python](https://img.shields.io/badge/Python-3.14-3776ab?style=flat-square&logo=python&logoColor=white)

16

24

![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSR-009688?style=flat-square&logo=fastapi&logoColor=white)

17

25

![SQLite](https://img.shields.io/badge/SQLite-diff%20%2B%20historique-141814?style=flat-square&logo=sqlite)

18

26

![Groupe KA](https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square)

19

27

28

+</div>

29

+

20

30

**Sorti·Ka** est un **agrégateur indépendant de sorties et d'événements** couvrant les **17 régions administratives du Québec** : plus de **18 000 événements actifs** dans **~330 villes**, avec dates, lieux, gratuité (plus de 3 600 événements gratuits à venir), fiche par événement et **lien direct vers la billetterie ou la source originale**. Mise à jour **horaire**, automatiquement.

21

31

22

32

Trouver quoi faire au Québec, c'est normalement ouvrir dix sites : les billetteries ne montrent que leurs propres spectacles, les calendriers municipaux que leur ville, les sites touristiques que leurs membres. Sorti·Ka retourne le problème : un **connecteur dédié par source** (une trentaine de connecteurs actifs, 44 sources au registre) visite chaque calendrier, normalise chaque événement vers un **schéma unique**, **déduplique les doublons inter-sources** et détecte les changements en continu. Sorti·Ka **n'est pas une billetterie** : c'est un **index fidèle** — aucun prix inventé, aucune date devinée, chaque fiche est attribuée à sa source. Pour qui ? Quiconque cherche quoi faire, ce soir ou cet été, n'importe où au Québec.

23

33

24

−## Captures d'écran

25

−

26

−

27

− <img src="docs/screenshots/sorti-ka-desktop.png" width="640" alt="Accueil — desktop">

28

− <img src="docs/screenshots/sorti-ka-mobile.png" width="200" alt="Accueil — mobile">

29

−

34

+## Visite guidée

35

+

36

+<table>

37

+ <tr>

38

+ <td align="center"><img src="docs/screenshots/accueil.png" width="420" alt="Accueil — desktop"> Accueil — liste des événements (desktop)</td>

39

+ <td align="center"><img src="docs/screenshots/sorti-ka-mobile.png" width="420" alt="Accueil — mobile"> Accueil — mobile</td>

40

+ </tr>

41

+ <tr>

42

+ <td align="center" colspan="2"><img src="docs/screenshots/fiche.png" width="420" alt="Fiche d'événement"> Fiche d'événement — dates, lieu, prix, lien billetterie</td>

43

+ </tr>

44

+</table>

45

+

46

+### Guide pas à pas (« Utiliser le site en 4 étapes », depuis [/doc](https://www.sorti-ka.com/doc/))

47

+

48

+<table>

49

+ <tr>

50

+ <td align="center"><img src="frontend/doc/img/etape1.png" width="420" alt="Étape 1 — accueil de Sorti·Ka"> Étape 1 — Arriver sur l'accueil</td>

51

+ <td align="center"><img src="frontend/doc/img/etape2.png" width="420" alt="Étape 2 — recherche filtrée d'événements"> Étape 2 — Filtrer la liste</td>

52

+ </tr>

53

+ <tr>

54

+ <td align="center"><img src="frontend/doc/img/etape3.png" width="420" alt="Étape 3 — fiche d'événement avec lien billetterie"> Étape 3 — Ouvrir la fiche d'un événement</td>

55

+ <td align="center"><img src="frontend/doc/img/etape4.png" width="420" alt="Étape 4 — tableau de bord statistiques"> Étape 4 — Consulter les statistiques</td>

56

+ </tr>

57

+</table>

30

58

31

59

## Fonctionnalités

32

60

33

61

- **Recherche filtrée** — région, ville, catégorie (14 catégories canoniques), période, **gratuité**, texte libre, tri et pagination (`GET /api/events`).

34

62

- **Fiche par événement** — dates, heure locale, artistes, lieu, prix (avec `price_label` original), carte, événements similaires ; **SSR + JSON-LD Event** (`/evenement/{uid}`) pour le SEO, sitemaps et robots.txt.

35

−- **~30 connecteurs actifs** : billetteries (Le point de vente, evenko/Algolia, Ticketpro, Ticket Accès, Tuxedo Billet, Ovation, Eventbrite), données ouvertes officielles (SIT Québec/Tourinsoft, Ville de Montréal CKAN, Laval, Sherbrooke, Brossard, Longueuil), diffuseurs et salles (La Vitrine, Place des Arts, salles via JSON-LD), portails régionaux (Montérégie, Outaouais, Lanaudière, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Gaspésie, Centre-du-Québec, Saguenay…), Atuvu.ca (via Scrapfly), Bandsintown, LHJMQ, Québec animée — Ticketmaster prêt (clé `TICKETMASTER_API_KEY` requise).

63

+- **~30 connecteurs actifs** couvrant billetteries, données ouvertes, diffuseurs et portails régionaux (tableau ci-dessous).

36

64

- **Déduplication inter-sources** — empreinte titre + ville + date : un même concert publié par 3 sources = une seule carte, la fiche la plus riche gagne.

37

65

- **Répertoire des municipalités MAMH** — 1 250 villes + arrondissements + alias, homonymes résolus par population ; rattachement automatique aux 17 régions.

38

66

- **Persistance robuste** — upsert par hash de contenu, délai de grâce de 2 syncs avant retrait, alerte de dérive quand une source casse, historique des synchronisations.

40

68

- **Widget KA Agent** + **favoris « Mon univers Ka »** (KA ID, hub groupe-ka.com).

41

69

- **Tests sur fixtures réelles, zéro réseau** (pytest).

42

70

71

+## Connecteurs & sources

72

+

73

+| Famille | Sources | Accès |

74

+|---|---|---|

75

+| **Billetteries** | Le point de vente, evenko (Algolia), Ticketpro, Ticket Accès, Tuxedo Billet, Ovation, Eventbrite | API/JSON publics des billetteries |

76

+| **Données ouvertes officielles** | SIT Québec / Tourinsoft, Ville de Montréal (CKAN), Laval, Sherbrooke, Brossard, Longueuil | portails de données ouvertes |

77

+| **Diffuseurs & salles** | La Vitrine, Place des Arts, salles via JSON-LD | pages publiques structurées |

78

+| **Portails régionaux** | Montérégie, Outaouais, Lanaudière, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Gaspésie, Centre-du-Québec, Saguenay… | calendriers régionaux publics |

79

+| **Autres** | Atuvu.ca (via Scrapfly), Bandsintown, LHJMQ, Québec animée | HTML/JSON publics |

80

+| **Prêt (clé requise)** | Ticketmaster (`TICKETMASTER_API_KEY`) | API officielle |

81

+

82

+**Cadence de resync : horaire** — le watcher PM2 `sorti-ka-sync` (`run.py watch`) visite les sources en continu ; chaque événement passe par la normalisation (`schema.py` + `normalize.py`), l'upsert par hash, le délai de grâce (2 syncs) et l'alerte de dérive. Une fiche de conformité par connecteur est générée dans `docs/connecteurs/` (voir `docs/CONFORMITE.md`).

83

+

43

84

## Architecture

44

85

45

86

```

55

96

- **Base de données** : **SQLite** — événements, diff par hash, délai de grâce, historique de syncs, géocodage (`geocode.py`, `venues.py`).

56

97

- **Frontend** : SPA **sans build** (HTML/JS, routeur History API), design system Groupe KA « éditorial sharp » (ka-ui), widget KA Agent.

57

98

- **Anti-bot** : **Scrapfly** pour Atuvu (clé `SCRAPFLY_API_KEY` dans `.env`).

58

−- **Processus PM2** :

59

− - **`sorti-ka-web`** — uvicorn sur le port **8120** (API + frontend + SSR) ;

60

− - **`sorti-ka-sync`** — watcher **horaire** (`run.py watch`) : ingestion continue des sources ;

61

− - **`sorti-ka-ngrok`** — tunnel ngrok vers www.sorti-ka.com.

99

+

100

+## API — endpoints principaux

101

+

102

+| Endpoint | Rôle |

103

+|---|---|

104

+| `GET /api/events` | recherche filtrée : région, ville, catégorie, période, gratuité, texte, tri, pagination |

105

+| `GET /api/events/{uid}` | fiche complète d'un événement (+ SSR SEO sur `/evenement/{uid}`) |

106

+| `GET /api/regions` · `GET /api/categories` | référentiels (17 régions, 14 catégories canoniques) |

107

+| `GET /api/sources` | registre des sources et état des connecteurs |

108

+| `GET /api/stats` · `/api/stats/catalog` · `/api/stats/dashboard` · `/api/stats/report(/custom)` | tableau de bord + rapports PDF Groupe-KA |

109

+| `GET /api/favorites` · `POST /api/favorites/toggle` | favoris « Mon univers Ka » (KA ID) |

110

+| `GET /api/health` · `GET /healthz` | santé du service |

62

111

63

112

## Structure du repo

64

113

66

115

|---|---|

67

116

| `sortika/` | paquet Python : connecteurs, schéma `Event`, normalisation, régions MAMH, DB, web/SSR, stats, PDF, auth KA ID |

68

117

| `sortika/connectors/` | un module par source (auto-découverts), base commune + `_resilient.py` |

69

−| `frontend/` | SPA sans build (`index.html`, `ka-agent.js`, assets) |

118

+| `frontend/` | SPA sans build (`index.html`, `ka-agent.js`, assets) + guide `/doc` (page, images, PDF) |

70

119

| `data/` | base SQLite + `villes_regions.json` (répertoire MAMH) — non versionnés pour la BD |

71

120

| `tests/` | pytest sur fixtures réelles, zéro réseau |

72

121

| `scripts/` | utilitaires (génération de docs, maintenance) |

92

141

git add <fichiers> && git commit -m "…" && git push origin main

93

142

```

94

143

95

−Secrets (gabarit `.env.example`) : `SCRAPFLY_API_KEY` (Atuvu), `TICKETMASTER_API_KEY` (active le connecteur Ticketmaster).

144

+### Configuration notable (sans secrets)

145

+

146

+| Variable | Rôle |

147

+|---|---|

148

+| `SCRAPFLY_API_KEY` | anti-bot pour le connecteur Atuvu.ca |

149

+| `TICKETMASTER_API_KEY` | active le connecteur Ticketmaster (prêt, en attente de clé) |

150

+

151

+Gabarit : `.env.example` — aucun secret n'est versionné.

96

152

97

153

## Déploiement

98

154

100

156

|---|---|

101

157

| **Nœud** | **M3U96a** (cluster MacLustr) — `~/apps/sorti-ka` |

102

158

| **Port** | **8120** |

103

−| **Processus PM2** | `sorti-ka-web` (uvicorn) + `sorti-ka-sync` (watcher horaire) + `sorti-ka-ngrok` (tunnel) |

104

159

| **Domaine** | [www.sorti-ka.com](https://www.sorti-ka.com) via tunnel ngrok |

105

160

161

+| Processus PM2 | Rôle |

162

+|---|---|

163

+| `sorti-ka-web` | uvicorn sur le port **8120** — API + frontend + SSR SEO |

164

+| `sorti-ka-sync` | watcher **horaire** (`run.py watch`) — ingestion continue des sources |

165

+| `sorti-ka-ngrok` | tunnel ngrok vers www.sorti-ka.com |

166

+

167

+## Documentation

168

+

169

+- **Guide utilisateur en ligne** : [www.sorti-ka.com/doc/](https://www.sorti-ka.com/doc/) — à quoi sert le site, utilisation en 4 étapes, provenance des données, FAQ.

170

+- **Guide PDF téléchargeable** : [sorti-ka-documentation.pdf](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf).

171

+- **Conformité & connecteurs** : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/`.

172

+

106

173

## Écosystème Groupe KA

107

174

108

−- [groupe-ka.com](https://www.groupe-ka.com) — portail

109

−- [lou-ka.com](https://www.lou-ka.com) — logements à louer

110

−- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre

111

−- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière

112

−- [auto-ka.com](https://www.auto-ka.com) — véhicules

113

−- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois

114

−- [food-ka.com](https://www.food-ka.com) — épicerie / alimentation

115

−- [resto-ka.com](https://www.resto-ka.com) — restaurants

116

−- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements

117

−- [job-ka.com](https://www.job-ka.com) — emplois

118

−- [crea-ka.com](https://www.crea-ka.com) — créateurs

119

−- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces

120

−- [api-ka.com](https://www.api-ka.com) — API de données

175

+| Site | Univers |

176

+|---|---|

177

+| [groupe-ka.com](https://www.groupe-ka.com) | portail |

178

+| [lou-ka.com](https://www.lou-ka.com) | logements à louer |

179

+| [immo-ka.com](https://www.immo-ka.com) | propriétés à vendre |

180

+| [vrai-prix.com](https://www.vrai-prix.com) | estimation immobilière |

181

+| [auto-ka.com](https://www.auto-ka.com) | véhicules |

182

+| [fabri-ka.com](https://www.fabri-ka.com) | produits québécois |

183

+| [food-ka.com](https://www.food-ka.com) | épicerie / alimentation |

184

+| [resto-ka.com](https://www.resto-ka.com) | restaurants |

185

+| [sorti-ka.com](https://www.sorti-ka.com) | sorties et événements |

186

+| [job-ka.com](https://www.job-ka.com) | emplois |

187

+| [crea-ka.com](https://www.crea-ka.com) | créateurs |

188

+| [trouve-ka.com](https://www.trouve-ka.com) | petites annonces |

189

+| [api-ka.com](https://www.api-ka.com) | API de données |

190

+

191

+## Contact

192

+

193

+**Simon-Pierre Boucher** — fondateur, Groupe KA

194

+📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)

121

195

122

196

---

123

197

124

198

		`@@ -4,35 +4,63 @@`
4	4	Desc: Documentation du dépôt Sorti-Ka — agrégateur de sorties & événements
5	5	-->
6	6
7		−# Sorti·Ka
	7	+<p align="center">
	8	+ <a href="https://www.sorti-ka.com"><img src="https://www.sorti-ka.com/og.png" width="760" alt="Sorti·Ka — Toutes les sorties, dans les 17 régions"></a>
	9	+</p>
	10	+
	11	+<h1 align="center">Sorti·Ka</h1>
8	12
9		−Toutes les sorties et tous les événements du Québec — concerts, festivals, spectacles, expos, sport, famille — au même endroit.
	13	+<p align="center"><b>Toutes les sorties, dans les 17 régions</b></p>
10	14
11		−[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.sorti-ka.com&style=flat-square&label=www.sorti-ka.com)](https://www.sorti-ka.com)
	15	+<div align="center">
	16	+
	17	+[![Site](https://img.shields.io/website?url=https%3A%2F%2Fwww.sorti-ka.com&style=flat-square&label=www.sorti-ka.com&up_color=d6336c)](https://www.sorti-ka.com)
	18	+[![Documentation](https://img.shields.io/badge/📖_documentation-%2Fdoc-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/)
	19	+[![PDF](https://img.shields.io/badge/guide-PDF-d6336c?style=flat-square)](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf)
12	20	![Nœud](https://img.shields.io/badge/n%C5%93ud-M3U96a-1f6feb?style=flat-square)
13		−![Port](https://img.shields.io/badge/port-8120-e8590c?style=flat-square)
	21	+![Port](https://img.shields.io/badge/port-8120-d6336c?style=flat-square)
14	22	![PM2](https://img.shields.io/badge/process-PM2-2b037a?style=flat-square)
15	23	![Python](https://img.shields.io/badge/Python-3.14-3776ab?style=flat-square&logo=python&logoColor=white)
16	24	![FastAPI](https://img.shields.io/badge/FastAPI-API%20%2B%20SSR-009688?style=flat-square&logo=fastapi&logoColor=white)
17	25	![SQLite](https://img.shields.io/badge/SQLite-diff%20%2B%20historique-141814?style=flat-square&logo=sqlite)
18	26	![Groupe KA](https://img.shields.io/badge/Groupe-KA-b7f000?style=flat-square)
19	27
	28	+</div>
	29	+
20	30	Sorti·Ka est un agrégateur indépendant de sorties et d'événements couvrant les 17 régions administratives du Québec : plus de 18 000 événements actifs dans ~330 villes, avec dates, lieux, gratuité (plus de 3 600 événements gratuits à venir), fiche par événement et lien direct vers la billetterie ou la source originale. Mise à jour horaire, automatiquement.
21	31
22	32	Trouver quoi faire au Québec, c'est normalement ouvrir dix sites : les billetteries ne montrent que leurs propres spectacles, les calendriers municipaux que leur ville, les sites touristiques que leurs membres. Sorti·Ka retourne le problème : un connecteur dédié par source (une trentaine de connecteurs actifs, 44 sources au registre) visite chaque calendrier, normalise chaque événement vers un schéma unique, déduplique les doublons inter-sources et détecte les changements en continu. Sorti·Ka n'est pas une billetterie : c'est un index fidèle — aucun prix inventé, aucune date devinée, chaque fiche est attribuée à sa source. Pour qui ? Quiconque cherche quoi faire, ce soir ou cet été, n'importe où au Québec.
23	33
24		−## Captures d'écran
25		−
26		−<p align="center">
27		− <img src="docs/screenshots/sorti-ka-desktop.png" width="640" alt="Accueil — desktop">
28		− <img src="docs/screenshots/sorti-ka-mobile.png" width="200" alt="Accueil — mobile">
29		−</p>
	34	+## Visite guidée
	35	+
	36	+<table>
	37	+ <tr>
	38	+ <td align="center"><img src="docs/screenshots/accueil.png" width="420" alt="Accueil — desktop"><br><sub><b>Accueil — liste des événements (desktop)</b></sub></td>
	39	+ <td align="center"><img src="docs/screenshots/sorti-ka-mobile.png" width="420" alt="Accueil — mobile"><br><sub><b>Accueil — mobile</b></sub></td>
	40	+ </tr>
	41	+ <tr>
	42	+ <td align="center" colspan="2"><img src="docs/screenshots/fiche.png" width="420" alt="Fiche d'événement"><br><sub><b>Fiche d'événement — dates, lieu, prix, lien billetterie</b></sub></td>
	43	+ </tr>
	44	+</table>
	45	+
	46	+### Guide pas à pas (« Utiliser le site en 4 étapes », depuis [/doc](https://www.sorti-ka.com/doc/))
	47	+
	48	+<table>
	49	+ <tr>
	50	+ <td align="center"><img src="frontend/doc/img/etape1.png" width="420" alt="Étape 1 — accueil de Sorti·Ka"><br><sub><b>Étape 1 — Arriver sur l'accueil</b></sub></td>
	51	+ <td align="center"><img src="frontend/doc/img/etape2.png" width="420" alt="Étape 2 — recherche filtrée d'événements"><br><sub><b>Étape 2 — Filtrer la liste</b></sub></td>
	52	+ </tr>
	53	+ <tr>
	54	+ <td align="center"><img src="frontend/doc/img/etape3.png" width="420" alt="Étape 3 — fiche d'événement avec lien billetterie"><br><sub><b>Étape 3 — Ouvrir la fiche d'un événement</b></sub></td>
	55	+ <td align="center"><img src="frontend/doc/img/etape4.png" width="420" alt="Étape 4 — tableau de bord statistiques"><br><sub><b>Étape 4 — Consulter les statistiques</b></sub></td>
	56	+ </tr>
	57	+</table>
30	58
31	59	## Fonctionnalités
32	60
33	61	- Recherche filtrée — région, ville, catégorie (14 catégories canoniques), période, gratuité, texte libre, tri et pagination (`GET /api/events`).
34	62	- Fiche par événement — dates, heure locale, artistes, lieu, prix (avec `price_label` original), carte, événements similaires ; SSR + JSON-LD Event (`/evenement/{uid}`) pour le SEO, sitemaps et robots.txt.
35		−- ~30 connecteurs actifs : billetteries (Le point de vente, evenko/Algolia, Ticketpro, Ticket Accès, Tuxedo Billet, Ovation, Eventbrite), données ouvertes officielles (SIT Québec/Tourinsoft, Ville de Montréal CKAN, Laval, Sherbrooke, Brossard, Longueuil), diffuseurs et salles (La Vitrine, Place des Arts, salles via JSON-LD), portails régionaux (Montérégie, Outaouais, Lanaudière, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Gaspésie, Centre-du-Québec, Saguenay…), Atuvu.ca (via Scrapfly), Bandsintown, LHJMQ, Québec animée — Ticketmaster prêt (clé `TICKETMASTER_API_KEY` requise).
	63	+- ~30 connecteurs actifs couvrant billetteries, données ouvertes, diffuseurs et portails régionaux (tableau ci-dessous).
36	64	- Déduplication inter-sources — empreinte titre + ville + date : un même concert publié par 3 sources = une seule carte, la fiche la plus riche gagne.
37	65	- Répertoire des municipalités MAMH — 1 250 villes + arrondissements + alias, homonymes résolus par population ; rattachement automatique aux 17 régions.
38	66	- Persistance robuste — upsert par hash de contenu, délai de grâce de 2 syncs avant retrait, alerte de dérive quand une source casse, historique des synchronisations.
		`@@ -40,6 +68,19 @@ Trouver quoi faire au Québec, c'est normalement ouvrir dix sites : les billette`
40	68	- Widget KA Agent + favoris « Mon univers Ka » (KA ID, hub groupe-ka.com).
41	69	- Tests sur fixtures réelles, zéro réseau (pytest).
42	70
	71	+## Connecteurs & sources
	72	+
	73	+\| Famille \| Sources \| Accès \|
	74	+\|---\|---\|---\|
	75	+\| Billetteries \| Le point de vente, evenko (Algolia), Ticketpro, Ticket Accès, Tuxedo Billet, Ovation, Eventbrite \| API/JSON publics des billetteries \|
	76	+\| Données ouvertes officielles \| SIT Québec / Tourinsoft, Ville de Montréal (CKAN), Laval, Sherbrooke, Brossard, Longueuil \| portails de données ouvertes \|
	77	+\| Diffuseurs & salles \| La Vitrine, Place des Arts, salles via JSON-LD \| pages publiques structurées \|
	78	+\| Portails régionaux \| Montérégie, Outaouais, Lanaudière, Cantons-de-l'Est, Chaudière-Appalaches, Bas-Saint-Laurent, Gaspésie, Centre-du-Québec, Saguenay… \| calendriers régionaux publics \|
	79	+\| Autres \| Atuvu.ca (via Scrapfly), Bandsintown, LHJMQ, Québec animée \| HTML/JSON publics \|
	80	+\| Prêt (clé requise) \| Ticketmaster (`TICKETMASTER_API_KEY`) \| API officielle \|
	81	+
	82	+Cadence de resync : horaire — le watcher PM2 `sorti-ka-sync` (`run.py watch`) visite les sources en continu ; chaque événement passe par la normalisation (`schema.py` + `normalize.py`), l'upsert par hash, le délai de grâce (2 syncs) et l'alerte de dérive. Une fiche de conformité par connecteur est générée dans `docs/connecteurs/` (voir `docs/CONFORMITE.md`).
	83	+
43	84	## Architecture
44	85
45	86	```
		`@@ -55,10 +96,18 @@ run.py watch frontend/index.html web.py + seo.py`
55	96	- Base de données : SQLite — événements, diff par hash, délai de grâce, historique de syncs, géocodage (`geocode.py`, `venues.py`).
56	97	- Frontend : SPA sans build (HTML/JS, routeur History API), design system Groupe KA « éditorial sharp » (ka-ui), widget KA Agent.
57	98	- Anti-bot : Scrapfly pour Atuvu (clé `SCRAPFLY_API_KEY` dans `.env`).
58		−- Processus PM2 :
59		− - `sorti-ka-web` — uvicorn sur le port 8120 (API + frontend + SSR) ;
60		− - `sorti-ka-sync` — watcher horaire (`run.py watch`) : ingestion continue des sources ;
61		− - `sorti-ka-ngrok` — tunnel ngrok vers www.sorti-ka.com.
	99	+
	100	+## API — endpoints principaux
	101	+
	102	+\| Endpoint \| Rôle \|
	103	+\|---\|---\|
	104	+\| `GET /api/events` \| recherche filtrée : région, ville, catégorie, période, gratuité, texte, tri, pagination \|
	105	+\| `GET /api/events/{uid}` \| fiche complète d'un événement (+ SSR SEO sur `/evenement/{uid}`) \|
	106	+\| `GET /api/regions` · `GET /api/categories` \| référentiels (17 régions, 14 catégories canoniques) \|
	107	+\| `GET /api/sources` \| registre des sources et état des connecteurs \|
	108	+\| `GET /api/stats` · `/api/stats/catalog` · `/api/stats/dashboard` · `/api/stats/report(/custom)` \| tableau de bord + rapports PDF Groupe-KA \|
	109	+\| `GET /api/favorites` · `POST /api/favorites/toggle` \| favoris « Mon univers Ka » (KA ID) \|
	110	+\| `GET /api/health` · `GET /healthz` \| santé du service \|
62	111
63	112	## Structure du repo
64	113
		`@@ -66,7 +115,7 @@ run.py watch frontend/index.html web.py + seo.py`
66	115	\|---\|---\|
67	116	\| `sortika/` \| paquet Python : connecteurs, schéma `Event`, normalisation, régions MAMH, DB, web/SSR, stats, PDF, auth KA ID \|
68	117	\| `sortika/connectors/` \| un module par source (auto-découverts), base commune + `_resilient.py` \|
69		−\| `frontend/` \| SPA sans build (`index.html`, `ka-agent.js`, assets) \|
	118	+\| `frontend/` \| SPA sans build (`index.html`, `ka-agent.js`, assets) + guide `/doc` (page, images, PDF) \|
70	119	\| `data/` \| base SQLite + `villes_regions.json` (répertoire MAMH) — non versionnés pour la BD \|
71	120	\| `tests/` \| pytest sur fixtures réelles, zéro réseau \|
72	121	\| `scripts/` \| utilitaires (génération de docs, maintenance) \|
		`@@ -92,7 +141,14 @@ pm2 restart sorti-ka-web # après changement`
92	141	git add <fichiers> && git commit -m "…" && git push origin main
93	142	```
94	143
95		−Secrets (gabarit `.env.example`) : `SCRAPFLY_API_KEY` (Atuvu), `TICKETMASTER_API_KEY` (active le connecteur Ticketmaster).
	144	+### Configuration notable (sans secrets)
	145	+
	146	+\| Variable \| Rôle \|
	147	+\|---\|---\|
	148	+\| `SCRAPFLY_API_KEY` \| anti-bot pour le connecteur Atuvu.ca \|
	149	+\| `TICKETMASTER_API_KEY` \| active le connecteur Ticketmaster (prêt, en attente de clé) \|
	150	+
	151	+Gabarit : `.env.example` — aucun secret n'est versionné.
96	152
97	153	## Déploiement
98	154
		@@ -100,24 +156,42 @@ Secrets (gabarit `.env.example`) : `SCRAPFLY_API_KEY` (Atuvu), `TICKETMASTER_API
100	156	\|---\|---\|
101	157	\| Nœud \| M3U96a (cluster MacLustr) — `~/apps/sorti-ka` \|
102	158	\| Port \| 8120 \|
103		−\| Processus PM2 \| `sorti-ka-web` (uvicorn) + `sorti-ka-sync` (watcher horaire) + `sorti-ka-ngrok` (tunnel) \|
104	159	\| Domaine \| [www.sorti-ka.com](https://www.sorti-ka.com) via tunnel ngrok \|
105	160
	161	+\| Processus PM2 \| Rôle \|
	162	+\|---\|---\|
	163	+\| `sorti-ka-web` \| uvicorn sur le port 8120 — API + frontend + SSR SEO \|
	164	+\| `sorti-ka-sync` \| watcher horaire (`run.py watch`) — ingestion continue des sources \|
	165	+\| `sorti-ka-ngrok` \| tunnel ngrok vers www.sorti-ka.com \|
	166	+
	167	+## Documentation
	168	+
	169	+- Guide utilisateur en ligne : [www.sorti-ka.com/doc/](https://www.sorti-ka.com/doc/) — à quoi sert le site, utilisation en 4 étapes, provenance des données, FAQ.
	170	+- Guide PDF téléchargeable : [sorti-ka-documentation.pdf](https://www.sorti-ka.com/doc/sorti-ka-documentation.pdf).
	171	+- Conformité & connecteurs : `docs/CONFORMITE.md` + une fiche par connecteur dans `docs/connecteurs/`.
	172	+
106	173	## Écosystème Groupe KA
107	174
108		−- [groupe-ka.com](https://www.groupe-ka.com) — portail
109		−- [lou-ka.com](https://www.lou-ka.com) — logements à louer
110		−- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre
111		−- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière
112		−- [auto-ka.com](https://www.auto-ka.com) — véhicules
113		−- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois
114		−- [food-ka.com](https://www.food-ka.com) — épicerie / alimentation
115		−- [resto-ka.com](https://www.resto-ka.com) — restaurants
116		−- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements
117		−- [job-ka.com](https://www.job-ka.com) — emplois
118		−- [crea-ka.com](https://www.crea-ka.com) — créateurs
119		−- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces
120		−- [api-ka.com](https://www.api-ka.com) — API de données
	175	+\| Site \| Univers \|
	176	+\|---\|---\|
	177	+\| [groupe-ka.com](https://www.groupe-ka.com) \| portail \|
	178	+\| [lou-ka.com](https://www.lou-ka.com) \| logements à louer \|
	179	+\| [immo-ka.com](https://www.immo-ka.com) \| propriétés à vendre \|
	180	+\| [vrai-prix.com](https://www.vrai-prix.com) \| estimation immobilière \|
	181	+\| [auto-ka.com](https://www.auto-ka.com) \| véhicules \|
	182	+\| [fabri-ka.com](https://www.fabri-ka.com) \| produits québécois \|
	183	+\| [food-ka.com](https://www.food-ka.com) \| épicerie / alimentation \|
	184	+\| [resto-ka.com](https://www.resto-ka.com) \| restaurants \|
	185	+\| [sorti-ka.com](https://www.sorti-ka.com) \| sorties et événements \|
	186	+\| [job-ka.com](https://www.job-ka.com) \| emplois \|
	187	+\| [crea-ka.com](https://www.crea-ka.com) \| créateurs \|
	188	+\| [trouve-ka.com](https://www.trouve-ka.com) \| petites annonces \|
	189	+\| [api-ka.com](https://www.api-ka.com) \| API de données \|
	190	+
	191	+## Contact
	192	+
	193	+Simon-Pierre Boucher — fondateur, Groupe KA
	194	+📧 [contact@spboucher.ai](mailto:contact@spboucher.ai)
121	195
122	196	---
123	197
124	198