Aller au contenu
Blogue Krizaka

33

Nos choix de conception, pour les architectes : chacun avec sa doc officielle

15 nov. 202610 min de lecture

Ce que j'ai affronté, Huit choix de conception qu'un architecte peut questionner, chacun face à l'alternative refusée; Ce qu'on a construit, chaque choix en un bloc : le choix, le refus, pourquoi, le coût, avec sa doc officielle

Une longue salle de brique aux arcades et aux lampes suspendues, un petit canard jaune qui marche vers le fond

Ce chapitre est pour les architectes, les leads techniques et les concepteurs. Il est court exprès : huit décisions, chacune avec l'option qu'on a écartée, la raison et ce qu'elle nous coûte. Chaque affirmation sur un outil pointe vers sa doc officielle, pour que vous puissiez vérifier. Ce qu'on fait tourner est lu dans notre code sur main, pas de mémoire.

Les huit choix d'un coup d'œil

  • Messages

    Écarté
    Kafka
    Choisi
    RabbitMQ Pourquoi : il nous faut des files de travail (une tâche, un worker, puis elle disparaît). Ce que ça coûte : on opère le courtier ; chaque consommateur doit être idempotent.
  • Données

    Écarté
    NoSQL comme référence
    Choisi
    PostgreSQL, jsonb où il faut Pourquoi : des invariants entre lignes, gardés par une transaction. Ce que ça coûte : une migration à chaque changement de forme.
  • Vecteurs

    Écarté
    une base vectorielle à part
    Choisi
    pgvector dans le même PostgreSQL Pourquoi : le vecteur vit avec sa ligne, dans la même transaction et la même sauvegarde. Ce que ça coûte : l'extension avant les migrations ; HNSW coûte en mémoire.
  • Exécution

    Écarté
    un orchestrateur à nous
    Choisi
    peu de conteneurs, Next.js standalone Pourquoi : la plateforme build, déploie, redémarre et route. Ce que ça coûte : les JVM d'un conteneur vivent et meurent ensemble.
  • Tests de bout en bout

    Écarté
    retester la bibliothèque dans chaque produit
    Choisi
    Playwright (web), Maestro (mobile), sur les parcours Pourquoi : chaque test a un seul sujet. Ce que ça coûte : deux outils, et l'émulateur est lent.
  • CI

    Écarté
    une copie par dépôt
    Choisi
    36 workflows réutilisables, épinglés Pourquoi : une correction arrive partout par une montée d'épingle. Ce que ça coûte : changer un workflow partagé, c'est changer chaque dépôt.
  • Supervision

    Écarté
    Prometheus, Loki et Grafana chez nous
    Choisi
    Grafana Cloud, tableaux de bord en code Pourquoi : les sondes et le stockage ne sont pas notre produit. Ce que ça coûte : les limites de l'offre gratuite, et un caviardage avant Loki.
  • Code partagé

    Écarté
    copier entre produits, ou un seul dépôt
    Choisi
    des bibliothèques publiées, importées Pourquoi : un comportement écrit et testé une fois. Ce que ça coûte : une montée de version pour chaque changement.

Le détail suit, dans le même ordre.

La vue en C1 et C2

Deux vues d'un même modèle écrit en LikeC4, la notation du modèle C4, vérifié contre le modèle de base de l'organisation. Moins de détail que nos vues internes, et rien de sensible : ni hôte, ni adresse, ni compte.

Le contexte (C1)Clients et visiteurs utilisent Verikora et Folioviv ; Verikora demande des vérifications à Sovkora, le moteur d'IA ; les trois produits s'appuient sur les bibliothèques partagées, publiées sur les registres de paquets ; la plateforme fait tourner les workflows partagés sur GitHub, qui déploie main dans le cloud ; Sovkora envoie ses journaux, métriques et traces à la supervision.
ClientVisiteurPlateformeKrizakaVerikoraFoliovivGitHubSovkoraHébergementcloudBibliothèquespartagéesSupervisionRegistres depaquetsvérifie undocumenttient uneboutiqueachète sur unevitrinedemande desvérificationss'appuiesurs'appuiesurs'appuiesurvérifications, trainset publicationspubliéessurprovisionnedéploiemainjournaux,métriques,traces
Le schéma en mots

Éléments

  • Client: Une organisation ou une personne qui utilise un produit Krizaka.
  • Visiteur: Lit le site de l'entreprise, le blog et les sites des bibliothèques.
  • Plateforme Krizaka: Comment l'organisation travaille : CI et standards partagés, outillage des agents, infrastructure as code, gabarits.
  • Verikora: Vérifie des documents et garde les dossiers auxquels ils appartiennent.
  • Folioviv: Une boutique, sa vitrine et son éditeur.
  • GitHub: Le code, les tickets, les pull requests, la CI, la file de fusion et les tags.
  • Sovkora: Le moteur d'IA qu'appellent les produits : conversation, documents, médias, automatisations.
  • Hébergement cloud: L'hébergement des applications et des sites statiques, les bases de données gérées.
  • Bibliothèques partagées: Écrites une fois, versionnées, consommées par chaque produit.
  • Supervision: Tableaux de bord, journaux, traces et sondes de l'extérieur.
  • Registres de paquets: npm (@krizaka/*), Maven Central et GitHub Packages (com.krizaka), où les bibliothèques sont publiées.

Relations

  • Client → Verikora: vérifie un document
  • Client → Folioviv: tient une boutique
  • Visiteur → Folioviv: achète sur une vitrine
  • Verikora → Sovkora: demande des vérifications
  • Verikora → Bibliothèques partagées: s'appuie sur
  • Folioviv → Bibliothèques partagées: s'appuie sur
  • Sovkora → Bibliothèques partagées: s'appuie sur
  • Plateforme Krizaka → GitHub: vérifications, trains et publications
  • Bibliothèques partagées → Registres de paquets: publiées sur
  • Plateforme Krizaka → Hébergement cloud: provisionne
  • GitHub → Hébergement cloud: déploie main
  • Sovkora → Supervision: journaux, métriques, traces
Les conteneurs (C2)Verikora et Folioviv ont chacun une application web Next.js dans un conteneur, une application mobile Expo et une base PostgreSQL ; Sovkora a un service edge, les services du moteur, un courtier RabbitMQ, des workers Python et des bases PostgreSQL avec pgvector ; les applications web importent les paquets TypeScript et les services du moteur s'appuient sur les briques Java.
VerikoraFoliovivSovkoraBibliothèques partagéesVerikoramobileExpoFoliovivmobileExpoVerikora webNext.js, unconteneurFolioviv webNext.js, unconteneurBase VerikoraPostgreSQLBase FoliovivPostgreSQLService edgeSpring BootServices dumoteurSpring BootCourtierdemessagesRabbitMQBases SovkoraPostgreSQL,pgvectorWorkersPythonPaquets TypeScriptet UI@krizaka/*, npmBriques Javacom.krizaka, MavenSQLHTTPSSQLHTTPSHTTPSroutepublie depuisl'outboxSQL, outbox dans la mêmetransactionlivre, au moinsune foisrend lesrésultatsimporteimportes'appuiesur
Le schéma en mots

Éléments

  • Verikora: Vérifie des documents et garde les dossiers auxquels ils appartiennent.
    • Verikora mobile (Expo)
    • Verikora web (Next.js, un conteneur): Le site et la console, rendus côté serveur.
    • Base Verikora (PostgreSQL)
  • Folioviv: Une boutique, sa vitrine et son éditeur.
    • Folioviv mobile (Expo)
    • Folioviv web (Next.js, un conteneur): La vitrine et l'éditeur, rendus côté serveur.
    • Base Folioviv (PostgreSQL)
  • Sovkora: Le moteur d'IA qu'appellent les produits : conversation, documents, médias, automatisations.
    • Service edge (Spring Boot): La seule porte publique : authentification, limites de débit, routage.
    • Services du moteur (Spring Boot): Un service par contexte borné, plusieurs JVM dans un conteneur.
    • Courtier de messages (RabbitMQ): Files de travail par capacité, reprises, lettres mortes.
    • Bases Sovkora (PostgreSQL, pgvector): Une base par contexte ; l'outbox ; les vecteurs à côté des lignes.
    • Workers (Python): Médias, documents et modèles ; consomment les files.
  • Bibliothèques partagées: Écrites une fois, versionnées, consommées par chaque produit.
    • Paquets TypeScript et UI (@krizaka/*, npm): UI, authentification, données, paiements, stockage : le produit importe, il ne copie jamais.
    • Briques Java (com.krizaka, Maven): Le build parent, la BOM et les starters Spring Boot.

Relations

  • Verikora web → Base Verikora: SQL
  • Verikora mobile → Verikora web: HTTPS
  • Folioviv web → Base Folioviv: SQL
  • Folioviv mobile → Folioviv web: HTTPS
  • Verikora web → Service edge: HTTPS
  • Service edge → Services du moteur: route
  • Services du moteur → Courtier de messages: publie depuis l'outbox
  • Services du moteur → Bases Sovkora: SQL, outbox dans la même transaction
  • Courtier de messages → Workers: livre, au moins une fois
  • Workers → Courtier de messages: rend les résultats
  • Verikora web → Paquets TypeScript et UI: importe
  • Folioviv web → Paquets TypeScript et UI: importe
  • Services du moteur → Briques Java: s'appuie sur

1. RabbitMQ plutôt que Kafka

RabbitMQ porte les tâches de Sovkora jusqu'à ses workers. Un service écrit la tâche dans une table outbox, dans la même transaction que son propre changement, et un relais la publie. Chaque capacité a sa routing key : une tâche CPU et une tâche GPU arrivent dans des queues différentes. Les queues sont bornées (longueur maximale et débordement), un message en échec est repris puis envoyé en dead letter, et un consommateur acquitte ce qu'il a fini.

Pourquoi pas Apache Kafka : on a besoin de files de travail. Une tâche est faite une fois, par un worker, puis elle disparaît. Kafka est un journal partitionné où les événements « are not deleted after consumption » et sont gardés selon une durée par topic (Kafka, introduction). Le rejeu et le très gros débit, ses forces, ne sont pas notre problème aujourd'hui. Le routage AMQP, oui.

Le coût : on opère le courtier nous-mêmes, parce que notre hébergeur cloud au Canada propose Kafka en service géré, pas RabbitMQ. Un courtier perdu perd ses messages en vol ; c'est pour ça que l'outbox et la base portent la vérité, pas le courtier. La livraison est au moins une fois : chaque consommateur doit être idempotent.

2. Le relationnel plutôt que le NoSQL

PostgreSQL pour chaque produit, et une base par contexte borné dans Sovkora (moteur, utilisateurs, facturation, studio). Les parties souples sont des colonnes jsonb. La recherche de Verikora est la recherche plein texte de PostgreSQL. Les écritures concurrentes passent par des verrous de ligne et consultatifs et par FOR UPDATE … SKIP LOCKED.

Pourquoi pas une base documentaire comme référence : nos données ont des règles qui lient plusieurs lignes. Une réserve de crédits et la tâche qu'elle paie, une règle et ses révisions, un document et ses vérifications. Une transaction les garde vraies ensemble, et l'outbox ne marche que parce que le message et le changement sont commités d'un coup. jsonb donne la souplesse là où on en a besoin, sans deuxième moteur.

Le coût : chaque changement de forme est une migration versionnée, et on grandit en taille avant de grandir en nombre. Un modèle relationnel doit être surveillé contre les lectures non bornées et les requêtes N+1 ; nos règles Java les refusent.

3. Les vecteurs à côté des lignes : pgvector, pas une base vectorielle à part

pgvector, dans le même PostgreSQL. Le cache sémantique de Sovkora garde un embedding de 1024 dimensions, avec un index HNSW en distance cosinus, et les recommandations vivent dans la base de connaissances. Ce cache est éteint par défaut ; un pack doit l'allumer.

Pourquoi pas une base vectorielle dédiée : un vecteur ne sert qu'avec la ligne qu'il décrit. Même transaction, même sauvegarde, même filtre par client dans la même requête. pgvector fait la recherche exacte et approchée (HNSW, IVFFlat) avec « ACID compliance, point-in-time recovery, JOINs » de Postgres (pgvector).

Le coût : l'administrateur du cluster doit installer l'extension avant les migrations. Un index HNSW prend de la mémoire et du temps à construire. À une échelle qu'on n'a pas atteinte, un moteur dédié répondrait peut-être plus vite ; on ne l'a pas mesuré.

4. Peu de conteneurs, et Next.js dans l'un d'eux

L'application web de chaque produit est un serveur Next.js buildé avec output: "standalone" : une image Docker, lancée comme un service chez notre hébergeur cloud au Canada. Sovkora fait tourner un conteneur edge et un conteneur moteur qui démarre plusieurs JVM côte à côte. Ce qui a un état (PostgreSQL, le courtier) vit hors des conteneurs d'application. Nos sites (ce blogue, les docs des bibliothèques) sont des exports statiques. Chaque application est décrite par une spec versionnée dans son dépôt, et un outil signale tout écart entre ce fichier et l'application en ligne.

Pourquoi pas un conteneur par service sur un orchestrateur à nous : on est une petite équipe, un fondateur et des agents IA. La plateforme build, déploie à chaque push sur main, redémarre et route. La spec dans le dépôt est tout le deploy, relue comme du code.

Le coût : les JVM d'un même conteneur démarrent, s'arrêtent et grandissent ensemble. Si l'une sort, le conteneur sort et la plateforme relance le tout. Chaque JVM a sa heap dans la mémoire du conteneur, réglée à la main. Les limites de la plateforme sont les nôtres.

5. Playwright pour le web, Maestro pour le mobile

La preuve principale d'un produit, ce sont ses parcours : chacun tient une promesse au client, joué par une distribution de démonstration semée. Les parcours web sont des tests Playwright dans un projet nommé critical. Les parcours mobiles sont des flows YAML Maestro sur un émulateur Android, à chaque pull request. Chacun tourne depuis un workflow partagé, avec un check requis.

Ce qu'on a écarté : retester les composants de la bibliothèque dans chaque produit (snapshots, copies de ce que @krizaka/ui vérifie déjà), et de longues suites de bout en bout relancées après un test instable. Un test de produit a un seul sujet parmi trois : ses règles (unitaire), son serveur et son API (intégration, sur une vraie base), ses parcours (bout en bout). Un bogue dans un composant de la bibliothèque reçoit son test dans la bibliothèque. Les projets Playwright donnent une config par navigateur ou par appareil ; les flows Maestro sont courts, et quelqu'un qui ne code pas peut les lire.

Le coût : deux outils, deux syntaxes (TypeScript et YAML). L'émulateur est la partie la plus lente de notre CI. Et peu de parcours, c'est un trou possible entre eux, que les tests unitaires et d'intégration doivent couvrir.

6. La CI écrite une fois, dans GitHub

Le dépôt .github de l'organisation porte 36 workflows réutilisables (on: workflow_call) : Node, Java, Python, Rust, bout en bout mobile, parcours, analyses de sécurité. Chaque produit les appelle, épinglés à un SHA de commit complet, et merge par une merge queue.

Pourquoi pas une copie de la CI dans chaque dépôt : quand on corrige un check, la correction arrive partout par une montée d'épingle, et chaque dépôt répond aux mêmes checks requis, agents compris.

Le coût : changer un workflow partagé, c'est changer chaque dépôt. Il est donc testé seul, puis déployé par montées d'épingle. Un appelant ne peut changer que ce que le workflow expose en entrées.

7. La supervision avec Grafana, en code

Une stack Grafana Cloud. Synthetic Monitoring sonde nos sites publics de l'extérieur. Les services Java émettent des journaux structurés, des métriques et des traces par notre starter d'observabilité, et les exportent en OTLP dès que le point d'entrée d'un environnement est réglé. Les dashboards sont du JSON gardé en code et passé au lint.

Un dashboard a toujours la même forme : une rangée par application. D'abord la disponibilité et la latence vues de l'extérieur, puis le débit, les erreurs et la durée des requêtes, puis la saturation, puis les lignes d'erreur des journaux (Loki). On montre la forme et pas une capture, parce qu'une capture porterait des noms d'hôtes, des adresses et des comptes.

Pourquoi pas Prometheus, Loki et Grafana chez nous : les sondes, le stockage et les alertes ne sont pas notre produit, et l'offre gratuite hébergée couvre ce qu'on envoie aujourd'hui.

Le coût : les limites de l'offre gratuite sont les nôtres, et la télémétrie sort de notre hébergement. C'est pour ça que les journaux ne rejoignent Loki qu'après une étape de caviardage partagée. Aujourd'hui, les sondes tournent ; la télémétrie des services s'allume un environnement à la fois.

8. Des bibliothèques partagées, importées, jamais copiées

Des paquets TypeScript et UI sous le scope @krizaka (krizaka-ui, krizaka-ts, docs sur ui.krizaka.com et ts.krizaka.com). Des briques Java sous com.krizaka (krizaka-java, docs sur java.krizaka.com) : un build parent, une BOM et des starters Spring Boot pour le web, la sécurité, RabbitMQ, l'observabilité, la persistance et d'autres. L'application web de Verikora dépend de 28 paquets @krizaka, celle de Folioviv de 23 ; les services de Sovkora importent la BOM puis les starters, sans version à eux.

Pourquoi pas copier du code entre produits, ni un seul dépôt pour tout : un comportement est écrit, testé et documenté une fois ; un produit l'importe et ne teste que ses propres règles. Le starter RabbitMQ est l'endroit où « publié par une ligne transactionnelle, repris avec un délai croissant, puis mis en dead letter » est écrit une fois pour tous les services.

Le coût : un changement de bibliothèque n'arrive dans un produit que par une montée de version, et un changement cassant demande une version majeure et une migration chez chaque consommateur. Les bibliothèques sont publiques et open source : leur API est une promesse.

Ce que ce chapitre ne montre pas

Nos registres de décision restent internes : on en donne les raisons, pas le texte. Le modèle derrière les deux vues déclare les trois produits et les bibliothèques au niveau de ce chapitre ; le modèle complet de chaque produit vit dans son propre dépôt.