# Architecture

## System overview

The Fira protocol is organized into a layered architecture where each module has a clear responsibility and well-defined dependencies.

```mermaid
%%{init: {'flowchart': {'curve': 'monotoneY', 'rankSpacing': 60, 'nodeSpacing': 40, 'padding': 24}}}%%
flowchart TB
  subgraph userLayer ["  User Layer  "]
    Router["<b>FiraRouterV4</b><br/>Diamond Proxy"]
  end

  subgraph coreLayer ["  Core Protocol  "]
    LM["<b>LendingMarket</b><br/>Fixed + Variable Rate"]
    Market["<b>FiraMarket</b><br/>BT/FW AMM"]
    YC["<b>YieldContracts</b><br/>BT + CT"]
  end

  subgraph baseLayer ["  Base Layer  "]
    FW["<b>FW</b><br/>Fira Wrapped"]
    Vault["<b>SisuVault</b><br/>ERC-4626 Vault"]
  end

  subgraph supportLayer ["  Support  "]
    LI["<b>LiquidityInjector</b>"]
    Oracles["<b>Oracles</b><br/>TWAP · Solvency"]
    Rehyp["<b>Rehypothecation</b><br/>Module"]
  end

  Router --> LM
  Router --> Market
  Router --> YC
  Market --> YC
  YC --> FW
  FW --> Vault
  LI -.-> LM
  LI -.-> YC
  Oracles -.-> Market
  Rehyp -.-> FW

  linkStyle default stroke-width:2.5px,stroke:#475569
  linkStyle 6,7,8,9 stroke:#7c3aed,stroke-width:2px

  style userLayer fill:#dbeafe,stroke:#2563eb,stroke-width:2px
  style coreLayer fill:#fef3c7,stroke:#d97706,stroke-width:2px
  style baseLayer fill:#d1fae5,stroke:#059669,stroke-width:2px
  style supportLayer fill:#ede9fe,stroke:#7c3aed,stroke-width:2px

  style Router fill:#2563eb,stroke:#1d4ed8,color:#fff,stroke-width:2px
  style LM fill:#d97706,stroke:#b45309,color:#fff,stroke-width:2px
  style Market fill:#d97706,stroke:#b45309,color:#fff,stroke-width:2px
  style YC fill:#d97706,stroke:#b45309,color:#fff,stroke-width:2px
  style FW fill:#059669,stroke:#047857,color:#fff,stroke-width:2px
  style Vault fill:#059669,stroke:#047857,color:#fff,stroke-width:2px
  style Oracles fill:#7c3aed,stroke:#6d28d9,color:#fff,stroke-width:2px
  style LI fill:#7c3aed,stroke:#6d28d9,color:#fff,stroke-width:2px
  style Rehyp fill:#7c3aed,stroke:#6d28d9,color:#fff,stroke-width:2px
```

Solid arrows = primary dependencies. Dashed purple arrows = support modules.

## Module dependency graph

The dependency flow is: **Router → Market + YieldContracts → FW → Underlying Vault**

* The **Router** holds no state of its own (beyond selector mappings). Each action facet reads market and yield contract state, orchestrates token transfers, and calls into the market or CT contract to execute operations.
* The **Market** depends on CT for the BC index (needed for pricing) and on the factory for fee configuration.
* **CT** depends on FW for the exchange rate (to compute the BC index) and on BT for mint/burn gating.
* **FW** tokens wrap external yield sources (ERC-4626 vaults) and expose a standardized deposit/redeem interface.
* The **RehypothecationModule** controls how much of FW's underlying sits idle vs. deployed in the vault.

## Cross-cutting concerns

### Reentrancy

Every external entry point uses `nonReentrant` from `FiraERC20`. The router relies on the market and CT contracts for reentrancy protection — the router itself has no reentrancy guard because it delegates all state-changing calls to contracts that do.

### Access control

| Component         | Owner controls                               |
| ----------------- | -------------------------------------------- |
| Factory           | Market fee configuration                     |
| CT Factory        | Interest fee configuration, treasury address |
| FW                | Pausing, rehypothecation module assignment   |
| Router            | Selector-to-facet mappings                   |
| LiquidityInjector | BT injection and withdrawal                  |

### Upgradability

* **Markets and yield contracts** are **not upgradeable** — deployed via factories and immutable once created.
* The **Router** is pseudo-upgradeable — the owner can point selectors at new facet addresses, effectively upgrading logic without migrating state.
* **FW tokens** use `BoringOwnableUpgradeable` and the `initializer` pattern for proxy-based upgradability.

## Related pages

* [Router Architecture](https://docs.fira.money/developers/architecture/router-architecture) — Diamond proxy pattern details
* [Features](https://docs.fira.money/developers/features) — Individual feature descriptions
* [Protocol Contracts](https://docs.fira.money/developers/protocol-contracts) — Contract-level documentation