# 4. Architecture

### 4.1 Control Plane vs Data Plane

Control plane components compute quotes and route plans from a normalised liquidity graph snapshot. Data plane components execute multi-leg plans and maintain the exchange lifecycle.

```mermaid
flowchart LR
    subgraph CP["Control Plane"]
        A["API Gateway
(x-api-key)"]
        B["Graph Service 
snapshot builder)"]
        C["Constraints & Policy
(venue/limits/TTL)"]
        R["Routing Engine
(k-best + scoring)"]

        A --> R
        B --> R
        C --> R
    end

    subgraph DP["Data Plane"]
        S["Swap/Exchange Service
(state machine)"]
        Q[("Durable Queue")]
        E["Execution Orchestrator
(idempotent logs)"]

        SS["State Store
(swaps, legs, audit)"]
        RA["Recipient Address"]
        PA["Provider Adapter"]
        DEX["DEX Adapter"]
        CEX["CEX Adapter"]

        S --> Q --> E
        E --> SS
        E --> RA
        E --> PA
        E --> DEX
        E --> CEX
    end

    R -- "RoutePlan" --> S
```

Figure 1. Control plane vs data plane architecture.

#### Components

#### Control Plane

| Component                | Description                                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------- |
| **API Gateway**          | Entry point for all requests. Authenticates via `x-api-key`.                             |
| **Graph Service**        | Builds snapshots of available liquidity venues and token graphs.                         |
| **Constraints & Policy** | Enforces venue restrictions, size limits, and TTL rules.                                 |
| **Routing Engine**       | Computes optimal routes using k-best path algorithm with scoring. Outputs a `RoutePlan`. |

#### Data Plane

| Component                  | Description                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------- |
| **Swap/Exchange Service**  | Receives the `RoutePlan` and manages swap lifecycle as a state machine.            |
| **Durable Queue**          | Persists swap jobs to ensure reliable, at-least-once delivery to the orchestrator. |
| **Execution Orchestrator** | Executes swap legs idempotently, coordinating across adapters and recording logs.  |
| **State Store**            | Persists swap state, individual legs, and a full audit trail.                      |
| **Recipient Address**      | Resolves and validates the destination address for the swap output.                |
| **Provider Adapter**       | Generic adapter interface for liquidity providers.                                 |
| **DEX Adapter**            | Adapter for decentralized exchange integrations.                                   |
| **CEX Adapter**            | Adapter for centralized exchange integrations.                                     |

***

#### Data Flow

1. A request hits the **API Gateway** and is authenticated.
2. The **Graph Service** provides a live liquidity snapshot; **Constraints & Policy** applies limits.
3. The **Routing Engine** computes the best route and emits a `RoutePlan`.
4. The `RoutePlan` is handed to the **Swap/Exchange Service**, which transitions through states.
5. Jobs are durably enqueued in the **Durable Queue**.
6. The **Execution Orchestrator** picks up jobs and dispatches legs to the appropriate adapter (Provider, DEX, or CEX).
7. All state transitions and results are written to the **State Store** for auditability.