HealthPack

C'est le diagramme que j'ouvrirais en premier. Les clients ne parlent jamais qu'à edge-gateway, qui valide chaque JWT auprès de Keycloak avant de transmettre une requête — les appels REST vont directement à un service métier, GraphQL passe par le BFF, et une montée en WebSocket va vers chat-service. Rien en aval ne revérifie l'authentification ; la passerelle est le seul endroit qui le fait, et tout le reste fait confiance aux revendications qu'elle transmet.

Les flèches doubles épaisses représentent gRPC, et elles se regroupent autour de terminology-service pour une raison précise : ce service est sollicité à presque chaque écriture clinique (valider un code ICD-10, vérifier une interaction médicamenteuse, résoudre un code LOINC), c'est donc le seul endroit où un protocole lent se ferait sentir partout. Les flèches pointillées représentent Kafka et RabbitMQ, et le diagramme est en réalité un argument pour les garder séparés : Kafka diffuse un même événement vers cinq consommateurs différents (lab.result.finalized à lui seul alimente le clinique, la facturation, l'assistant IA et les abonnements GraphQL), tandis que RabbitMQ porte des commandes vers exactement un exécutant — un PDF à générer, une notification à envoyer.

Lu de haut en bas, les couches racontent leur propre histoire : une bordure qui ne fait que valider et router, une couche de composition qui n'existe que pour épargner des allers-retours au frontend, sept services métier qui possèdent chacun une seule base PostgreSQL et rien d'autre, un service gRPC interne unique derrière tous les autres, et trois exécutants asynchrones qu'aucun client n'appelle jamais directement.

Tout dans HealthPack finit par pointer vers un Patient, c'est donc le modèle que j'ai conçu en premier. La relation qui mérite qu'on s'y arrête est Appointment "1" --> "0..1" Encounter : produces — un rendez-vous est une réservation, une consultation est la visite réelle, et ce sont délibérément deux enregistrements distincts. Un patient peut réserver un rendez-vous et ne jamais se présenter ; une admission sans rendez-vous peut produire une consultation sans réservation derrière elle. Fusionner les deux rendrait les absences et les admissions impossibles à représenter proprement.

Consent est directement rattaché à Patient plutôt qu'enfoui dans une table de paramètres, parce que l'assistant IA le vérifie sur le chemin critique de chaque question qu'il traite — isActiveFor(ConsentScope) est appelé avant qu'un seul document ne soit récupéré, pas après. Observation et Condition appartiennent toutes deux à Encounter par composition (le losange plein), ce qui signifie qu'elles ne peuvent pas survivre à la visite où elles ont été enregistrées — une mesure a toujours un horodatage et un contexte clinique, jamais isolée.

Les trois flèches pointillées qui convergent vers DocumentJob sont l'objet de ce diagramme : une LabOrder, une Prescription et une Invoice sont des concepts cliniques ou financiers totalement distincts, mais tous terminent leur cycle de la même façon — en déclenchant un PDF. Modéliser explicitement cette convergence a permis d'écrire document-service une seule fois, de façon générique, plutôt que trois fois avec trois pipelines PDF subtilement différents.

DocumentJob porte une idempotencyKey pour une raison concrète : un consommateur RabbitMQ peut recevoir le même message deux fois (c'est le compromis que fait RabbitMQ — livraison au moins une fois, jamais au plus une fois), et la prescription d'un médecin ne doit jamais être générée, signée et stockée deux fois à cause d'un appel réseau relancé. Le compteur attempts du job et sa méthode markFailed(String) existent pour qu'une génération bloquée devienne une donnée visible, pas un silence.

RagQuery conserve plus que la réponse — elle garde inputTokens et cacheReadTokens aux côtés de la List~Citation~, parce qu'une réponse RAG sans source n'est pas un fait qu'on montre à un clinicien, et un nombre de tokens sans indicateur de lecture de cache ne dit rien de l'efficacité réelle du cache de prompt en production. Chaque Citation porte une plage de pages, pas seulement un identifiant de document, pour que l'assistant puisse désigner le paragraphe exact qu'il cite.

AuditRecord est la seule classe de ce diagramme qui se référence elle-même : AuditRecord --> AuditRecord : prevHash chain. Le hash de chaque enregistrement est calculé sur ses propres champs plus le hash de l'enregistrement précédent, si bien que modifier une entrée passée — même un seul champ — casse tous les hashs suivants. verifyChain(AuditRecord prev) est la méthode qu'un auditeur appelle réellement, et elle confirme la chaîne ou indique précisément où elle s'est rompue.

C'est moins un diagramme de classes qu'une carte de qui appelle qui de façon synchrone. Les trois flèches de dépendance ..> vers TerminologyService depuis ClinicalService, PharmacyService et le code lié à SchedulingService confirment la décision d'architecture suggérée par le diagramme global : les recherches terminologiques sont le seul appel synchrone véritablement transversal, ce qui explique précisément pourquoi ce service est exclusivement en gRPC plutôt qu'en REST.

BffGraphQlResolvers mérite une lecture attentive : batchLoadPatients(Set~UUID~) : CompletableFuture~Map~ est la fonction de lot du DataLoader, et sa signature explique à elle seule pourquoi la couche GraphQL évite les requêtes N+1 — les résolveurs demandent un patient à la fois, DataLoader regroupe les identifiants dans un seul cycle de la boucle d'événements, et cette unique méthode les récupère tous en un seul appel gRPC. onVitalsUpdated et onLabResultReady renvoient un Flux, pas une valeur — ce sont des abonnements GraphQL, alimentés par des consommateurs Kafka en dessous, pas par du sondage.

Remarquez ce qui manque à chaque méthode ici : aucun createX ni getX n'est exposé à un client. DocumentService.onRenderCommand, NotificationService.onNotifyCommand et onCriticalValue, AiRagService.onDocumentTextExtracted — chaque point d'entrée commence par on, parce que chaque point d'entrée est un gestionnaire de message, pas un endpoint. Un client interroge le statut d'un job via une petite façade REST, mais ne peut jamais demander directement à ces services de faire quoi que ce soit ; il ne peut que le demander à une file.

ChatService ..> AiRagService : gRPC server-stream est le seul appel d'allure synchrone dans un diagramme par ailleurs asynchrone, et il est là parce qu'une réponse de chat doit paraître instantanée — la faire transiter par Kafka ajouterait un saut de file que l'utilisateur remarquerait en attendant l'apparition des tokens. AiRagService.evaluateGoldenSet() est une méthode sans appelant visible ici, délibérément : elle est invoquée par la CI, pas par le système en fonctionnement, pour noter la qualité des réponses face à un jeu fixe de questions-réponses avant qu'un changement ne parte en production.

Cette séquence justifie à elle seule l'association GraphQL/gRPC. Un praticien ouvre un tableau de bord qui nécessite démographie, consultations et résultats de laboratoire — trois services, potentiellement des dizaines de patients affichés en même temps. L'étape 10, « DataLoader regroupe tous les identifiants en un seul cycle de la boucle d'événements », est le moment décisif : plutôt que le schéma naïf N+1 (un appel par patient et par champ), chaque demande d'identifiant d'un résolveur est mise en file pour un seul cycle, puis vidée en un seul lot.

Le bloc par qui suit déclenche trois appels groupés en parallèle — gRPC batchGet vers patient-service, gRPC batchGetEncounters vers clinical-service, et un appel REST vers lab-service — et patient-service applique lui-même la même rigueur en interne : un MGET sur Redis d'abord, une requête PostgreSQL seulement pour ce qui n'était pas en cache. La note en bas de séquence énonce le gain sans détour : un appel gRPC par service, pas un par ligne de patient, quel que soit le nombre de patients affichés.

Deux modes de défaillance sont éliminés par conception, pas rattrapés après coup. Le SET slot-hold NX EX 120 sur Redis empêche deux personnes de se disputer le même créneau dans les secondes que prend le remplissage d'un formulaire, et l'INSERT PostgreSQL en dessous est protégé par une contrainte d'exclusion en base sur (practitioner_id, time_range) — même si deux requêtes franchissent toutes deux la vérification Redis, la base de données refuse elle-même la seconde écriture. La correction de la concurrence se trouve au seul endroit qui puisse réellement la garantir : la base de données, pas du code applicatif qui espère avoir vérifié à temps.

La seconde moitié met en œuvre le patron outbox : l'insertion du rendez-vous et celle de l'outbox se font dans la même transaction de base de données, si bien que « la réservation a réussi mais personne ne l'a su » n'est pas un état atteignable — un sondeur fonctionnant indépendamment de la requête récupère la ligne d'outbox et publie appointment.booked dès qu'il est prêt. Le rappel emprunte ensuite délibérément la voie lente : le mécanisme TTL plus échange de lettres mortes de RabbitMQ met en œuvre le délai de 24 heures, et si le fournisseur de push échoue, le message est renvoyé avec remise en file et un recul exponentiel avant d'atterrir dans une file de lettres mortes plutôt que de disparaître.

C'est le flux qui résume vraiment tout le projet — c'est celui décrit dans la première phrase de présentation. Un automate de laboratoire parle HL7 v2, un format de 1989 que lab-service analyse avec HAPI HL7v2 et valide contre LOINC avant de persister quoi que ce soit. La décision intéressante intervient juste après : plutôt que de laisser lab-service lui-même juger de ce qui est critique, il publie le fait — lab.result.finalized — et une topologie Kafka Streams séparée, partitionnée par identifiant patient avec une déduplication par fenêtre glissante de 15 minutes, se charge du jugement. La détection est délibérément découplée de l'enregistrement, pour que la logique d'alerte puisse évoluer sans toucher au service propriétaire des données.

Quand une valeur bascule dans le critique, une seule publication sur lab.critical-value se diffuse vers trois consommateurs en parallèle : notification-service la route vers une file prioritaire qui contourne entièrement les heures de silence, chat-service pousse une trame STOMP directement vers toute session ouverte du médecin, et l'abonnement GraphQL met à jour son tableau de bord en direct. Trois canaux de livraison différents, un seul événement, pour que, quelle que soit la façon dont le médecin regarde le système à cet instant, il le voie.

La vérification d'idempotence tout en haut est la première chose qui se produit, avant tout traitement réel : document-service recherche l'idempotencyKey reçue dans PostgreSQL et, si elle a déjà été traitée, acquitte le message sans rien faire d'autre. Cette seule vérification est ce qui permet à RabbitMQ de redistribuer la même commande de génération sans jamais produire deux PDF signés pour la même prescription.

Passé cette garde, le pipeline est en réalité deux pipelines mis bout à bout. Le premier génère, applique un profil d'archivage PDF/A, signe avec l'implémentation PAdES de BouncyCastle, et stocke l'objet dans MinIO sous son sha256. Le second ne démarre qu'une fois le premier pleinement validé : PDFBox extrait le texte du PDF qui vient d'être écrit, publie document.text-extracted, et c'est cet unique événement qui rend le document consultable par l'assistant de chat — découpé, vectorisé via Voyage AI, et inséré dans pgvector avec l'identifiant du patient en métadonnée, ce qui permet plus tard à une requête RAG de se limiter aux documents d'un seul patient et d'aucun autre.

L'ordre des opérations ici concrétise tout l'argument de confidentialité : ai-service appelle hasConsent(patientId, AI_ASSIST) auprès d'identity-service avant de vectoriser la question, avant d'interroger pgvector, avant de lire le moindre mot du dossier du patient. Un consentement révoqué renvoie PERMISSION_DENIED à ce stade et la conversation s'arrête là — l'assistant n'avance jamais assez loin pour avoir quoi que ce soit à expurger.

Une fois le consentement validé, la récupération se limite à ce seul patient (topK 8, filtré par patientId) et le contexte récupéré est expurgé des données de santé identifiantes avant d'être intégré au prompt — le modèle ne voit jamais plus de détails identifiants que la réponse n'en exige. La note cache_control sur l'étape de construction du prompt compte autant pour le coût que pour la latence : le prompt système et le corpus de directives restent stables à travers toutes les questions posées par l'équipe soignante de ce patient, si bien que le cache de prompt d'Anthropic transforme la majeure partie de ce contexte en lecture de cache plutôt qu'en nouvelle facturation, et cacheReadTokens est journalisé précisément pour vérifier que c'est réellement le cas plutôt que de le supposer. À partir de là, la boucle est un relais direct — Claude diffuse des événements content_block_delta, ai-service en transmet chacun via un flux serveur gRPC, chat-service le transforme en trame STOMP, et le navigateur l'affiche progressivement, si bien qu'une réponse apparaît comme une personne qui tape plutôt que d'arriver d'un bloc après une attente.

La cascade de cache Caffeine puis Redis existe parce que validateCode est appelée à presque chaque écriture clinique dans tout le système, et une recherche terminologique qui atteindrait PostgreSQL à chaque fois ralentirait chacune de ces écritures sans raison — les référentiels de codes changent à peine, un cache L1 local au processus adossé à un cache L2 partagé est donc la solution évidente, et chaque défaut de cache alimente les deux niveaux au passage, si bien que la prochaine requête, n'importe où dans le cluster, en profite.

La vérification d'interaction elle-même est ce qui justifie ce diagramme : un résultat contre-indiqué ne fait pas échouer la requête, il renvoie un 422 avec le conflit précis, et le praticien peut passer outre — mais seulement en fournissant une justification qui est enregistrée avec la prescription et un indicateur explicite de dérogation. Rien n'est bloqué en silence et rien n'est autorisé en silence ; chaque prescription contestée laisse une trace de qui a dérogé, à quoi, et pourquoi. Les deux dernières publications en bas de séquence — prescription.issued vers Kafka, une commande de génération vers RabbitMQ — sont exactement le point où reprend le diagramme 4d.