Architecture événementielle — aperçu général

Ce dépôt contient la documentation et la gouvernance des schémas pour une architecture événementielle générique. Le document présente, de façon synthétique, le principe, les composants courants et le flux général d'ingestion / traitement / stockage.

Principe rapide

Architecture serverless et événementielle : les producteurs publient des événements sur un bus (par ex. Event Grid / Event Hub). Les consommateurs (Functions, Logic Apps, jobs) consomment ces événements pour valider, enrichir, persister et générer des événements dérivés. Les workflows complexes sont orchestrés et les erreurs non traitables vont en dead‑letter pour investigation et reprise.

Dépôt de schémas (Schema Repository)

Le dépôt centralise des JSON Schema versionnés qui définissent les contrats entre producteurs et consommateurs. Ces schémas sont stockés dans Git pour la gouvernance et publiés sous forme de snapshots immuables dans un conteneur Blob Storage (ex. https://<account>.blob.core.windows.net/schemas).

• Stockage : un conteneur Blob schemas contient les fichiers JSON versionnés.
• Convention de nommage recommandée : <context>-<entity>-vMAJOR.MINOR.PATCH.json où :
  • context : domaine métier, service ou module (ex. user, order, payment)
  • entity : type d'objet ou événement (ex. created, updated, validated)
  • Exemples : user-created-v1.0.0.json, payment-processed-v2.1.0.json, inventory-stockupdated-v1.5.2.json
• Versionnement des schémas : les schémas sont versionnés dans Git et des copies immuables (snapshots) sont publiées dans Blob Storage pour garder un historique consultable.

Automatisation des snapshots

À chaque merge sur la branche principale, la pipeline CI publie automatiquement un snapshot horodaté du schéma dans Blob Storage. Une Azure Function peut aussi être déployée pour créer des snapshots à la demande via API. Ces snapshots garantissent audit, traçabilité et rollback.

Déclencheurs automatiques :

• Merge sur branche principale → snapshot immédiat
• Tag de release → snapshot avec métadonnées de release

Format des snapshots :

• Schéma source : <context>-<entity>-v<version>.json (ex. user-created-v1.0.0.json)
• Snapshot horodaté : snapshots/<context>-<entity>-v<version>-<timestamp>.json (ex. snapshots/user-created-v1.0.0-20250911T103000Z.json)
• Métadonnées : version, checksum, date de publication stockées dans l'index
• Immutabilité : les snapshots horodatés ne peuvent jamais être modifiés après publication

Organisation Blob Storage :

• schemas/ → schémas actuels (écrasés à chaque mise à jour)

• snapshots/ → copies horodatées immutables (audit et rollback)

• Distribution des schémas :

  • Option recommandée : Azure Function + APIM → contrôle d'accès fin, transformation, versioning, avec throttling/caching APIM
  • Option simple : accès direct Blob via SAS → moins flexible mais plus direct pour cas basiques

Azure Function App - Gestion des schémas

La Function App centralise la gestion des schémas avec plusieurs fonctions spécialisées :

Fonction Schema Registry (HTTP Trigger)

Détermine quel schéma retourner selon plusieurs stratégies :

• Par nom et version : /api/schemas/{name}/{version} (ex. /api/schemas/user-created/1.0.0)
• Version latest : /api/schemas/{name}/latest → retourne automatiquement la version la plus récente
• Par contexte : /api/schemas?context={context} → liste tous les schémas d'un contexte métier
• Découverte globale : /api/schemas → retourne l'index complet avec métadonnées

Mécanisme de résolution :

1. La fonction lit l'index JSON depuis Blob Storage (mise en cache) - voir structure détaillée dans "Index de découverte"
2. Parse les paramètres de la requête (nom, version, contexte)
3. Résout l'URL du blob correspondant via l'index
4. Retourne le schéma avec headers de cache appropriés
5. Gère les erreurs avec codes HTTP spécifiques :
   • 200 - Schéma trouvé et retourné avec succès
   • 304 - Not Modified (si ETag/If-None-Match correspond)
   • 400 - Bad Request (paramètres invalides, format version incorrect)
   • 404 - Not Found (schéma inexistant, version introuvable)
   • 500 - Internal Server Error (Blob Storage inaccessible, erreur cache)
   • 503 - Service Unavailable (maintenance, surcharge temporaire)

Fonctions de Validation (Event Grid Trigger)

Traitent les événements entrants depuis Event Grid :

• Écoute par type/contexte : chaque fonction écoute des événements spécifiques (ex. user.*, payment.*)
• Validation automatique : récupère le schéma approprié via la fonction registry interne
• Application des règles : valide le payload selon le schéma résolu et les règles métier
• Routage intelligent : dirige vers les pipelines suivants ou dead-letter en cas d'échec de validation
• Enrichissement : peut ajouter des métadonnées de validation (timestamp, version schéma utilisée)

Optimisations partagées :

• Cache des schémas fréquemment utilisés au niveau de la Function App

Gouvernance des schémas

Règles opérationnelles

• Garder les schémas immuables une fois publiés (nouvelle version pour les changements).
• Snapshots automatiques à chaque release/merge (voir "Automatisation des snapshots").
• Breaking changes : suppression/renommage de champ obligatoire, changement de type d'un champ existant, modification de contraintes (enum, format). Les changements additifs (nouveaux champs optionnels) ne sont pas breaking.
• Documenter les breaking-changes dans le changelog et la PR.

Index de découverte

Conserver un index (fichier JSON) listant les versions disponibles pour faciliter la découverte côté consommateurs :

{
  "schemas": [
    {
      "name": "user-created",
      "version": "1.0.0",
      "url": "https://account.blob.core.windows.net/schemas/user-created-v1.0.0.json",
      "snapshotUrl": "https://account.blob.core.windows.net/snapshots/user-created-v1.0.0-20250911T103000Z.json",
      "checksum": "sha256:abc123...",
      "publishedAt": "2025-09-11T10:30:00Z"
    },
    {
      "name": "payment-processed",
      "version": "2.1.0",
      "url": "https://account.blob.core.windows.net/schemas/payment-processed-v2.1.0.json",
      "snapshotUrl": "https://account.blob.core.windows.net/snapshots/payment-processed-v2.1.0-20250911T103500Z.json",
      "checksum": "sha256:def456...",
      "publishedAt": "2025-09-11T10:35:00Z"
    }
  ]
}

Rôles et responsabilités

• Schema Owner : responsable de la définition, évolution et maintenance d'un domaine de schémas. Valide les changements et s'assure de la cohérence métier.
• Schema Reviewers : équipe technique qui révise la syntaxe, performance et impact des modifications. Au moins 2 reviewers requis pour les changements MAJOR.
• Schema Consumers : équipes qui utilisent les schémas. Doivent être notifiées des changements breaking et participer aux tests d'intégration.
• Schema Committee : comité de gouvernance pour les décisions transversales, résolution de conflits et définition des standards.

Processus d'approbation

• Changements PATCH : approbation automatique après validation CI + 1 reviewer.
• Changements MINOR : approbation Schema Owner + 1 reviewer technique + notification aux consumers.
• Changements MAJOR : approbation Schema Committee + 2 reviewers + validation explicite des équipes impactées + période de préavis (minimum 2 semaines).

Critères de validation

• Conformité aux standards JSON Schema .
• Respect des conventions de nommage et structure.
• Documentation complète (description, exemples, use cases).
• Tests de validation fournis (cas positifs et négatifs).
• Analyse d'impact sur les consumers existants.

Tests et validation

Stratégie de tests par type de changement

• PATCH (bugfix) : validation syntaxique + tests de régression sur exemples existants.
• MINOR (ajout) : validation syntaxique + tests de compatibilité backward + validation que les nouveaux champs n'impactent pas les consumers existants.
• MAJOR (breaking) : validation syntaxique + tests de compatibilité + tests d'intégration avec les équipes consumers + validation des migrations.

Matrice de compatibilité

• Backward compatible : les messages conformes à la version N-1 restent valides en version N.
• Forward compatible : les consumers version N-1 peuvent traiter les messages version N (en ignorant les nouveaux champs).
• Breaking change : nécessite une mise à jour coordonnée des producers et consumers.

Processus de validation avec les équipes

• Notification préventive : avertir les équipes consumers 2 semaines avant un changement MAJOR (6 mois pour une dépréciation complète).
• Période de test : mise à disposition d'un environnement de test avec la nouvelle version pendant 1 semaine minimum.
• Validation explicite : accord écrit des équipes impactées avant publication du changement breaking.
• Rollback plan : procédure documentée pour revenir à la version précédente en cas de problème.

Critères d'acceptance pour les PR

• Validation syntaxique réussie (jsonschema).
• Tests unitaires fournis et passants.
• Documentation mise à jour (README, changelog).
• Review technique approuvée par les reviewers désignés.
• Pour les changements MAJOR : validation des équipes impactées documentée.

Monitoring et observabilité

Métriques à surveiller

• Usage des schémas : nombre de validations par schéma/version, identification des schémas non utilisés.
• Erreurs de validation : taux d'échec par schéma, types d'erreurs fréquentes, messages non conformes.
• Performance : temps de validation, latence d'accès aux schémas, utilisation du cache.
• Adoption : vitesse de migration vers nouvelles versions, taux d'adoption des changements.
• Gouvernance : nombre de PR en attente, délai moyen de review, respect des SLA.

Alerting et notifications

• Schémas obsolètes : alerte si aucune utilisation détectée depuis 3 mois.
• Pic d'erreurs : notification si le taux d'échec dépasse 5% sur 1 heure.
• Performance dégradée : alerte si la latence d'accès aux schémas dépasse 500ms.
• Gouvernance : rappel automatique pour les PR en attente de review depuis > 5 jours.

Tableau de bord de santé

• Vue d'ensemble : nombre total de schémas, versions actives, taux de validation global.
• Par domaine : usage, erreurs et performance par domaine métier.
• Tendances : évolution des métriques sur 30 jours, détection d'anomalies.
• SLA : respect des délais de traitement des PR, disponibilité du service de validation.

Mise à jour des schémas

Processus de mise à jour des schémas :

1. Édition : les schémas sont modifiés dans le dépôt Git (dossier schemas/) via une branche dédiée.
2. Pull Request : ouvrir une PR décrivant le changement, le cas d'usage et l'impact sur la compatibilité.
3. CI / Validation : la pipeline CI exécute :
   • validation syntaxique (jsonschema / ajv),
   • exécution des tests d'exemples (producteurs / consommateurs).
4. Publication : une fois la PR acceptée et mergée, la CI publie automatiquement :
   • le schéma mis à jour dans le conteneur schemas/ (écrase la version précédente),
   • un snapshot horodaté immutable dans snapshots/ (voir "Automatisation des snapshots"),
   • un tag/release Git si nécessaire,
   • la mise à jour de l'index/version catalog et l'exposition via APIM (optionnel).
5. Versioning : appliquer Semantic Versioning (MAJOR.MINOR.PATCH). Un changement breaking doit incrémenter MAJOR.
6. Rollback / Audit : les snapshots publiés dans Blob Storage servent de point d'audit et permettent de revenir à une version antérieure si besoin.

Bonnes pratiques : inclure un changelog court dans la PR, tester producteurs et consommateurs contre le nouveau schéma dans un environnement d'intégration, et demander une revue inter‑équipes pour les changements majeurs.

Dépréciation des schémas

Politique de rétention

• Durée de vie minimale : 2 ans après la dernière utilisation détectée d'un schéma en production.
• Versions multiples : maximum 5 versions MAJOR actives simultanément par schéma.
• Nettoyage automatique : suppression des snapshots non utilisés depuis 3 ans (après validation manuelle).

Processus de dépréciation (End-of-Life)

1. Identification : détection automatique des schémas candidats à la dépréciation (usage < 1% sur 6 mois).
2. Notification préventive : communication aux équipes consumers 6 mois avant l'EOL.
3. Période de grâce : 3 mois supplémentaires pour migration avec support dédié.
4. Dépréciation effective : marquage du schéma comme deprecated, arrêt des mises à jour.
5. Suppression finale : retrait après validation que plus aucun consumer n'utilise le schéma.

Migration forcée

• Versions critiques : migration obligatoire sous 3 mois en cas de faille de sécurité.
• Support migration : outils automatisés de conversion entre versions adjacentes (jsonschema-migrate, scripts de transformation).
• Escalade : processus d'escalade vers le Schema Committee en cas de blocage technique.

Pipeline de traitement (général)

Un pipeline de traitement est une séquence orchestrée ou composée de handlers qui consomment des événements, valident les messages, effectuent des transformations/enrichissements, persistent des données et publient des événements dérivés. Les pipelines peuvent être implémentés comme des fonctions serverless individuelles, des orchestrateurs (Durable Functions) ou des jobs batch selon les besoins.

Principales responsabilités d'un pipeline :

• Validation : vérifier la conformité du message grâce à des JSON Schema et appliquer les règles métier.
• Gestion des erreurs : isoler et stocker les messages en échec dans un dead‑letter (Table/Blob/Queue) avec métadonnées d'erreur.
• Persistance : créer ou mettre à jour les entités en base (upsert idempotent) pour l'accès opérationnel.
• Historisation : enregistrer des snapshots pour audit et comparaisons (Data Lake / Blob Storage).
• Publication : émettre des événements dérivés pour alimenter d'autres consommateurs.
• Orchestration : gérer retries, temporisations et compensations pour scénarios long‑running.

Validation et schémas

• Les validations doivent s'appuyer sur des JSON Schema stockés de manière centralisée (par ex. Blob Storage).
• Conventions : nommage cohérent des schémas et possibilité d'utiliser oneOf pour combiner variantes.
• Les messages non conformes sont routés en dead‑letter avec le détail d'erreur pour correction.

Robustesse opérationnelle

• Idempotence : prévoir une clé d'idempotence pour éviter les doubles traitements.
• Retries & backoff : implémenter des stratégies de retry et circuit breaker pour appels externes.
• Dead‑letter : stocker les métadonnées minimales (publisher, timestamp, uniqueId, error code/message, payload) pour reprise.

Observabilité et tests

• Traces et métriques : instrumenter les étapes clés (durée, erreurs, volumes) et exposer des métriques opérationnelles.
• Tests : voir section "Tests et validation" pour la méthodologie complète de validation des schémas et pipelines.

Sécurité et déploiement

• Accès sécurisé aux schémas et aux stores via Managed Identities ; secrets dans Key Vault.
• Déploiement via CI/CD : valider les schémas, exécuter les tests et déployer le code et l'infra de façon automatisée.

Contrat minimal (entrées / sorties)

• Entrée : message JSON contenant au minimum id, type, source, data et time.
• Sortie : 0..N événements dérivés publiés, upsert en base opérationnelle, ou enregistrement en dead‑letter en cas d'erreur.