docs: refonte du README (pastilles + captures d écran à jour)
3 changed files +85 −131
modified
README.md
+85 −131
@@ -1,167 +1,121 @@ | ||
| 1 | −<!-- | |
| 2 | − Author: Simon-Pierre Boucher <contact@spboucher.ai> | |
| 3 | − File: README.md | |
| 4 | − Desc: Créa·Ka — agrégateur des créateurs de contenu québécois | |
| 5 | −--> | |
| 6 | −<div align="center"> | |
| 1 | +<!-- Auteur : Simon-Pierre Boucher — contact@spboucher.ai --> | |
| 7 | 2 | |
| 8 | 3 | # Créa·Ka |
| 9 | 4 | |
| 10 | −**Tous les créateurs québécois. Tous leurs liens.** | |
| 5 | +**Tous les créateurs de contenu québécois, tous leurs liens — un annuaire public cross-plateforme, croisement entre un annuaire cherchable et un « Linktree collectif ».** | |
| 11 | 6 | |
| 12 | − | |
| 7 | +[](https://www.crea-ka.com) | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 13 | 11 | |
| 14 | −[](https://www.crea-ka.com) | |
| 15 | −[](https://www.crea-ka.com/stats) | |
| 16 | −[](https://www.crea-ka.com) | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | 17 | |
| 18 | −[](https://www.python.org) | |
| 19 | −[](creaka/web.py) | |
| 20 | −[](frontend/src/index.template.html) | |
| 21 | −[](tests/) | |
| 22 | −[](creaka/connectors/) | |
| 23 | −[](https://www.crea-ka.com) | |
| 18 | +**Créa·Ka** ([www.crea-ka.com](https://www.crea-ka.com)) est l'**annuaire public, québécois et cross-plateforme des créateurs de contenu**. Chaque créateur québécois a **une fiche canonique** qui regroupe **tous ses comptes publics** — Instagram, TikTok, YouTube, Twitch, X, Facebook, Snapchat, Kick, Substack, Patreon, OnlyFans, balado… — chacun avec son URL canonique, ses métriques (abonnés, publications, j'aime, vues, épisodes) et son **score de confiance de rattachement**. | |
| 24 | 19 | |
| 25 | −**https://www.crea-ka.com** | |
| 20 | +Pour qui ? Le public qui découvre des créateurs par niche, région, langue ou taille d'audience ; les créateurs eux-mêmes (fiche, opt-out) ; les marques et médias qui cherchent un annuaire public là où les bases existantes sont payantes, généralistes et anglophones. L'**éthique prime sur tout** : profils publics et professionnels seulement, purge des données privées, opt-out immédiat et persistant, régime restreint des mineurs, conformité Loi 25. | |
| 26 | 21 | |
| 27 | −</div> | |
| 22 | +## Captures d'écran | |
| 28 | 23 | |
| 29 | −--- | |
| 24 | +<p align="center"> | |
| 25 | + <img src="docs/screenshots/crea-ka-desktop.png" width="640" alt="Accueil — desktop"> | |
| 26 | + <img src="docs/screenshots/crea-ka-mobile.png" width="200" alt="Accueil — mobile"> | |
| 27 | +</p> | |
| 30 | 28 | |
| 31 | −## Description | |
| 29 | +## Fonctionnalités | |
| 32 | 30 | |
| 33 | −**Créa·Ka** est l'**annuaire public, québécois et cross-plateforme des créateurs de contenu** — un croisement entre un **annuaire cherchable** et un **« Linktree collectif »**, membre de la famille **Groupe Ka**. | |
| 31 | +- **Annuaire filtrable** par niche (20), région (17 régions administratives), langue, plateforme et taille d'audience (nano/micro/macro/méga). | |
| 32 | +- **Page dédiée par créateur** — `/createur/{id}` avec tous ses liens et métriques. | |
| 33 | +- **Pages SEO programmatiques** — `/plateformes` + `/plateforme/{p}` rendues en HTML. | |
| 34 | +- **Tableau de bord analytique** `/stats` + rapports PDF aux couleurs Groupe KA (catalogue + ReportBuilder). | |
| 35 | +- **API publique** — `GET /api/creators` (filtres q/niche/region/langue/plateforme/tier), `/api/creators/{id}`, `/api/stats`, `/api/taxonomies`, `/api/sources`, `POST /api/optout`, `/healthz`. | |
| 36 | +- **Connexion « Se connecter avec KA ID »** (SSO du hub groupe-ka.com) + favoris unifiés « Mon univers Ka ». | |
| 37 | +- **Widget KA Agent** — bulle de chat IA du Groupe KA câblée sur le site. | |
| 38 | +- **Couverture cumulative** — un watch quotidien relance découverte + enrichissement : nouveaux créateurs, métriques rafraîchies, comptes croisés révélés via les liens de bio et les pages link-in-bio. | |
| 39 | +- **Score de confiance** sur chaque rattachement de compte — sous 0.50 → « à vérifier », jamais publié ; fusion des doublons uniquement sur compte fort partagé, **jamais sur le nom** (homonymes). | |
| 40 | +- **Opt-out immédiat et persistant** (`/retrait`) : fiche masquée sur-le-champ, liste de suppression `data/optout.json`, jamais ré-agrégée. | |
| 34 | 41 | |
| 35 | −Chaque créateur québécois a **une fiche canonique** qui regroupe **tous ses comptes publics** — **Instagram, TikTok, YouTube, Twitch, X, Facebook, Snapchat, Kick, Substack, Patreon, OnlyFans, balado**… — chacun avec son **URL canonique**, ses **métriques** (abonnés, publications, j'aime, vues, épisodes) et son **score de confiance de rattachement**. | |
| 42 | +## Architecture | |
| 36 | 43 | |
| 37 | −## Fonctionnalités | |
| 44 | +Pipeline (calqué sur Lou·Ka) : **découverte → extraction → résolution d'identité → normalisation → déduplication → SQLite → API/UI**. | |
| 38 | 45 | |
| 39 | −- **Annuaire filtrable** par **niche** (20), **région** (17 régions administratives), **langue**, **plateforme** et **taille d'audience** (**nano/micro/macro/méga**). | |
| 40 | −- **Page dédiée par créateur** : `/createur/{id}` avec tous ses liens et métriques. | |
| 41 | −- **Tableau de bord analytique** `/stats` + **rapport PDF** aux couleurs Groupe-KA. | |
| 42 | −- **Connexion « Se connecter avec KA ID »** via le hub **groupe-ka.com** (SSO de l'écosystème). | |
| 43 | −- **Widget KA Agent** (bulle de chat IA Groupe KA) câblé sur le site. | |
| 44 | −- **Couverture cumulative** : un **watch quotidien** relance découverte + enrichissement — nouveaux créateurs, métriques rafraîchies, comptes croisés révélés via les **liens de bio** et les pages **link-in-bio**. | |
| 45 | −- **Opt-out immédiat et persistant** (`/retrait`) et **éthique stricte** (voir plus bas). | |
| 46 | +- **Backend Python 3.14 / FastAPI** (`creaka/web.py`) : API + service du frontend statique. | |
| 47 | +- **SQLite (mode WAL)** (`creaka/db.py`) : fiches canoniques, index des comptes, journal des syncs. | |
| 48 | +- **Résolution d'identité** (`creaka/identity.py`) : signaux pondérés (`profil_source` 0.98 · `link_in_bio` 0.95 · `cross_link` 0.90 · listes/bases publiques 0.85 · `handle_match` 0.75). | |
| 49 | +- **10 connecteurs** auto-découverts (`creaka/connectors/`) — découverte (listes-medias, wikidata-qc, onlyqueb, youtube-recherche, balados-itunes) et enrichissement (instagram-profil, tiktok-profil, youtube, twitch, link-in-bio via Scrapfly/API officielles). | |
| 50 | +- **Éthique** (`creaka/ethics.py`) : purge des données privées, opt-out, régime restreint des mineurs. | |
| 51 | +- **Frontend SPA zéro build** — template HTML généré par `scripts/build_frontend.py` (icônes SVG injectées), design ka-ui « éditorial sharp », footer commun (`ecosystem.json`). | |
| 52 | +- **25 tests pytest** (identité, homonymes, éthique…). | |
| 46 | 53 | |
| 47 | −## Architecture (calquée sur Lou·Ka) | |
| 54 | +Processus PM2 sur le nœud : | |
| 48 | 55 | |
| 49 | −``` | |
| 50 | −DÉCOUVERTE → EXTRACTION → RÉSOLUTION D'IDENTITÉ → NORMALISATION → DÉDUP. → SQLite → API/UI | |
| 51 | −``` | |
| 52 | − | |
| 53 | −| Module | Rôle | | |
| 56 | +| Processus | Rôle | | |
| 54 | 57 | |---|---| |
| 55 | −| `creaka/schema.py` | fiche **`Creator`** + **`PlatformAccount`**, **validation stricte** (compte sans url/confidence = rejeté) | | |
| 56 | −| `creaka/identity.py` | **signaux de rattachement** §12.1 : `profil_source` 0.98 · `link_in_bio` 0.95 · `cross_link` 0.90 · `listes_medias`/`base_publique` 0.85 · `handle_match` 0.75 | | |
| 57 | −| `creaka/dedup.py` | fusion **uniquement** sur compte fort partagé — **jamais sur le nom** (homonymes) | | |
| 58 | −| `creaka/ethics.py` | **purge des données privées**, opt-out persistant, **régime restreint des mineurs** | | |
| 59 | −| `creaka/db.py` | **SQLite WAL** : fiches canoniques + index des comptes + journal des syncs | | |
| 60 | −| `creaka/auth.py` | connexion **KA ID** (hub groupe-ka.com) | | |
| 61 | −| `creaka/stats.py` + `creaka/kapdf.py` | statistiques `/stats` + **rapport PDF** | | |
| 62 | −| `creaka/web.py` | **API FastAPI** + frontend statique | | |
| 63 | − | |
| 64 | −### Connecteurs (registre auto-découvrant — `creaka/connectors/`) | |
| 65 | − | |
| 66 | −| Connecteur | Famille | Accès | Signal | | |
| 67 | −|---|---|---|---| | |
| 68 | −| `listes-medias` | découverte | dataset local (palmarès médias publics croisés, **376 profils**) | 0.85 | | |
| 69 | −| `wikidata-qc` | découverte | **SPARQL Wikidata** (nés/résidant au QC, handles curés) | 0.85 | | |
| 70 | −| `onlyqueb` | découverte | sitemap + JSON-LD (annuaire public, liens auto-déclarés) | 0.90 | | |
| 71 | −| `youtube-recherche` | découverte | recherche publique YouTube, ~120 requêtes × **marqueur QC obligatoire**, pagination par continuations | 0.98 | | |
| 72 | −| `balados-itunes` | découverte | **API officielle** iTunes/Apple Podcasts | 0.98 | | |
| 73 | −| `instagram-profil` | enrichissement | Scrapfly (profil public : abonnés, bio, **liens de bio** → cross-link) | — | | |
| 74 | −| `tiktok-profil` | enrichissement | Scrapfly (JSON d'hydratation public) | — | | |
| 75 | −| `youtube` | enrichissement | **API officielle v3** si clé, sinon page publique | — | | |
| 76 | −| `twitch` | enrichissement | **API officielle Helix** (sauté sans clés) | — | | |
| 77 | −| `link-in-bio` | enrichissement | Linktree/Beacons/Bio.link… — **le levier nº 1** : une page → tous les comptes | 0.95 | | |
| 78 | − | |
| 79 | −## Stack | |
| 80 | − | |
| 81 | −- **Python 3.14** · **FastAPI** · **SQLite (mode WAL)** | |
| 82 | −- **Frontend SPA zéro build** (template HTML + `scripts/build_frontend.py`, icônes SVG injectées) | |
| 83 | −- Design **ka-ui « éditorial sharp »** Groupe KA — accent violet, footer commun (`ecosystem.json`, 13 sites), page `/contact` | |
| 84 | −- **25 tests** pytest (identité, homonymes, éthique…) | |
| 85 | −- Hébergé sous **PM2** + tunnel **ngrok** | |
| 86 | − | |
| 87 | −## API publique | |
| 58 | +| `crea-ka-web` | API FastAPI + frontend sur le port **8160** | | |
| 59 | +| `crea-ka-sync` | watch de synchronisation (24 h) : découverte + enrichissement | | |
| 60 | +| `crea-ka-ngrok` | tunnel ngrok vers **www.crea-ka.com** | | |
| 88 | 61 | |
| 89 | −``` | |
| 90 | −GET /api/creators?q&niche®ion&langue&plateforme&tier&sort&limit&offset | |
| 91 | −GET /api/creators/{id} GET /api/stats GET /api/taxonomies | |
| 92 | −GET /api/sources POST /api/optout GET /healthz | |
| 93 | −``` | |
| 94 | − | |
| 95 | −## Structure du projet | |
| 62 | +## Structure du repo | |
| 96 | 63 | |
| 97 | 64 | ``` |
| 98 | 65 | crea-ka/ |
| 99 | −├── creaka/ # cœur Python : schema, identity, dedup, ethics, db, web, auth, stats | |
| 100 | −│ └── connectors/ # 10 connecteurs (découverte + enrichissement) | |
| 101 | −├── frontend/ # src/ (template) → dist/ (généré) | |
| 102 | −├── scripts/ # build_frontend.py · deploy-m3u96b.sh · screenshots.sh | |
| 103 | −├── tests/ # 25 tests pytest | |
| 104 | −├── data/ # SQLite, optout.json, datasets locaux | |
| 105 | −├── docs/ # screenshot.png + captures | |
| 106 | −└── run.py # CLI : sync · serve · optout | |
| 66 | +├── run.py # CLI : sync · serve · optout | |
| 67 | +├── creaka/ # cœur Python : schema, identity, dedup, ethics, db, web, auth, stats, kapdf + connectors/ (10) | |
| 68 | +├── frontend/ # src/ (template) → dist/ (généré par build_frontend.py) | |
| 69 | +├── scripts/ # build_frontend.py · deploy-m3u96b.sh · screenshots.sh | |
| 70 | +├── tests/ # 25 tests pytest | |
| 71 | +├── data/ # SQLite, optout.json, datasets locaux (gitignorés au besoin) | |
| 72 | +├── actors/ # acteurs Apify d'appoint | |
| 73 | +└── docs/ # captures d'écran + docs connecteurs | |
| 107 | 74 | ``` |
| 108 | 75 | |
| 109 | −## Démarrage local | |
| 76 | +## Développement (remote-first) | |
| 77 | + | |
| 78 | +**La source de vérité est le repo git sur le nœud M3U96b** (`~/apps/crea-ka`) — on n'édite jamais les copies laptop. Toute modification se fait sur le nœud via SSH : édition, tests, `pm2 restart`, puis commit/push depuis le nœud. | |
| 79 | + | |
| 80 | +- Remote `origin` = **spbgit** (git perso [git.spboucher.ai](https://git.spboucher.ai), bare repos sur M3U96a). **Pas GitHub.** | |
| 81 | +- L'agent forwarding SSH est actif : le `git push origin main` fonctionne pendant une session SSH depuis le laptop. | |
| 110 | 82 | |
| 111 | 83 | ```bash |
| 112 | 84 | python3 -m venv .venv && .venv/bin/pip install -r requirements.txt |
| 113 | 85 | cp .env.example .env # SCRAPFLY_KEY, YOUTUBE_API_KEY… |
| 114 | −python3 -m pytest tests/ -q # 25 tests (identité, homonymes, éthique…) | |
| 86 | +python3 -m pytest tests/ -q # 25 tests | |
| 115 | 87 | python3 run.py sync # découverte + enrichissement |
| 116 | −python3 run.py serve 8160 # API + frontend → http://localhost:8160 | |
| 117 | −python3 scripts/build_frontend.py # regénère frontend/dist (icônes SVG injectées) | |
| 88 | +python3 run.py serve 8160 # API + frontend | |
| 89 | +python3 scripts/build_frontend.py # regénère frontend/dist | |
| 118 | 90 | python3 run.py optout "instagram:handle" # retrait manuel |
| 91 | + | |
| 92 | +pm2 restart crea-ka-web # après un changement en production | |
| 119 | 93 | ``` |
| 120 | 94 | |
| 121 | 95 | ## Déploiement |
| 122 | 96 | |
| 123 | −- **Nœud** : **M3U96b** (`~/apps/crea-ka`) | |
| 124 | −- **Port** : **8160** | |
| 125 | −- **Domaine** : **www.crea-ka.com** (tunnel **ngrok**) | |
| 126 | −- **PM2** (3 process) : | |
| 127 | − - **`crea-ka-web`** — API FastAPI + frontend sur **:8160** | |
| 128 | − - **`crea-ka-sync`** — watch de synchronisation (**24 h**) : découverte + enrichissement | |
| 129 | − - **`crea-ka-ngrok`** — tunnel vers **www.crea-ka.com** | |
| 130 | −- Redéploiement : `scripts/deploy-m3u96b.sh` · captures : `scripts/screenshots.sh` | |
| 131 | − | |
| 132 | −## Développement remote-first (IMPORTANT) | |
| 133 | − | |
| 134 | −La **source de vérité est le repo git sur le nœud M3U96b** (`~/apps/crea-ka`), **pas** une copie laptop. Toute modification se fait **sur le nœud via SSH** (édition, tests, `pm2 restart`), puis commit/push **depuis le nœud**. | |
| 135 | − | |
| 136 | −- **`origin` = spbgit** (git perso **git.spboucher.ai** — bare repo `~/srv/git/crea-ka.git` sur M3U96a, alias SSH `gitsrv`). **Pas GitHub.** | |
| 137 | −- L'**agent forwarding** SSH est actif : le `git push origin main` fonctionne pendant une session SSH depuis le laptop. | |
| 138 | − | |
| 139 | −## Éthique — prime sur tout | |
| 140 | − | |
| 141 | −- **Profils publics et professionnels seulement** ; `ethics.scrub()` **purge téléphones, adresses civiques et courriels personnels** avant tout stockage. | |
| 142 | −- **Opt-out immédiat et persistant** (`/retrait`) : fiche masquée sur-le-champ, liste de suppression `data/optout.json`, **jamais ré-agrégée**. | |
| 143 | −- **Mineurs** : régime restreint automatique (année de naissance Wikidata) et **exclusion de l'annuaire public**. | |
| 144 | −- **Score de confiance** sur chaque rattachement ; **sous 0.50 → « à vérifier », jamais publié**. Mieux vaut un lien de moins qu'un lien erroné. | |
| 145 | −- **Loi 25** : finalités documentées, accès/rectification/retrait via `/retrait`. | |
| 146 | − | |
| 147 | −## Captures supplémentaires | |
| 148 | − | |
| 149 | −| Accueil (annuaire) | Page créateur | | |
| 150 | −|---|---| | |
| 151 | −|  |  | | |
| 152 | − | |
| 153 | −| Statistiques | Mobile (tab bar Lou·Ka) | | |
| 154 | −|---|---| | |
| 155 | −|  |  | | |
| 97 | +- **Nœud** : M3U96b (Mac Studio, cluster MacLustr) — répertoire `~/apps/crea-ka` | |
| 98 | +- **Port** : **8160** (local, exposé uniquement via le tunnel) | |
| 99 | +- **Processus PM2** : `crea-ka-web` (serveur) + `crea-ka-sync` (synchro) + `crea-ka-ngrok` (tunnel) | |
| 100 | +- **Domaine** : **https://www.crea-ka.com** (tunnel ngrok) | |
| 101 | + | |
| 102 | +## Écosystème Groupe KA | |
| 103 | + | |
| 104 | +- [groupe-ka.com](https://www.groupe-ka.com) — portail du groupe et compte unique KA ID | |
| 105 | +- [lou-ka.com](https://www.lou-ka.com) — logements à louer | |
| 106 | +- [immo-ka.com](https://www.immo-ka.com) — propriétés à vendre | |
| 107 | +- [vrai-prix.com](https://www.vrai-prix.com) — estimation immobilière | |
| 108 | +- [auto-ka.com](https://www.auto-ka.com) — véhicules | |
| 109 | +- [fabri-ka.com](https://www.fabri-ka.com) — produits québécois | |
| 110 | +- [food-ka.com](https://www.food-ka.com) — épicerie et alimentation | |
| 111 | +- [resto-ka.com](https://www.resto-ka.com) — restaurants | |
| 112 | +- [sorti-ka.com](https://www.sorti-ka.com) — sorties et événements | |
| 113 | +- [job-ka.com](https://www.job-ka.com) — emplois | |
| 114 | +- [crea-ka.com](https://www.crea-ka.com) — créateurs de contenu *(ce repo)* | |
| 115 | +- [trouve-ka.com](https://www.trouve-ka.com) — petites annonces | |
| 116 | +- [api-ka.com](https://www.api-ka.com) — API de données | |
| 156 | 117 | |
| 157 | 118 | --- |
| 158 | 119 | |
| 159 | −<div align="center"> | |
| 160 | − | |
| 161 | −Un service **Groupe Ka** · [KA ID](https://www.groupe-ka.com) · [Lou-Ka](https://www.lou-ka.com) · | |
| 162 | −[Immo-Ka](https://www.immo-ka.com) · [Auto-Ka](https://www.auto-ka.com) · | |
| 163 | −[Food-Ka](https://www.food-ka.com) · [Fabri-Ka](https://www.fabri-ka.com) | |
| 164 | − | |
| 165 | −© Simon-Pierre Boucher — <contact@spboucher.ai> | |
| 166 | − | |
| 167 | −</div> | |
| 120 | +© Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai | |
| 121 | +Ce repo vit sur **spbgit** ([git.spboucher.ai](https://git.spboucher.ai)). | |
added
docs/screenshots/crea-ka-desktop.png
+0 −0
Binary file not shown.
added
docs/screenshots/crea-ka-mobile.png
+0 −0
Binary file not shown.