# Architecture Overview

The Onyx Protocol implements a highly modular architecture designed for creating bespoke tokenized value vaults.

## Contracts Layout

Though modular, all vaults sit within a common core architecture consisting of four types of contracts:

### 1. Shares

`Shares` is the central contract for an Onyx instance. It is an ERC20 tokenized representation of all portfolio holdings and a registry of settings, rules, and roles for the rest of the system.

### 2. Components

Components are specialized contracts that provide modular functionality to individual `Shares` deployments. Each component is:

* Uniquely deployed for a single `Shares` contract
* Focused on a specific domain (fees, valuation, issuance, etc.)
* Replaceable and upgradeable independently
* Can be nested within other components (e.g., a PerformanceFee can be a component of a FeeManager)

### 3. Global settings and factories

`Global` is the top-level, shared contract that contains common settings for Onyx.

e.g., it defines the global "owner" role, which is used primarily for access-control of proxy upgrades

Factories are used to deploy `Shares` and its components.

### 4. Shared Infrastructure

There are also specialized contracts that do not relate to a specific Onyx instance. Such common infrastructural contracts may also be used by Shares and its Components.

e.g., price conversion oracles

## Architecture Diagram

{% @mermaid/diagram content="  graph TB
%% Styling
classDef global fill:#e1f5fe,stroke:#01579b,stroke-width:3px
classDef shares fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef component fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef factory fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
classDef infra fill:#fce4ec,stroke:#880e4f,stroke-width:2px

```
  %% Global Layer
  Global[Global]:::global

  %% Infrastructure
  subgraph Infrastructure[Shared Infrastructure]
      Oracle1[Oracle]:::infra
      Oracle2[Oracle]:::infra
  end

  %% Factories
  subgraph Factories[Factory System]
      SharesFactory[Shares Factory]:::factory
      ComponentFactories[Component Factories]:::factory
  end

  %% Fund Instance
  subgraph Fund1[Vault Instance 1]
      Shares1[Shares]:::shares

      subgraph Components1[Attached Components]
          Val1[Valuation Manager]:::component
          Fee1[Fee Manager]:::component
          Dep1[RFQ Deposit Handler]:::component
          Red1[In-Kind Redeem Handler]:::component

      end
  end

  %% Fund Instance 2
  subgraph Fund2[Vault Instance 2]
      Shares2[Shares]:::shares

      subgraph Components2[Attached Components]
          Val2[Valuation Manager]:::component
          Fee2[Fee Manager]:::component
          Queue2[Deposit/Redeem Queue]:::component
      end
  end

  %% Relationships
  Global --> Factories
  Global --> Infrastructure

  SharesFactory --> Shares1
  SharesFactory --> Shares2

  ComponentFactories --> Components1
  ComponentFactories --> Components2

  Shares1 -.->|manages| Components1
  Shares2 -.->|manages| Components2

  Components1 -.->|may use| Infrastructure
  Components2 -.->|may use| Infrastructure" %}
```