> ## 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.

# Connector Architecture

> How FIM One connects legacy systems through AI — from Copilot to Hub.

## Copilot vs Hub

The architecture supports two integration scales:

```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** embeds into a host system's UI. Users interact with AI without leaving their familiar interface. It can use multiple connectors (host DB + notification service, etc.).

**Hub** is a standalone portal that connects all systems. It's not embedded in any single system -- it's the central intelligence layer where systems meet AI.

Same connector architecture, different delivery. A Copilot uses the same `ConnectorToolAdapter` as a Hub.

## Core Principle

**The client changes zero code.** FIM One bridges into their systems proactively -- reading their databases, calling their APIs, pushing to their message bus. The client provides only credentials and network access.

## Three-Layer Architecture

```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
```

Each layer has a distinct responsibility:

| Layer                          | Owns                               | Changes when...                         |
| ------------------------------ | ---------------------------------- | --------------------------------------- |
| **Platform**                   | Orchestration, multi-tenant, UI    | New platform features ship              |
| **Connector Governance Layer** | Enterprise governance policies     | Security/compliance requirements change |
| **MCP Protocol**               | Transport, tool interface standard | Never (open standard)                   |
| **Legacy System**              | Business data and logic            | Never (that's the whole point)          |

## Why MCP as the Transport Layer

Adapters are implemented as **MCP Servers**. This is a deliberate architectural choice:

* **Reuse**: FIM One already ships an MCP Client (v0.3). Adding a legacy system adapter reuses the same infrastructure as adding any MCP tool.
* **Standard protocol**: MCP is an open standard. No proprietary protocol to invent or maintain.
* **Ecosystem**: Third-party MCP Servers (databases, APIs, SaaS tools) work out of the box.
* **Process isolation**: Each MCP Server runs as a separate process. A misbehaving adapter cannot crash the platform.

### What MCP alone does not provide

The **Connector Governance Layer** adds enterprise governance that raw MCP lacks:

| Concern                  | MCP | Connector Governance Layer                                            |
| ------------------------ | --- | --------------------------------------------------------------------- |
| Read-only enforcement    | No  | `read_only` flag on operations; write blocked by default              |
| Audit logging            | No  | Every tool call recorded (timestamp, user, tool, params, result)      |
| Auth passthrough         | No  | Proxy host-system auth; agent acts on behalf of logged-in user        |
| Confirmation gate        | No  | Write operations require human approval (SSE `confirmation_required`) |
| Circuit breaker          | No  | Connection failure triggers graceful degradation                      |
| Operation classification | No  | Operations tagged as read/write/admin with per-level policies         |

### Why not invent a custom protocol

Protocol is commodity. The technical value is in the adapters themselves (domain knowledge, schema mapping, edge-case handling) and the governance layer (audit, auth, safety). Inventing a transport protocol would add maintenance cost without adding capability. Stripe uses HTTPS; Docker uses cgroups; FIM One uses MCP.

## Deployment Model

Everything runs in a single Docker Compose deployment. The client installs nothing.

```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>
  All provided by FIM One. Client provides only:

  * Database credentials (read-only account recommended)
  * API endpoints and keys (if available)
  * Network whitelist access
</Note>

**Access hierarchy**: FIM One adapts to whatever access the client can provide:

| What client has           | How FIM One connects                                |
| ------------------------- | --------------------------------------------------- |
| API with documentation    | HTTP API adapter (best case)                        |
| API without documentation | HTTP API adapter + manual schema mapping            |
| Database access only      | Database adapter (direct SQL, read-only by default) |
| Database + message bus    | Database adapter + message push adapter             |

## Agent-Connector Decoupling

The agent sees connectors as ordinary tools. It does not know or care whether a tool is built-in, a third-party MCP Server, or a legacy system connector.

```mermaid theme={null}
flowchart TB
    Agent["Agent's Tool List"]

    subgraph BuiltIn["Built-in Tools"]
        T1["web_search"]
        T2["calculator"]
    end

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

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

This means:

* **Adding** a new system = adding a connector config. Agent code does not change.
* **Removing** a connector = removing the config. No code changes.
* The same agent can use built-in tools and connectors in a single task.

## Hot-Plug Evolution

| Version  | How to add a new connector                                                       | Restart required?         |
| -------- | -------------------------------------------------------------------------------- | ------------------------- |
| **v0.6** | Write a Python MCP Server with Connector Governance Layer, add to docker-compose | Redeploy                  |
| **v0.8** | Write a YAML/JSON config, platform generates MCP Server                          | Restart                   |
| **v1.0** | Upload OpenAPI spec, AI generates config automatically                           | **No restart (hot-plug)** |

Enterprise deployments are "implement once, run for months" -- hot-plug is a v1.0 convenience, not a v0.6 requirement.

## Data Flow Example

User: "Check all overdue contracts from the finance system and push a summary to 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."
```

## Connector Standardization Levels

| Level       | Version | Approach                                             | Who builds it                              |
| ----------- | ------- | ---------------------------------------------------- | ------------------------------------------ |
| **Level 1** | v0.6    | Python MCP Server with Connector Governance          | FIM One developer                          |
| **Level 2** | v0.8    | YAML/JSON config, platform auto-generates MCP Server | Implementation engineer (no Python needed) |
| **Level 3** | v1.0    | Upload OpenAPI/Swagger spec, AI generates config     | AI (with human review)                     |

## Relationship to Existing MCP Ecosystem

FIM One's MCP Client (shipped in v0.3) already supports third-party MCP Servers. Legacy system adapters are simply **domain-specific MCP Servers** built with the Connector Governance Layer for enterprise governance.

```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"]
```

The Connector Governance Layer does not replace MCP -- it extends MCP with the governance layer that enterprise legacy system integration requires.