> For the complete documentation index, see [llms.txt](https://docs.yifi.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yifi.io/docs/earn/getting-started/architecture-overview.md).

# Architecture overview

The components behind the YiFi Earn API, how data flows through them, and where the custody boundaries sit

YiFi Earn is a data-and-execution layer over EVM DeFi. It reads protocol state, normalizes it into a single model, prices it, and hands partners a signable transaction – while keeping user funds entirely outside its own contracts.

### Components

```mermaid
flowchart LR
    subgraph Client
        APP[Partner app / wallet]
        W[User wallet]
    end

    subgraph YiFi[YiFi Earn]
        API[Core API — Data Gateway]
        IDX[Indexer]
        PR[Pricing]
        EX[Execution routing]
        PF[Portfolio read-model]
    end

    subgraph Chain[EVM chains]
        PROTO[Underlying protocols — Aave, Lido, Morpho, Ethena, ...]
        FS[FeeSplitter contracts]
    end

    APP --> API
    API --> IDX
    API --> PR
    API --> EX
    API --> PF
    IDX --> PROTO
    PF --> IDX
    EX --> PROTO
    EX --> FS
    W --> PROTO
```

**Core API (Data Gateway).** The single entry point. It composes normalized reference data (chains, platforms, categories), tokens and their metrics, unified markets, and the execution and portfolio surfaces. All entities are linked by stable IDs so integrators can compose them freely.

**Indexer.** Protocol state is indexed Subgraphs to collect protocol-specific values that aren't present in standard schemas – like interest-rate-model curve parameters – are read through custom contract-call handlers rather than inferred from indexed events.

**Pricing.** Prices are applied at the edge, so internal calculations stay native-first.

**Execution routing.** Deposit (zap) and withdraw (unzap) transactions are constructed through Portals WarpDrive and LI.FI Composer. This layer builds calldata; it does not custody assets or sign.

**Portfolio read-model.** A read-only projection of positions, performance, and transaction history keyed by wallet address. It reads from indexed on-chain state – including parsing receipt-token transfer/redeem events directly – rather than trusting cached balances.

**FeeSplitter contracts.** A proprietary contract, deployed across eight EVM networks – Ethereum, BNB Chain, Base, HyperEVM, Arbitrum, Polygon, Optimism, and Avalanche – that splits the protocol-level fee on-chain between YiFi and the attributed partner. It holds only accrued fees, never user principal.

### The normalization pipeline

Raw, protocol-shaped data becomes a uniform model in a fixed sequence: indexed from chain (Subgraphs)→ mapped onto normalized entities with stable IDs → priced → served through the Core API. 

The result is that a lending reserve, a staking pool, and a vault all arrive in the same shape, and a partner writes one integration instead of one per protocol.