> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture des connecteurs

> Comment FIM One connecte les systèmes hérités via l'IA — de Copilot à Hub.

## Copilot vs Hub

L'architecture prend en charge deux échelles d'intégration :

```mermaid theme={null}
flowchart TD
    subgraph Copilot["Copilot (embedded)"]
        subgraph Host["Host System (ERP)"]
            C["FIM One Copilot<br/>(iframe / widget)"]
        end
        C --> DB1["DB"]
        C --> API1["API"]
    end

    subgraph Hub["Hub (central portal)"]
        H["FIM One Hub<br/>(Portal / API)"]
        H --> ERP["ERP"]
        H --> CRM["CRM"]
        H --> OA["OA"]
        H --> Lark["Lark"]
        H --> DB2["DB"]
        H --> CustomAPI["Custom API"]
    end
```

**Copilot** s'intègre dans l'interface utilisateur d'un système hôte. Les utilisateurs interagissent avec l'IA sans quitter leur interface familière. Il peut utiliser plusieurs connecteurs (DB hôte + service de notification, etc.).

**Hub** est un portail autonome qui connecte tous les systèmes. Il n'est intégré dans aucun système unique -- c'est la couche d'intelligence centrale où les systèmes rencontrent l'IA.

Même architecture de connecteur, livraison différente. Un Copilot utilise le même `ConnectorToolAdapter` qu'un Hub.

## Principe fondamental

**Le client ne change aucun code.** FIM One s'intègre proactivement dans leurs systèmes -- en lisant leurs bases de données, en appelant leurs API, en poussant vers leur bus de messages. Le client fournit uniquement les identifiants et l'accès réseau.

## Architecture à trois couches

```mermaid theme={null}
flowchart TB
    A["<b>FIM One Platform</b><br/>ReAct / DAG / Portal UI<br/><i>Multi-tenant, scheduling, conversation persistence</i>"]
    B["<b>Connector Governance Layer</b><br/>audit log, auth passthrough, operation classification<br/><i>read_only enforcement, confirmation gate, circuit breaker</i>"]
    C["<b>MCP Protocol (Transport)</b><br/>stdio / HTTP transport<br/><i>Standard tool description, process isolation</i>"]
    D["<b>Legacy System</b><br/>DB / API / MQ<br/><i>Client's existing systems</i>"]

    A --> B --> C --> D
```

Chaque couche a une responsabilité distincte :

| Couche                                    | Responsable de                           | Change quand...                                           |
| ----------------------------------------- | ---------------------------------------- | --------------------------------------------------------- |
| **Plateforme**                            | Orchestration, multi-tenant, UI          | De nouvelles fonctionnalités de plateforme sont déployées |
| **Couche de gouvernance des connecteurs** | Politiques de gouvernance d'entreprise   | Les exigences de sécurité/conformité changent             |
| **Protocole MCP**                         | Transport, standard d'interface d'outils | Jamais (norme ouverte)                                    |
| **Système hérité**                        | Données métier et logique                | Jamais (c'est tout l'intérêt)                             |

## Pourquoi MCP comme couche de transport

Les adaptateurs sont implémentés en tant que **Serveurs MCP**. Il s'agit d'un choix architectural délibéré :

* **Réutilisabilité** : FIM One est déjà livré avec un Client MCP (v0.3). L'ajout d'un adaptateur de système hérité réutilise la même infrastructure que l'ajout de n'importe quel outil MCP.
* **Protocole standard** : MCP est une norme ouverte. Aucun protocole propriétaire à inventer ou maintenir.
* **Écosystème** : Les serveurs MCP tiers (bases de données, API, outils SaaS) fonctionnent immédiatement.
* **Isolation des processus** : Chaque serveur MCP s'exécute en tant que processus distinct. Un adaptateur défaillant ne peut pas faire planter la plateforme.

### Ce que MCP seul ne fournit pas

La **Couche de gouvernance des connecteurs** ajoute la gouvernance d'entreprise que MCP brut ne possède pas :

| Préoccupation                   | MCP | Couche de gouvernance des connecteurs                                                       |
| ------------------------------- | --- | ------------------------------------------------------------------------------------------- |
| Application de la lecture seule | Non | Drapeau `read_only` sur les opérations ; écriture bloquée par défaut                        |
| Journalisation d'audit          | Non | Chaque appel d'outil enregistré (horodatage, utilisateur, outil, paramètres, résultat)      |
| Authentification directe        | Non | Authentification du système hôte proxy ; l'agent agit au nom de l'utilisateur connecté      |
| Porte de confirmation           | Non | Les opérations d'écriture nécessitent une approbation humaine (SSE `confirmation_required`) |
| Disjoncteur                     | Non | L'échec de la connexion déclenche une dégradation progressive                               |
| Classification des opérations   | Non | Opérations étiquetées comme lecture/écriture/administration avec des politiques par niveau  |

### Pourquoi ne pas inventer un protocole personnalisé

Le protocole est une commodité. La valeur technique réside dans les adaptateurs eux-mêmes (connaissance du domaine, mappage de schéma, gestion des cas limites) et la couche de gouvernance (audit, authentification, sécurité). Inventer un protocole de transport ajouterait un coût de maintenance sans ajouter de capacité. Stripe utilise HTTPS ; Docker utilise cgroups ; FIM One utilise MCP.

## Modèle de déploiement

Tout s'exécute dans un seul déploiement Docker Compose. Le client n'installe rien.

```mermaid theme={null}
flowchart TD
    subgraph Docker["FIM One Deployment (Docker Compose)"]
        subgraph Core["FIM One Core"]
            R["ReAct / DAG"]
            P["Platform API"]
            U["Portal UI"]
            G["Connector Governance"]
        end

        subgraph MCP1["MCP Server: Finance DB"]
            M1["SQL queries (read-only)"]
        end

        subgraph MCP2["MCP Server: OA System"]
            M2["REST API calls"]
        end

        subgraph MCP3["MCP Server: Lark"]
            M3["Webhook notifications"]
        end

        Core --> MCP1
        Core --> MCP2
        Core --> MCP3
    end

    MCP1 --> Oracle["Client's Oracle DB"]
    MCP2 --> Seeyon["Client's Seeyon OA"]
    MCP3 --> Lark["Lark API"]
```

<Note>
  Tous fournis par FIM One. Le client fournit uniquement :

  * Les identifiants de base de données (compte en lecture seule recommandé)
  * Les points de terminaison API et les clés (si disponibles)
  * L'accès à la liste blanche du réseau
</Note>

**Hiérarchie d'accès** : FIM One s'adapte à l'accès que le client peut fournir :

| Ce que le client a                    | Comment FIM One se connecte                                          |
| ------------------------------------- | -------------------------------------------------------------------- |
| API avec documentation                | Adaptateur HTTP API (meilleur cas)                                   |
| API sans documentation                | Adaptateur HTTP API + mappage de schéma manuel                       |
| Accès à la base de données uniquement | Adaptateur de base de données (SQL direct, lecture seule par défaut) |
| Base de données + bus de messages     | Adaptateur de base de données + adaptateur de push de messages       |

## Découplage Agent-Connecteur

L'agent voit les connecteurs comme des outils ordinaires. Il ne sait pas et ne se soucie pas de savoir si un outil est intégré, un serveur MCP tiers ou un connecteur de système hérité.

```mermaid theme={null}
flowchart TB
    Agent["Liste d'outils de l'Agent"]

    subgraph BuiltIn["Outils intégrés"]
        T1["web_search"]
        T2["calculator"]
    end

    subgraph Connector["Outils Connecteur"]
        T3["contract_query"]
        T4["finance_report"]
        T5["lark_push"]
    end

    Agent --- BuiltIn
    Agent --- Connector
```

Cela signifie :

* **Ajouter** un nouveau système = ajouter une configuration de connecteur. Le code de l'agent ne change pas.
* **Supprimer** un connecteur = supprimer la configuration. Aucune modification de code.
* Le même agent peut utiliser des outils intégrés et des connecteurs dans une seule tâche.

## Évolution du Hot-Plug

| Version  | Comment ajouter un nouveau connecteur                                                             | Redémarrage requis ?              |
| -------- | ------------------------------------------------------------------------------------------------- | --------------------------------- |
| **v0.6** | Écrire un serveur MCP Python avec couche de gouvernance des connecteurs, ajouter à docker-compose | Redéploiement                     |
| **v0.8** | Écrire une config YAML/JSON, la plateforme génère le serveur MCP                                  | Redémarrage                       |
| **v1.0** | Télécharger une spécification OpenAPI, l'IA génère la config automatiquement                      | **Pas de redémarrage (hot-plug)** |

Les déploiements d'entreprise sont « implémenter une fois, exécuter pendant des mois » -- le hot-plug est une commodité de v1.0, pas une exigence de v0.6.

## Exemple de flux de données

Utilisateur : « Vérifier tous les contrats en retard du système financier et envoyer un résumé à Lark. »

```
1. User sends message via Portal / API

2. FIM One (ReAct mode):
   Think: I need to query the finance DB for overdue contracts, then push to Lark.

3. Act: contract_query(status="overdue", days_past_due=">30")
   → Connector Governance: audit log, read_only check (pass)
   → MCP Server: translates to SQL
   → Client DB: SELECT * FROM contracts WHERE status='overdue' AND ...
   ← Returns 7 overdue contracts

4. Think: Found 7 overdue contracts. I'll summarize and push.

5. Act: lark_push(message="7 overdue contracts found: ...")
   → Connector Governance: audit log, write operation → confirmation gate
   → User approves via Portal
   → MCP Server: POST to Lark webhook
   ← Push successful

6. Answer: "Found 7 overdue contracts. Summary pushed to Lark group."
```

## Niveaux de standardisation des connecteurs

| Niveau       | Version | Approche                                                                         | Qui le construit                                                |
| ------------ | ------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| **Niveau 1** | v0.6    | Serveur MCP Python avec gouvernance des connecteurs                              | Développeur FIM One                                             |
| **Niveau 2** | v0.8    | Configuration YAML/JSON, génération automatique du serveur MCP par la plateforme | Ingénieur d'implémentation (aucune connaissance Python requise) |
| **Niveau 3** | v1.0    | Télécharger la spécification OpenAPI/Swagger, l'IA génère la configuration       | IA (avec révision humaine)                                      |

## Relation avec l'écosystème MCP existant

Le Client MCP de FIM One (livré en v0.3) supporte déjà les serveurs MCP tiers. Les adaptateurs de systèmes hérités sont simplement des **serveurs MCP spécifiques au domaine** construits avec la couche de gouvernance des connecteurs pour la gouvernance d'entreprise.

```mermaid theme={null}
flowchart TB
    subgraph MCP["MCP Ecosystem (third-party)"]
        M1["filesystem server"]
        M2["GitHub server"]
        M3["Slack server"]
        M4["any community MCP server"]
    end

    subgraph CG["Connector Governance (FIM One)"]
        C1["read_only enforcement"]
        C2["audit logging"]
        C3["auth passthrough"]
        C4["confirmation gate"]
    end

    MCP --> TR["ToolRegistry"]
    CG --> TR
    TR --> Agent["Agent sees all as tools"]
```

La couche de gouvernance des connecteurs ne remplace pas MCP -- elle étend MCP avec la couche de gouvernance que l'intégration des systèmes hérités d'entreprise nécessite.