# CLAUDE.md — Créa·Ka

Agrégateur exhaustif des créateurs de contenu et influenceurs québécois, avec liens vers TOUTES leurs plateformes. Chaque créateur, tous ses comptes (Instagram, TikTok, YouTube, Twitch, X, Facebook, Snapchat, Kick, Substack, Patreon…), regroupés, cherchables et découvrables par niche, région, langue et taille d'audience.

Ce fichier est la source de vérité pour tout agent Claude (ou humain) qui travaille sur ce dépôt. Lis-le en entier avant d'écrire une seule ligne de code.

# 0. À LIRE EN PREMIER — Règles non négociables

1. En-tête d'auteur obligatoire. Chaque fichier du dépôt (code, config, doc, script) doit commencer par un en-tête mentionnant l'auteur : Simon-Pierre Boucher <contact@spboucher.ai>. Voir la section 17 pour le format exact. Aucun fichier ne doit être commité sans cet en-tête.

2. Inspire-toi du dépôt Lou·Ka. Avant de concevoir ou d'écrire le moindre connecteur, va lire le dépôt de Lou·Ka (le site jumeau, agrégateur de logements). Ses connecteurs sont le patron de référence : structure des modules, extraction (Firecrawl / Scrapfly), normalisation, déduplication, gestion des mises à jour, planification. Ne réinvente rien : reprends les mêmes conventions, la même architecture, les mêmes utilitaires partagés. Créa·Ka doit être cohérent avec l'écosystème ·Ka. Voir section 3.

3. Travail de moine. L'agrégation est minutieuse, créateur par créateur, plateforme par plateforme, sans rien précipiter. Un mauvais rattachement de compte (attribuer à un créateur un profil qui n'est pas le sien) est une faute grave. Mieux vaut un lien vérifié de moins qu'un lien erroné.

4. Vérifie l'existant avant d'ajouter. Avant d'intégrer un créateur ou une source, confirme qu'il/elle n'est pas déjà couvert(e) (index créateurs, registre des sources — sections 9 et 12). Un créateur = une fiche canonique, quelles que soient les plateformes et sources qui l'alimentent.

5. Chaque plateforme a son connecteur sur mesure, mais les sources qui partagent une même mécanique (API d'une plateforme, agrégateurs de liens type Linktree) sont couvertes par un connecteur générique templatisé réutilisable. Voir section 8.

6. VIE PRIVÉE & ÉTHIQUE — règle sacrée. Créa·Ka n'agrège que des profils publics et professionnels de créateurs qui se présentent publiquement comme tels. Jamais de données privées, de coordonnées personnelles non publiées, ni de compilation intrusive. Mécanisme d'opt-out obligatoire. Prudence extrême avec les créateurs mineurs. Voir section 15 — cette section prime sur toute autre considération de complétude ou de volume.

# 1. Mission

Rendre visible, en un seul endroit, l'ensemble des créateurs de contenu et influenceurs québécois, avec un lien direct vers chacune de leurs plateformes, et permettre de les découvrir par niche, région, langue et taille d'audience.

En clair : un croisement entre un annuaire (recherche et découverte) et un « Linktree collectif » (tous les comptes d'un créateur au même endroit), centré sur le Québec.

# Ce qui nous distingue

Les bases d'influenceurs existantes (Heepsy, Upfluence, HypeAuditor) sont payantes, généralistes et anglophones, pensées pour les marques. Les « tops influenceurs » des médias québécois sont ponctuels et non exhaustifs. Personne n'offre un annuaire public, québécois, exhaustif et cross-plateforme. C'est le créneau de Créa·Ka.

# 2. Périmètre — TOUS les créateurs québécois

Périmètre maximaliste. Si la personne crée du contenu publiquement et a une audience au Québec, elle a sa place :

• Influenceurs (Instagram, TikTok, Snapchat) : mode, beauté, lifestyle, famille.
• YouTubeurs : vlog, humour, gaming, tech, éducation, cuisine.
• Streamers : Twitch, Kick, YouTube Live (gaming, IRL, just chatting).
• Créateurs TikTok toutes niches.
• Podcasteurs et créateurs audio.
• Créateurs écrits : Substack, blogues, infolettres.
• Créateurs sur abonnement : Patreon (contenu grand public/professionnel).
• Créateurs de niche : sport, plein air, finance, humour, musique, arts, cuisine, parentalité, tech, jeux vidéo, etc.
• Micro et nano-créateurs locaux (souvent ignorés des bases existantes).

Règle d'or : en cas de doute sur l'inclusion, on inclut et on catégorise — sauf si la règle de vie privée/éthique (section 15) s'y oppose.

# 3. Dépôts de référence — étudier Lou·Ka AVANT de coder

Créa·Ka fait partie de la famille ·Ka. Le dépôt de Lou·Ka est la référence canonique pour l'architecture des connecteurs. Avant tout développement :

1. Ouvrir le dépôt de Lou·Ka et localiser le dossier des connecteurs (typiquement connectors/, scrapers/ ou sources/).
2. Lire 2 ou 3 connecteurs complets pour comprendre : structure d'un module, extraction (Firecrawl / Scrapfly, endpoints JSON), normalisation, déduplication, mises à jour, planification (cadence, retries, backoff), erreurs, logging.
3. Réutiliser les utilitaires partagés de Lou·Ka (clients Firecrawl/Scrapfly, helpers de normalisation, déduplication, géocodage) plutôt que d'en réécrire.
4. Calquer conventions de nommage, structure des dossiers et style de code.

Adaptation propre à Créa·Ka : là où Lou·Ka normalise une annonce, Créa·Ka normalise un créateur + N comptes de plateformes rattachés. Le défi central n'est pas le volume par source mais la résolution d'identité : rattacher les bons comptes à la bonne personne (section 12).

Si tu ne trouves pas le dépôt Lou·Ka ou l'accès aux connecteurs, arrête-toi et demande plutôt que d'inventer une architecture divergente.

Écosystème complet, pour contexte :

# 4. Architecture

Pipeline ·Ka, adapté aux créateurs (l'étape clé en plus : résolution d'identité) :

  ┌────────────┐   ┌────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────┐   ┌────────┐
  │ DÉCOUVERTE │──▶│ EXTRACTION │──▶│ RÉSOLUTION   │──▶│ NORMALISATION│──▶│ DÉDUP.   │──▶│STOCKAGE│
  │ (trouver   │   │ FC/Scrapfly│   │ D'IDENTITÉ   │   │ (schéma      │   │ (créateur│   │  (DB)  │
  │  créateurs)│   │ + APIs     │   │ (lier comptes)│   │  commun)     │   │  unique) │   │        │
  └────────────┘   └────────────┘   └──────────────┘   └──────────────┘   └──────────┘   └───┬────┘
                                                                                             │
                                                                                  ┌──────────▼──────────┐
                                                                                  │ API / RECHERCHE / UI │
                                                                                  │ (annuaire + liens)   │
                                                                                  └─────────────────────┘

• Découverte : trouver les créateurs québécois (hashtags, géo, listes, agences).
• Extraction : enrichir chaque profil (bio, abonnés, liens) via API ou scraping.
• Résolution d'identité : rattacher tous les comptes d'une même personne (souvent via sa page de liens type Linktree).
• Normalisation / Déduplication / Stockage : une fiche créateur canonique.
• API / UI : recherche et découverte par niche, région, langue, taille.

# 5. Modèle de données — schéma Créateur + Plateformes

{
  "id": "string",                       // * id interne canonique
  "source_ids": ["linktree:handle"],    // * id(s) d'origine par source
  "display_name": "string",             // * nom public / nom de scène
  "legal_name": "string|null",          // seulement si rendu public par le créateur
  "bio": "string",                      // bio publique agrégée / résumée
  "niches": ["humour", "gaming"],       // * taxonomie (section 6)
  "creator_type": "streamer",           // influenceur|youtubeur|streamer|podcasteur|...
  "region": "string",                   // une des 17 régions si connu (section 7)
  "city": "string|null",
  "languages": ["fr"],                  // fr | en | bilingue
  "primary_platform": "youtube",        // * plateforme principale
  "platforms": [                        // * TOUS les comptes rattachés
    {
      "platform": "youtube",            // * (section 6.2)
      "handle": "@nom",                 // *
      "url": "https://youtube.com/@nom",// *
      "followers": 125000,              // abonnés (peut être null)
      "verified": true,
      "confidence": 0.98,               // * confiance du rattachement (section 12)
      "last_checked": "ISO-8601"        // *
    }
  ],
  "link_in_bio_url": "https://linktr.ee/nom", // page de liens source, si trouvée
  "total_reach": 350000,                // somme dédupliquée des audiences (indicatif)
  "audience_tier": "macro",             // section 6.3
  "business_contact": "string|null",    // courriel pro SEULEMENT si public (section 15)
  "agency": "string|null",              // agence / management si public
  "is_minor": false,                    // * drapeau si le créateur est mineur (§15)
  "status": "active",                   // active | inactive | opted_out
  "first_seen": "ISO-8601",             // *
  "last_seen":  "ISO-8601",             // *
  "updated_at": "ISO-8601"              // *
}

Règles :

• platforms est le cœur : tous les comptes publics, chacun avec son url et son confidence de rattachement.
• Ne jamais inscrire legal_name, business_contact ou toute coordonnée non rendue publique par le créateur lui-même (section 15).
• is_minor : si détecté, appliquer le régime restreint de la section 15.

# 6. Taxonomies

# 6.1 Niches

humour · mode · beaute · lifestyle · famille-parentalite · cuisine · gaming · tech · sport-fitness · plein-air · voyage · musique · arts · danse · education · finance-affaires · sante-mieux-etre · bouffe-resto · actualite-opinion · autre

# 6.2 Plateformes (platform)

instagram · tiktok · youtube · twitch · kick · x · facebook · snapchat · substack · patreon · linkedin · threads · podcast · site-web · autre

# 6.3 Taille d'audience (audience_tier) — basée sur l'audience principale

• nano (< 10k) · micro (10k–100k) · macro (100k–1M) · mega (> 1M).

# 6.4 Langue

fr · en · bilingue

# 7. Régions du Québec (quand connu)

Bas-Saint-Laurent · Saguenay–Lac-Saint-Jean · Capitale-Nationale · Mauricie · Estrie · Montréal · Outaouais · Abitibi-Témiscamingue · Côte-Nord · Nord-du-Québec · Gaspésie–Îles-de-la-Madeleine · Chaudière-Appalaches · Laval · Lanaudière · Laurentides · Montérégie · Centre-du-Québec.

La région est souvent inconnue ou non déclarée pour un créateur — c'est acceptable (region: null). Ne jamais deviner ou inférer une localisation précise à partir de données privées. Se limiter à ce que le créateur déclare publiquement.

# 8. Philosophie des connecteurs

• Deux familles de connecteurs :
  1. Découverte — trouver de nouveaux créateurs québécois (hashtags, géo, listes médias, agences, palmarès).
  2. Enrichissement — pour un handle donné, récupérer profil, abonnés, liens.
• Le levier nº 1 : les pages de liens (link-in-bio). Linktree, Beacons, Linkin.bio, etc. exposent d'un coup tous les comptes d'un créateur → c'est la source la plus efficace pour remplir platforms. Un connecteur générique « link-in-bio » (templatisé par service) est prioritaire.
• Connecteurs templatisés par plateforme pour l'enrichissement (un connecteur YouTube, un Twitch, etc.), à réutiliser pour tous les créateurs.
• Interface commune (à calquer sur Lou·Ka) : fetch() → normalize() → emit(). Idempotent, incrémental quand c'est possible.
• Robustesse : timeouts, retries + backoff, tolérance aux changements, alerte si un connecteur cesse de retourner des données (probable blocage).

# 9. Catalogue des sources à connecter (priorisé)

⚠️ Vérifie l'index des créateurs et le registre des sources avant d'ajouter.

# Palier 1 — Pages de liens (link-in-bio) : révèlent toutes les plateformes

• Linktree, Beacons, Linkin.bio (Later), Milkshake, Campsite, Snipfeed. Une seule page → tous les comptes du créateur. À templatiser.

# Palier 2 — API officielles des plateformes (enrichissement fiable)

• YouTube Data API, Twitch API, X/Threads API (selon accès), TikTok et Instagram (via API officielles/Graph quand disponibles). Respecter quotas et CGU. À privilégier sur le scraping.

# Palier 3 — Découverte de créateurs québécois

• Hashtags & mots-clés : #quebec, #mtl, #madeinquebec, #créateurquébécois, etc.
• Signaux de langue (français) et de lieu déclarés publiquement.
• Listes et palmarès médias (« influenceurs québécois »), articles de presse.
• Palmarès / galas du milieu (récompenses de création numérique).
• Agences de talents / management québécoises (rosters publics).

# Palier 4 — Profils publics des plateformes (scraping encadré)

• Pages de profil publiques (bio, liens, abonnés) quand l'API ne suffit pas — Scrapfly requis, CGU à respecter, voir section 15.

# Palier 5 — Créateurs sur abonnement / écrits

• Substack, Patreon (pages publiques : nom, thème, liens ; pas le contenu réservé ni les données d'abonnés).

# 10. Extraction — Firecrawl, Scrapfly & APIs

• API officielle de la plateforme → toujours privilégié (YouTube, Twitch, etc.). Fiable, structuré, conforme.
• Parsing des pages link-in-bio (Firecrawl) → extraire la liste des liens/comptes.
• Firecrawl → pages publiques relativement ouvertes (agences, listes, blogues).
• Scrapfly → plateformes hostiles au scraping (Instagram, TikTok) : anti-bot, rendu JS, rotation d'IP. À minimiser et n'utiliser que faute d'API, dans le respect des CGU (section 15).

Chaque connecteur documente en tête son mode d'accès (API / Firecrawl / Scrapfly) et pourquoi. Réutiliser les clients partagés de Lou·Ka.

# 11. Normalisation

• Nettoyer noms, bios, handles (emoji superflus, doublons, casse).
• Mapper vers le schéma Créateur + Plateformes (section 5).
• Classer niches, type de créateur, langue, taille d'audience.
• Normaliser chaque url de plateforme (forme canonique par plateforme).
• Rattacher une région uniquement si déclarée publiquement (sinon null).
• Renseigner confidence de chaque rattachement de compte (section 12).
• Conserver les source_ids préfixés (ex. linktree:nom, youtube:UCxxxx).

# 12. Résolution d'identité & déduplication — LE cœur du projet

Le vrai défi n'est pas le volume, c'est de rattacher les bons comptes à la bonne personne et de ne pas fusionner deux personnes distinctes.

# 12.1 Rattachement des comptes (identity resolution)

Signaux, du plus fort au plus faible :

1. Page link-in-bio listant explicitement les comptes → rattachement fort.
2. Liens croisés : un profil qui pointe vers un autre (IG → TikTok en bio).
3. Handle identique + même nom d'affichage + même photo sur plusieurs plateformes.
4. Mentions réciproques / mêmes liens externes.

• Chaque rattachement reçoit un score confidence. En dessous d'un seuil, marquer « à vérifier » plutôt que de rattacher à tort.

# 12.2 Déduplication des créateurs

• Clé : ensemble de comptes rattachés + nom d'affichage normalisé.
• Deux fiches qui partagent au moins un compte à confidence élevée → fusion.
• Homonymes : ne jamais fusionner sur le seul nom. Exiger un compte partagé.
• À la fusion : union des platforms, meilleure source par champ, on ne perd aucun lien vérifié.

S'inspirer de la déduplication de Lou·Ka (entités multi-sources), en gardant à l'esprit qu'ici une erreur de fusion mélange deux personnes réelles — donc prudence maximale.

# 13. Fraîcheur & états

• Abonnés / audience changent constamment → rafraîchir et horodater (last_checked par plateforme).
• Comptes disparus / renommés : marquer inactifs, conserver l'historique ; ne pas supprimer brutalement (politique de grâce via last_seen, comme Lou·Ka).
• Créateur inactif (plus de publication) → status: inactive.
• Opt-out : si un créateur demande le retrait → status: opted_out, fiche masquée et non ré-agrégée (voir section 15).

# 14. Cadence de rafraîchissement

• Métriques d'audience des gros créateurs : hebdomadaire.
• Enrichissement standard : mensuel.
• Découverte de nouveaux créateurs : continu / hebdomadaire selon les sources.
• Toujours mettre à jour last_checked et last_seen à chaque passage réussi.

# 15. Vie privée, éthique & conformité — PRIME SUR TOUT

Créa·Ka agrège des personnes. Cette section a priorité absolue sur la complétude et le volume. En cas de doute, on n'inclut pas et on demande.

• Uniquement du public et du professionnel. N'agréger que les profils publics de créateurs qui se présentent publiquement comme créateurs/influenceurs, et que les informations qu'ils rendent publiques (nom de scène, comptes, bio, liens, courriel pro affiché). Jamais d'adresse personnelle, de téléphone privé, de courriel personnel, ni de données déduites/privées.
• Pas de compilation intrusive. Ne pas croiser des sources pour reconstituer des informations qu'une personne n'a pas choisi de rendre publiques.
• Opt-out obligatoire et respecté. Fournir un mécanisme simple de retrait ; une fois opted_out, la fiche est masquée et exclue des ré-agrégations futures (liste de suppression persistante).
• Créateurs mineurs — prudence extrême. Si is_minor est détecté (ou probable), appliquer un régime restreint : pas de données de contact, pas de métriques précises de localisation, et en cas de doute exclure. Ne jamais produire quoi que ce soit qui pourrait faciliter le ciblage ou l'identification d'un mineur.
• CGU & robots.txt de chaque plateforme respectés. Privilégier les API officielles ; minimiser le scraping ; rate-limiting raisonnable ; identification honnête. Les plateformes (Instagram, TikTok) sont restrictives : ne pas industrialiser un accès contraire à leurs conditions — demander en cas de doute.
• Attribution & exactitude. Lien vers la source ; ne republier que le nécessaire à la découverte ; corriger vite toute erreur de rattachement (une fausse association est un préjudice réel pour la personne).
• Loi 25 (protection des renseignements personnels au Québec). Concevoir en tenant compte des obligations applicables aux renseignements personnels ; documenter les finalités, permettre l'accès/rectification/retrait.

# 16. Conventions de code

• Suivre les mêmes conventions que Lou·Ka (langage, dossiers, nommage, linting, formatage). Cohérence > préférences personnelles.
• Un connecteur = un module isolé, testable indépendamment.
• Secrets (clés API des plateformes, Firecrawl/Scrapfly) via variables d'environnement / gestionnaire de secrets. Jamais en clair.
• Logging structuré (source, nb de créateurs, nb de comptes rattachés, confiance moyenne, erreurs, durée).
• Commits atomiques, messages clairs.

# 17. En-tête d'auteur — OBLIGATOIRE dans chaque fichier

Tout fichier du dépôt doit débuter par un en-tête d'auteur. L'auteur est toujours Simon-Pierre Boucher <contact@spboucher.ai>.

Python / Shell / YAML / TOML / Dockerfile :

# ==============================================================================
# Author: Simon-Pierre Boucher <contact@spboucher.ai>
# File:   <nom_du_fichier>
# Desc:   <brève description>
# ==============================================================================

JavaScript / TypeScript / Go / Rust / Java / C :

// ==============================================================================
// Author: Simon-Pierre Boucher <contact@spboucher.ai>
// File:   <nom_du_fichier>
// Desc:   <brève description>
// ==============================================================================

Markdown / HTML / XML :

<!--
  Author: Simon-Pierre Boucher <contact@spboucher.ai>
  File:   <nom_du_fichier>
  Desc:   <brève description>
-->

CSS / SCSS :

/*
  Author: Simon-Pierre Boucher <contact@spboucher.ai>
  File:   <nom_du_fichier>
*/

Règles :

• Aucun fichier commité sans cet en-tête.
• Pour un connecteur, indiquer dans Desc: la source/plateforme couverte, le mode d'accès (API / Firecrawl / Scrapfly / link-in-bio) et s'il fait de la découverte ou de l'enrichissement.
• Vérifier la présence de l'en-tête en revue de code (idéalement hook de pré-commit).

# 18. Tests & qualité

• Chaque connecteur : tests unitaires de normalisation sur fixtures réelles (réponses API, pages link-in-bio, profils publics figés).
• Tests de résolution d'identité : cas connus de comptes multi-plateformes + cas-pièges d'homonymes à ne pas fusionner.
• Validation de schéma : toute fiche émise doit valider le schéma ; rejeter un compte sans url/confidence.
• Contrôle éthique automatisé : vérifier qu'aucune donnée privée n'entre en base et que les fiches opted_out restent exclues.
• Monitoring : alerte si une source cesse de retourner des données (blocage).

# 19. Checklist — ajouter un connecteur / créateur

1. Lire les connecteurs de référence dans le dépôt Lou·Ka (section 3).
2. Vérifier que la source/le créateur n'est pas déjà couvert (index/registre).
3. Découverte ou enrichissement ? Identifier la plateforme/template réutilisable.
4. Choisir le mode d'accès : API officielle > link-in-bio > Firecrawl > Scrapfly (section 10), dans le respect des CGU.
5. Implémenter fetch() → normalize() → emit() (interface commune).
6. Mapper le schéma créateur + plateformes ; renseigner confidence par compte.
7. Brancher la résolution d'identité et la déduplication (section 12).
8. Appliquer les règles de vie privée/éthique (section 15) : public seulement, opt-out respecté, régime mineurs, pas de données privées.
9. Gérer fraîcheur, comptes disparus, inactifs, opt-out (section 13).
10. Ajouter l'en-tête d'auteur (section 17).
11. Écrire les tests + fixtures, dont identité et contrôle éthique (section 18).
12. Enregistrer la source dans le registre avec sa cadence.
13. Valider volume, confiance des rattachements et qualité sur un premier run.

# 20. Roadmap / MVP

MVP : templatiser un connecteur link-in-bio (Linktree/Beacons) pour remplir platforms d'un coup, + les API officielles YouTube et Twitch pour l'enrichissement fiable. Découverte initiale via listes médias, agences et hashtags québécois. Résolution d'identité de base (link-in-bio + liens croisés). UI d'annuaire avec recherche/filtres par niche, région, langue, plateforme, taille d'audience, et page créateur listant tous ses comptes.

Ensuite : Instagram/TikTok (API officielles en priorité), Substack/Patreon, métriques d'audience historisées, score de confiance affiné, opt-out en libre-service, et cross-linking avec les autres sites ·Ka.

Nord stratégique : être l'annuaire public de référence des créateurs québécois — exhaustif, cross-plateforme et respectueux de la vie privée — là où les bases existantes sont payantes, généralistes et anglophones.

Fin de CLAUDE.md — Créa·Ka. Auteur : Simon-Pierre Boucher <contact@spboucher.ai>.