Aller au contenu

ADR-030 — Isolation des bases Python / TS : ownership par service + API pour la donnée partagée
Statut Accepted
Date 20/07/2026 (échange Slack Romain × Dimitri, évoqué avec Denis Mludek et William Delmas) — précisé 21/07 (moteur = Neon, pas Mongo)
Décideurs Romain BAZIL, Dimitri Hertz (alignement Denis × William sur le principe)
Origine Échange Slack 20/07/2026 + synchro Dimitri 21/07 + projet Linear « Isolation DB Python × API TS » (BRI-1611)
Amende ADR-025 (partie « mono-base greffée » et écritures directes Python → Neon outil d'analyse)

Contexte

Le système est scindé en deux apps (ADR-024) : IA-analyse-API (Python, agents) et project-analysis (TypeScript, outil d'analyse). En juin 2026, ADR-025 avait acté une mono-base Postgres/Neon greffée : l'app Python écrivait directement dans le Neon de l'outil d'analyse pour aller vite.

Ce choix montre ses limites : l'app Python détient des credentials sur la base TS, gère ses propres migrations sur des tables mélangées, et plusieurs sources (Python, Manus, autres) peuvent peupler la même donnée métier sans passer par un contrôle unique. Manus passe déjà par l'API TS ; Python, non.

Discussion du 20/07 : Denis, William, Dimitri et Romain convergent sur le principe microservices — chaque service possède sa base ; on n'écrit dans la base d'un autre service qu'en passant par son API — sans tout centraliser côté TS.

Décision

Données internes IA (runs, exécutions agents, sentinel, ingest…)  →  Base Postgres/Neon dédiée Python (ownership + migrations Python)
Donnée métier partagée (sections, workflows, UI…)               →  API de l'app TS uniquement (ownership + schéma TS)
Recherche vectorielle                                              →  Qdrant (inchangé — ADR-025)
Moteur DB Python                                                   →  Neon/Postgres (pas Mongo)

Règle d'ownership : une table appartient à un seul service. L'autre service y accède en écriture uniquement via l'API du propriétaire.

Moteur pour la base Python (précisé le 21/07) : Neon/Postgres, même si la nature des données internes est plutôt documentaire. Les avantages Mongo (migrations souples, scale extrême) ne justifient pas d’introduire une techno hors stack Bricks — cf. alternatives écartées.

Tables internes Python (base dédiée, migrations Python)

Table Rôle
analysis_runs Suivi des analyses (statut, phase, métadonnées)
agent_executions Sorties par agent (résultats, tokens, erreurs, tool calls)
incidents Self-healing / Sentinel
sentinel_state État du système de surveillance
ingestion_manifests Manifeste incrémental d'ingestion documentaire
project_financial_analyses Snapshot analyse financière structurée (PFA)

Donnée métier commune (API TS)

  • section_versions et tables liées (sections, workflows) — contenu affiché dans l'outil d'analyse
  • Toute table utile aux personas (analyste, comité, AM) et aujourd'hui écrite en direct depuis Python

Ce que ça ne change pas : la logique métier des agents (on change le comment on persiste, pas ce qu'on analyse).

Rationale

  • Sécurité : retirer les credentials Neon outil d'analyse de l'app Python ; chaque service n'accède qu'à sa base.
  • Ownership clair : les tables purement IA (runs, sentinel, ingest) n'ont pas vocation à vivre dans le schéma TS — même logique que Qdrant (base dédiée au microservice).
  • Une porte d'entrée pour le métier : publication via l'API TS = mêmes schémas, mêmes contrôles, que la source soit Python, Manus ou une future intégration.
  • Migrations découplées : le Python gère l'évolution de ses tables sans interférer avec Drizzle côté TS (et inversement pour le métier).
  • Pas de sur-centralisation : faire passer toute la persistance par le TS aurait déplacé l'ownership des tables internes IA vers une app qui ne les consomme pas.

Conséquences

Ce qui change

  1. Deux bases Postgres/Neon : une pour l'outil d'analyse (TS), une pour le microservice Python — au lieu d'une seule base greffée.
  2. L'app Python n'écrit plus en direct dans les tables métier du Neon TS ; elle appelle l'API TS (auth service-to-service, retries, gestion d'erreurs).
  3. Les tables listées ci-dessus migrent vers la base Python ; l'historique est migré ou gelé selon plan de cutover.
  4. Manus et toute autre source de donnée métier doivent utiliser la même API TS (alignement à vérifier — BRI-1618).

Ce qu'il faut faire

  • Cartographier ownership table par table + inventorier les écritures directes Python → Neon TS (BRI-1612, BRI-1613).
  • Provisionner la base Python dédiée (local / preprod / prod) — BRI-1614. Acté 21/07 : Denis crée la base Neon Python (accès centralisés).
  • Migrer les tables internes IA — BRI-1615 (estimé Dimitri : ½–1 j une fois la DB dispo).
  • Exposer les endpoints de publication côté TS — BRI-1616 (Romain, contrat d’API cadré par Dimitri ; pas d’auth m2m redondante inutile — Dimitri revoit l’auth Python ↔ TS et le fouillis de variables d’env au passage).
  • Implémenter le client Python → API TS — BRI-1617.
  • Planifier le cutover, retirer les credentials partagés, valider en prod — BRI-1619, BRI-1620.
  • Lié : sortir le lancement Composable/Haiku du Python pour que l’outil d’analyse (TS) orchestre les deux analyses en parallèle — chantier d’orchestration, pas de modèle de données, mais même vague de fondations.

Ce qu'il faut éviter

  • Continuer les écritures directes Python → tables métier TS « en attendant » sans date de fin.
  • Faire passer les tables internes IA par l'API TS : ownership incohérent, complexité inutile.
  • Dupliquer la logique métier dans l'API TS au lieu de réutiliser les contrôles existants.
  • Oublier une source (Manus, script, autre) qui écrirait encore en direct dans le Neon TS.

Suivi opérationnel au 04/08/2026

La séparation est en place, mais le weekly S32 a fait apparaître deux prérequis d'exploitation non soldés :

  1. Migrations reproductibles : l'état de la base Python doit pouvoir être reconstruit sans deviner les changements appliqués. L'outil, l'historique, l'exécution par environnement et le retour arrière restent à fiabiliser.
  2. Tests preprod représentatifs : Dimitri doit pouvoir valider une évolution sur quelques dossiers réalistes en déclenchant le même parcours qu'en production.

Le snapshot manuel avant le déploiement du 04/08 est un garde-fou ponctuel. Il ne vaut pas procédure durable de migration ou de restauration.

Alternatives écartées

  • Tout passer par l'API TS (y compris tables internes IA) : rejeté par Dimitri — ces tables n'appartiennent pas au modèle métier TS ; le TS n'a pas à gérer runs, sentinel, ingest. Complexifie l'API sans gain produit.
  • Conserver la mono-base greffée (statu quo ADR-025) : acceptable pour la vélocité initiale, mais credentials partagés, migrations croisées, pas de porte d'entrée unique pour le métier. Le gain sécurité / isolation justifie la bascule maintenant.
  • Nouvelle techno de persistance (Mongo, etc.) pour la base Python : écarté une deuxième fois le 21/07. Dimitri reconnaît que la data interne est plutôt documentaire et que Mongo évite les migrations, mais l’écart avec Postgres/JSONB s’est resserré ; Bricks est déjà sur Neon, sans habitus Mongo, et on n’a pas de contrainte de scale qui justifierait le changement. « Le “un peu mieux” ne va pas justifier le changement que ça ferait de votre côté niveau infra. » — Dimitri, 21/07. Cohérent avec ADR-025.

Verbatims

« Aujourd'hui l'app Python écrit directement dans Neon […] Manus, lui, passe déjà par l'API TS. La logique semble pousser vers le fait que tout peuplement passe par l'API TS […] isoler les deux apps, ne plus avoir les credentials DB côté Python. » — Romain BAZIL, Slack 20/07/2026

« Je ne conseille pas forcément de passer uniquement par le TS pour écrire en DB. […] Dans l'idéal il faudrait plutôt 2 BDD séparées : 1 pour l'app TS, 1 pour le microservice python avec ses datas internes — de la même manière que l'app python gère Qdrant. » — Dimitri Hertz, Slack 20/07/2026

« Pour toutes les autres tables qui sont communes aux workflows comme section / version, etc. ce sera l'app TS qui gère l'écriture dans la DB. Dans une architecture microservices pure, chaque service a sa propre BDD et tu ne peux écrire dans cette BDD qu'en passant par le service qui en est propriétaire. » — Dimitri Hertz, Slack 20/07/2026

« Si vous avez tout votre infra sur Neon et que vous n’avez jamais utilisé MongoDB, je peux faire la même chose avec Neon. […] le “un peu mieux” ne va pas justifier le changement. » — Dimitri Hertz, synchro 21/07/2026

Voir aussi

Sources