Aller au contenu

Architecture

Les trois couches

src/aim/
├── core/      métier pur : modèles, extraction, consolidation, compilation
├── server/    API FastAPI, MCP, authentification, PostgreSQL, Blob
└── cli/       client léger : appels HTTP, écriture des packs, cache

core ne connaît ni HTTP, ni PostgreSQL, ni Azure : il ne dépend que d'un protocole Store de dix méthodes. C'est ce qui permet de le tester avec un double en mémoire, en une fraction de seconde, et de changer de moteur de stockage sans le toucher.

flowchart TD
    subgraph poste["Poste de travail"]
        CLI[CLI aim]
        CACHE[(~/.aim/cache)]
        REPO[Dépôt client<br/>CLAUDE.md · AGENTS.md]
    end
    subgraph azure["Azure — rg-aim-prod"]
        API[Container App<br/>API + MCP]
        PG[(PostgreSQL<br/>privé)]
        BLOB[(Blob<br/>sources brutes)]
        KV[Key Vault]
    end
    AGENT[Agent de code]

    CLI -->|HTTPS + Entra| API
    CLI --> CACHE
    CLI --> REPO
    AGENT -->|MCP + clé d'API| API
    AGENT --> REPO
    API --> PG
    API --> BLOB
    API --> KV

Les cinq principes

1. Le pipeline est une suite de transformations idempotentes

Source → Document → Fait → Pack. Un document dont l'empreinte n'a pas changé n'est jamais réextrait. Réingérer un corpus stable ne coûte rien.

C'est cette propriété qui permettra de brancher un flux continu — webhooks, capture d'écran — sans repenser le système.

2. Rien n'entre dans un pack sans provenance

Un fait cite son document et l'extrait exact qui le justifie. Quand l'agent applique une règle jugée fausse, on remonte en un geste à la source, et on corrige la source plutôt que le pack.

3. L'utilisateur ne range rien

La nature d'un document est déduite par le modèle au moment de l'extraction, dans le même appel que les faits. La seule hiérarchie imposée, observed contre declared, se déduit de l'origine.

Une version antérieure demandait de classer les fichiers en sous-dossiers. C'était une fuite de l'implémentation vers l'utilisateur ; elle a été supprimée.

4. Le code client ne quitte pas le poste

Le lecteur de dépôt tourne dans le CLI. Il réduit un dépôt à six signaux de structure et n'envoie que ces résumés.

5. Le refus d'accès ne révèle rien

Un client auquel un principal n'a pas accès renvoie 404, jamais 403.

Décisions structurantes

Décision Alternative écartée Pourquoi
PostgreSQL + full-text Azure AI Search ~75 €/mois pour un service utilisé à 10 %, contre ~18 € pour un moteur qui donne aussi le relationnel
Un réplica permanent Scale-to-zero Le démarrage à froid se paierait en attente humaine au milieu d'un raisonnement d'agent
Base en sous-réseau délégué Pare-feu d'IP publiques Une règle par machine et par collaborateur, contre zéro exposition
Clés d'API pour les agents Jeton Entra partout Un jeton expire en une heure, inutilisable pour un MCP configuré une fois
Flux NDJSON File de tâches Suffit à un réplica, et évite un composant de plus
MkDocs Material Docusaurus Même langage que le projet : un seul outillage à maintenir

Pour aller plus loin