Vue d’ensemble de l’architecture
Cette note décrit le découpage actuel de l’umbrella Barrel et la direction qu’il prend. Lisez-la quand vous devez savoir quelle application porte une responsabilité, ou avant d’ajouter une nouvelle application à l’umbrella.
Applications actuelles
Barrel est une umbrella rebar3. Chaque application est une application OTP distincte, avec une responsabilité claire et sa propre API publique.
- barrel_docdb : la couche documents. Métadonnées des documents, MVCC, le flux de changements, les primitives de réplication, les pièces jointes, la timeline (branche, PITR, fusion) et la fondation catalogue/indexation. Utilisable seule comme base de documents embarquée.
- barrel_vectordb : la couche vecteurs. La base vectorielle embarquée, les index ANN locaux (HNSW, FAISS, DiskANN), BM25, et la recherche hybride locale qui les combine. Utilisable seule comme base vectorielle embarquée.
- barrel_embed : génération d’embeddings auprès de plusieurs fournisseurs
(Python local, Ollama, OpenAI et d’autres).
barrel_vectordbl’utilise pour la recherche textuelle et hybride. - barrel_rerank : reranking par cross-encoder. Optionnel, utilisé par
barrel_vectordb. - barrel_faiss : bindings NIF Erlang pour FAISS. Backend optionnel de
barrel_vectordb. Il demande la bibliothèque C++ FAISS, il est donc exclu du build par défaut. - barrel_ngram : index de sous-chaînes et d’expressions régulières par
trigrammes sur les documents
barrel_docdb, avec des segments immuables dotés de sommes de contrôle.barrel_serverle sert sous la forme de l’outil MCPngram_search. - barrel_crypto : primitives de chiffrement au repos. Enveloppe AES-256-GCM, CTR adressable par offset, dérivation de clés HKDF et fournisseurs de clés enfichables. Utilisé par docdb et vectordb pour les bases chiffrées.
- barrel : la base de données embarquable. Compose
barrel_docdb,barrel_vectordbetbarrel_cryptopour qu’un document, ses pièces jointes (blobs) et son vecteur partagent un même identifiant. Ajoute le mode enregistrement, BQL, le gestionnaire de cycle de vie des bases (barrel_dbs) et les contextes (barrel_ctx*: le catalogue de contextes, les requêtes fédérées, les ensembles de travail, l’export et l’import en lecture seule). La timeline elle-même vit dansbarrel_docdb;barrell’expose sur la base composée. Ne sert aucun protocole réseau ; son client de contextes distants appelle d’autres nœuds en HTTP. C’est le paquet hex « edge ». - barrel_spaces : la couche agents. Les espaces (bases de contexte
partagées), les jetons de capacité, les sessions avec TTL et les
passations, construits sur
barrel. - barrel_server : le serveur réseau. Expose
barreletbarrel_spacesen HTTP (REST/JSON) et en MCP aveclivery, y compris les routes/contextset/worksetset les outils MCPcontext_*. Activé sur demande via le profilserver; absent du build embarquable par défaut. - barrel_att_s3 : un backend de pièces jointes compatible S3 pour
barrel_docdb. Activé sur demande via le profils3.
Découpage visé
À plus long terme, la pile sépare ces responsabilités :
- docdb (existe) : la source de vérité des métadonnées de documents et du catalogue. MVCC, changements, primitives de réplication et stockage des pièces jointes (blobs).
- vectordb (existe) : segments vectoriels et recherche locale vectorielle, textuelle et hybride.
- barrel (existe) : compose docdb et vectordb dans un même espace d’identifiants.
- server (existe,
barrel_server) : les transports au-dessus de l’APIbarrel. - stockage objet : les blobs sont des pièces jointes docdb avec un
backend enfichable par base (
barrel_att_backend: RocksDB BlobDB par défaut,nonepour les bases sans pièces jointes, et un stockage compatible S3 viabarrel_att_s3). Il n’y a pas d’application de stockage objet séparée ; un document possède son blob, comme les vecteurs et les métadonnées se rattachent au même identifiant. - couche agents (existe,
barrel_spaces+ MCP) : espaces, jetons de capacité, sessions et passations au-dessus de l’APIbarrel; exposée parbarrel_server. - contextes (existe,
barrel_ctx*dansbarrel, REST et MCP dansbarrel_server) : des jeux de données nommés interrogés ensemble à travers les nœuds, avec des ensembles de travail et des copies portables en lecture seule. Voir le guide des contextes. - fabric (futur,
barrel_fabric) : agents de jeux de données, durabilité, placement et orchestration de la réplication entre nœuds.
Règles de frontière
Ces règles gardent l’umbrella maintenable à mesure qu’elle grandit :
- Des frontières d’applications OTP claires. Chaque application possède ses modules et son API publique.
- Pas de dépendances circulaires entre applications. Le sens est
barrel_server->barrel_spaces->barrel-> {barrel_docdb,barrel_vectordb},barrel_server->barrel_ngram->barrel_docdb, etbarrel_vectordb->barrel_embed(et en optionbarrel_faiss,barrel_rerank).barrel_docdbetbarrel_vectordbsont des feuilles ;barrel_docdb->barrel_vectordbest interdit. - Préférer des modules propres à chaque application à des modules globaux partagés. Éviter une application « fourre-tout » commune.
- L’usage local ne demande aucun service externe. S3, la réplication distante et les agents fabric ne sont jamais nécessaires pour faire tourner une application en local.
- Les backends lourds optionnels (par exemple FAISS) restent activés sur demande et hors du build par défaut.
Périmètre et justification
Cette umbrella contient les bibliothèques de la pile de données Barrel
(barrel_docdb, barrel_vectordb, barrel_embed, barrel_rerank,
barrel_faiss, barrel_ngram, barrel_crypto, barrel_att_s3), la base
embarquable (barrel), la couche agents (barrel_spaces) et le serveur
réseau (barrel_server). Les produits et les clients construits sur la pile
restent dans leurs propres dépôts.
Ce que l’umbrella vous apporte
- La coordination des versions : un seul ensemble de dépendances résolu pour
toutes les applications. Elle a déjà imposé un seul
hackney(4.4.0) et un seulmeck(1.2.0) là où les dépôts séparés avaient divergé, et fait apparaître en une passe le correctif ducatchpréfixe d’OTP 29. - Des changements atomiques entre applications :
barrel_vectordbet ses backends (barrel_embed,barrel_rerank,barrel_faiss) évoluent ensemble. Un changement de l’API vectordb et de ses adaptateurs tient en un commit et une exécution de CI, sans courir après les tags d’un dépôt à l’autre. - Une seule surface de build, de test et de release : des profils partagés
(l’activation de FAISS), une seule PLT, un seul
rel/. - Un foyer pour les couches qui traversent la pile :
barrel(la base complète) unifie déjà docdb et vectordb sous un même identifiant, etbarrel_fabric(futur) les étendra à plusieurs nœuds. Une couche qui unifie deux applications demande un dépôt qui contient les deux.barrel_docdbne partage aucun code avecbarrel_vectordb: sa place ici se justifie parbarrelet par le travail à venir sur fabric.
Hors périmètre (séparé volontairement)
barrellm: une couche application/service qui consomme la pile (barrellm->barrel_docdb+barrel_embed). Elle a sa propre surface HTTP/MCP, son propre rythme de release et des dépendances épinglées bien plus anciennes (par exemple rocksdb 2.5.0, hackney 1.20.1/2.0.1). L’intégrer inverserait les couches et ramènerait la pile vers des dépendances plus anciennes.barrel_llm: un répertoire vide, simple emplacement réservé. Rien à importer.
Si des produits doivent être co-développés plus tard
Gardez-les dans des dépôts séparés qui dépendent de la pile, via des
dépendances par chemin pour le travail local
({path, "../barrel/apps/barrel_vectordb"}) ou via les paquets publiés.
S’ils grandissent, regroupez-les dans leur propre umbrella d’applications
(par exemple barrel_apps) qui dépend de celle-ci, plutôt que de mélanger
bibliothèques et produits à plat.
Organisation du build
apps/contient les applications.- Le
rebar.configde premier niveau coordonne le build et agrège les dépendances déclarées par chaque application. Il restreint l’ensemble d’applications par défaut pour que l’application FAISS soit activée sur demande (rebar3 as faiss compile), comme le serveur (rebar3 as server compile) et le backend S3 (rebar3 as s3 compile). rel/contient le squelette de release de l’umbrella.docs/contient la documentation au niveau de l’umbrella ; la documentation propre à chaque application reste dans l’application.