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

# Overview

> High-level overview of the CoverFi smart contract ecosystem

The CoverFi smart contract ecosystem provides a decentralized stablecoin loss protection mechanism built on Stellar and Soroban. These contracts have been open-sourced at [CoverFI-space/coverfi-contracts](https://github.com/CoverFI-space/coverfi-contracts.git).

## Architecture Diagram

The following diagram illustrates the interactions between the main components of the CoverFi contract ecosystem:

```mermaid theme={null}
graph TD
    User([User])
    Admin([Protocol Admin])
    Oracle([Oracle Adapter])
    Engine[Protection Engine]
    ProtectedVault[Protected Balance Vault]
    PremiumVault[Premium Vault]
    ReserveVault[Reserve Vault]
    
    User -->|Creates Position| Engine
    User -->|Claims Protection| Engine
    Admin -->|Updates Prices| Oracle
    
    Engine -->|Reads Prices| Oracle
    Engine -->|Moves Principal| ProtectedVault
    Engine -->|Moves Fee| PremiumVault
    Engine -->|Locks/Unlocks Capacity| ReserveVault
    Engine -->|Triggers Payout| ReserveVault
    
    PremiumVault -->|Forwards Yield| ReserveVault
```

## Money and Data Flow

For a user protecting `1000` units with a `1%` fee and a `10%` max payout cap:

1. **Initiation**: The user creates a protection position.
2. **Principal**: The principal amount (`1000` units) moves into the `protected_balance_vault`.
3. **Fee Collection**: The protection fee (`10` units) moves into the `premium_vault`.
4. **Yield Routing**: The `premium_vault` forwards fees to the `reserve_vault`.
5. **Capacity Locking**: The `reserve_vault` locks the maximum payout capacity (`100` units).
6. **Data Storage**: The position is stored as active in the engine's state.

If the oracle price falls below the trigger before expiry, the payout is calculated based on the price loss and is capped by the configured maximum payout basis points.