Un event catalogue est le référentiel vivant qui décrit, documente et structure tous les events publiés dans votre écosystème. Il ne s’agit pas d’une liste statique, mais d’un actif opérationnel: il relie les domaines métier, les contracts techniques, les contraintes de conformité et les responsabilités organisationnelles. En banque, où chaque event peut avoir une valeur probatoire, le catalogue est un composant critique pour l’audit, la traçabilité et la résilience.

Ce guide explique pourquoi un event catalogue est indispensable, comment le structurer, et comment l’intégrer dans votre gouvernance afin qu’il reste fiable et utile à long terme.

Qu’est-ce qu’un event catalogue (et ce que ce n’est pas)

Un event catalogue répond à une question simple: qui publie quoi, dans quel contrat, à quelles conditions et pour quel usage. Il associe un event à son propriétaire, sa description métier, son schéma, ses topics, ses règles de compatibilité, ses contraintes de rétention, ses SLO/SLA et ses consommateurs.

Il ne faut pas le confondre avec: - Schema Registry: gère la compatibilité technique des schémas, mais ne capture pas la dimension métier, l’owner, la sensibilité ou le contexte. - Data Catalog: couvre des datasets et des tables; un event catalogue gère des flux et des contrats temps réel. - Documentation ad hoc: un wiki sans gouvernance devient rapidement obsolète.

Le catalogue est donc un pont entre le métier (virement, KYC, fraude) et la technique (topic, schema, partition key), avec une gouvernance claire.

Pourquoi il devient indispensable en banque

Dans un SI bancaire, la multiplication des producteurs et consommateurs crée un risque de couplage implicite. Sans catalogue: - Les équipes consomment des events sans connaître l’owner ni les garanties. - Des schémas évoluent sans contrôle, cassant des projections critiques. - Des données sensibles circulent sans classification. - Les audits deviennent coûteux, car il faut reconstruire la logique du flux.

Un catalogue apporte de la visibilité et de la discipline contractuelle. Il clarifie les responsabilités et évite les dépendances invisibles, ce qui est vital pour des domaines régulés.

Structure minimale d’une fiche d’event

Chaque event doit être décrit avec un niveau de détail suffisant pour être consommé sans ambiguïté. Voici les champs essentiels:

Champ	Rôle	Exemple bancaire
Nom	Identifiant métier	TransferInitiated
Topic	Transport	prod.payments.transfer.evt.initiated.v1
Domain	Contexte métier	payments
Owner	Responsable	Squad Paiements
Schéma	Contrat technique	Avro v1
Compatibilité	Règle d’évolution	BACKWARD
Clé de partition	Ordre	account_id
Rétention	Durée	365 jours
Sensibilité	Classification	PII-Restricted
SLA	Engagement	99.9% / 2s
Consommateurs	Dépendances	Ledger, Fraud, CRM

Cette fiche doit être accessible, versionnée et mise à jour quand le contrat évolue. En banque, l’owner doit être clairement identifiable pour les revues de conformité.

Exemple d’entrée de catalogue

Voici un exemple de fiche structurée, versionnée dans un dépôt Git:

name: TransferInitiated
version: 1
domain: payments
owner: squad-payments
contact: payments-oncall@bank.example
public: true
schema:
  type: avro
  registry_id: 412
  compatibility: BACKWARD
topic:
  name: prod.payments.transfer.evt.initiated.v1
  partitions: 24
  retention_days: 365
  cleanup_policy: delete
partition_key: account_id
slo:
  availability: 99.9
  max_latency_ms: 2000
sensitivity:
  classification: PII-Restricted
  fields: ["from_account", "to_account"]
consumers:
  - ledger-service
  - fraud-service
  - notifications-service
lifecycle:
  status: active
  deprecated_on: null

Ce format permet d’automatiser des contrôles: validation de compatibilité, détection de champs sensibles, vérification de la rétention, et alertes si un consumer critique n’est pas déclaré.

Taxonomie et classification

Un event catalogue utile impose une taxonomie claire. Les dimensions classiques sont: - Public vs private: contrat stable ou interne. - Fact vs delta: état complet ou changement minimal. - Command vs event: intention vs fait. - Criticality: impact métier en cas de perte.

Dans un contexte bancaire, la classification des données doit être alignée avec les exigences réglementaires (PCI-DSS, GDPR, normes locales). Un event qui contient un IBAN ou un identifiant client doit être marqué comme sensible, avec un plan de protection et des restrictions d’accès.

Gouvernance et workflow de publication

Sans processus, le catalogue devient un artefact passif. Un workflow robuste inclut: 1) Design review: validation du contrat, du nommage, de la clé de partition. 2) Validation schema: compatibilité et tests de sérialisation. 3) Classification sécurité: PII, chiffrement, ACL. 4) Publication contrôlée: ajout dans le catalogue, puis création du topic. 5) Onboarding consumers: lecture des SLA et des constraints.

Ce workflow doit être automatisé en CI/CD pour éviter la dérive. Un simple fichier YAML sans validation devient vite obsolète.

Versioning et compatibilité

La compatibilité est le cœur du contrat. En banque, la règle générale est: - BACKWARD pour les events publics (les consumers anciens continuent de fonctionner). - FULL pour les topics critiques (compatibilité stricte dans les deux sens).

L’ajout d’un champ est une évolution additive; la suppression est disruptive et nécessite un changement de version de topic. Le catalogue doit indiquer les champs optionnels, les defaults et la politique de dépréciation. Sans cela, les consumers appliquent des règles implicites et la dette technique augmente.

Cycle de vie des events

Un event a un cycle de vie complet: - Draft: en conception, non consommable. - Active: utilisé en production. - Deprecated: toujours produit, mais appelé à disparaître. - Retired: plus produit, lecture archivistique seulement.

Le catalogue doit afficher ce cycle pour éviter la consommation de flux en fin de vie. En banque, il est fréquent de conserver un event en lecture seule pour l’audit même après sa dépréciation.

Observabilité, SLA et qualité des données

Un event catalogue moderne inclut des SLO/SLA: délai maximal d’émission, fréquence attendue, et taux d’erreur toléré. Ces informations sont cruciales pour les consumers. Par exemple, un service de fraude ne doit pas dépendre d’un event sans SLA clair.

La qualité de données est un autre axe: documentez les règles d’intégrité, indiquez si certains champs sont obligatoires, et surveillez la dérive (nulls, formats invalides). Les métriques doivent être accessibles depuis le catalogue pour que les équipes mesurent la fiabilité du flux.

Sécurité et conformité

Le catalogue est un outil de contrôle. Il doit indiquer: - Les champs sensibles. - Les règles de masquage (ex: IBAN partiellement masqué). - Les exigences de chiffrement. - Les ACL autorisées.

Un event catalogue aide aussi à documenter les transferts cross-border. Dans une banque internationale, certains events ne doivent pas sortir d’une région pour respecter les contraintes locales. Le catalogue doit donc mentionner la zone de stockage et la politique de réplication.

Bonnes pratiques de base

• prod.payments.transfer.evt.initiated.v1
• prod.payments.transfer.evt.settled.v1
• prod.payments.transfer.cmd.initiate.v1
• prod.corebanking.account.evt.opened.v1
• prod.payments.transfer.dlq.v1

Ces noms mettent en évidence l’environnement, le domaine, le type (evt/cmd), l’action et la version. Le catalogue doit refléter exactement ces conventions pour éviter les divergences entre documentation et réalité.

Intégration avec le Schema Registry

Le catalogue doit pointer vers le Schema Registry, mais il ajoute la couche métier. Une bonne pratique consiste à stocker l’identifiant du schéma, la compatibilité et le lien vers la définition. Ainsi, un consumer peut retrouver le contrat technique et la raison métier du flux sans passer par plusieurs outils.

Catalogue et architecture bancaire

Prenons un flux de virement international: - TransferInitiated (paiements) déclenche AML. - TransferRiskApproved (fraude) permet la réservation FX. - LedgerEntryPosted (ledger) acte la comptabilisation.

Chaque event appartient à un domaine distinct, mais le catalogue les relie par correlation et explique la logique globale. Cette vision est essentielle pour les équipes de conformité et d’audit, qui doivent reconstruire un parcours client sans inspecter le code source.

Mise en œuvre pratique

Le catalogue peut être implémenté de plusieurs façons: - Repository Git: YAML/JSON versionnés, validation en CI. - Portail interne: UI de recherche et de découverte. - API catalogue: utilisée par les pipelines pour contrôler la création de topics.

L’essentiel est d’avoir un single source of truth. En banque, le Git offre l’avantage de la traçabilité: chaque changement de contrat est un commit signé, ce qui facilite les audits.

Catalogue, lineage et analyse d’impact

Un catalogue moderne doit exposer la dépendance amont/aval. Connaître les consommateurs d’un event est indispensable pour évaluer l’impact d’un changement de schéma ou d’une modification de rétention. En banque, un simple champ ajouté sur TransferInitiated peut affecter des projections de risque, des calculs prudentiels ou des rapports réglementaires.

Le lineage fournit une vue graphe: producteurs, topics, consumers, pipelines de transformation et data stores finaux. Cette vue accélère l’analyse d’incident et la gestion de crise. Si un consumer critique accuse du retard, le catalogue permet d’identifier les services en amont qui génèrent la charge ou les services en aval qui dépendent du flux.

Pour être utile, le lineage doit être maintenu automatiquement (logs Kafka, observabilité, métadonnées de déploiement). Un lineage manuel vieillit vite et perd sa valeur. En contexte bancaire, cette capacité est souvent exigée en audit: il faut savoir quels systèmes alimentent un rapport financier et quelles données ont été utilisées pour une décision de risque.

Onboarding des consumers

Consommer un event n’est pas un acte trivial. Le catalogue doit guider les équipes avec un parcours clair: - Vérifier que le domaine et le SLA sont compatibles avec le besoin. - Lire la section “sensibilité” et appliquer les règles de sécurité. - Valider la clé de partition pour comprendre l’ordre garanti. - Implémenter l’idempotence et les retries avant de consommer en production.

En banque, il est recommandé de fournir des events exemples (payloads réalistes) et un environnement de test avec un topic sandbox. Cela permet aux consumers de valider leur logique sans risque de perturber des flux critiques. Le catalogue peut aussi référencer des tests contractuels, des SDK internes ou un guide de projection pour accélérer l’intégration.

Automatisation et quality gates

Un catalogue fiable doit être auto-validé. Mettez en place des quality gates dans la CI: - Vérification du nommage (pattern, environnement, version). - Validation de compatibilité (Schema Registry). - Détection de champs sensibles non déclarés. - Alignement entre la configuration du topic et le contrat documenté.

En pratique, un modèle GitOps fonctionne bien: la création d’un topic passe par une pull request, validée par des contrôles automatiques et une revue architecture. En banque, cette discipline réduit les risques d’erreurs opérationnelles et renforce la traçabilité des décisions.

Anti-patterns à éviter

• Catalogue décoratif: rempli une fois, jamais mis à jour.
• Absence d’owner: personne n’est responsable du contrat.
• Données sensibles non classifiées: risque réglementaire immédiat.
• Schémas versionnés sans dépréciation: accumulation de flux obsolètes.
• Docs déconnectées: topic réel différent du topic documenté.

Ces anti-patterns conduisent à la perte de confiance. Un catalogue qui n’est pas fiable devient un risque plus qu’un outil.

Conclusion

Un event catalogue n’est pas un luxe, c’est une infrastructure de gouvernance. Il rend l’écosystème observable, contractualisé et auditable. En banque, où la traçabilité est un impératif légal, il devient un élément central du design end-to-end. Traitez-le comme un produit: versionnez-le, automatisez-le, et donnez-lui des owners. C’est à ce prix que l’event-driven peut être durable.