Vue d'ensemble du plan de données

Le plan de données regroupe sept services à contexte borné et un projector, tous sous app/. Chaque service possède son propre schéma MySQL sur HeatWave (ADR 0005). Les services users, commands et modules annoncent chaque changement validé comme un événement sur NATS (ADR 0003), puis le projector agrège ces événements dans la projection des réglages Valkey lue par le hot path.

Cette page présente la vue des composants. Le reste de la section approfondit :

• Conception de la base : modèle conceptuel, schémas physiques et règles d’intégrité.
• Cache et write-behind : chemins de lecture et d’écriture, avec leurs diagrammes UML de séquence et d’état.
• Conception des classes : diagrammes UML de classes et patterns utilisés.
• Projection des réglages : organisation Valkey et protocole de reconstruction.

Diagramme des composants

flowchart LR
    subgraph services["Data services (app/)"]
        users["users"]
        commands["commands"]
        modules["modules"]
        transactions["transactions"]
        others["loyalty, notifications,<br/>discord-data"]
    end

    subgraph record["State of record"]
        mysql[("MySQL HeatWave<br/>one schema per service")]
    end

    nats(["NATS JetStream"])
    projector["projector"]
    valkey[("Valkey<br/>settings projection")]
    hot["Hot path readers<br/>(ingress workers)"]

    users --> mysql
    commands --> mysql
    modules --> mysql
    transactions --> mysql
    others --> mysql

    users -- "change events" --> nats
    commands -- "change events" --> nats
    modules -- "change events" --> nats

    nats -- "invalidation (broadcast)" --> services
    nats -- "durable group" --> projector
    projector --> valkey
    hot --> valkey

Propriété

Les références entre services sont de simples colonnes indexées contenant l’identifiant utilisateur Twitch. Par construction, aucune clé étrangère ne traverse les schémas.

Contrats d’événements

Les sujets et DTO de contenu résident dans internal/domain/event/data et constituent un contrat public : renommer un sujet ou réduire son contenu est un changement incompatible. Les événements de changement transportent le nouvel état complet (transfert d’état par événement), de sorte que les consommateurs ne lisent jamais le schéma d’un autre service et que la relivraison est sans danger.

Tous les sujets data.> sont capturés par le flux JetStream BAGEL_DATA (rétention de 5 minutes, stockage sur fichier, trois réplicas, pkg/bus/streams.go).

Deux formes d’abonnement sont utilisées délibérément :

• Broadcast (sans groupe de file) : invalidation du cache. Chaque instance d’un service supprime ses clés mises en cache lorsqu’une instance écrit.
• Groupe de file durable : le projector et les répondants de reproject. Un seul consommateur par groupe traite chaque événement, et le groupe conserve sa position après un redémarrage.

Les consommateurs valident chaque contenu et abandonnent (journalisation et acquittement) ce qui ne peut pas être décodé ou validé. Un acquittement négatif sur un message invalide entraînerait sa relivraison indéfinie.

Configuration

Chaque service lit sa configuration dans l’environnement. Variables communes :

Sans clé de licence, la supervision ne fait rien : le développement local n’a donc besoin d’aucune variable NEW_RELIC_*.