# 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" %}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enzyme.finance/onyx-protocol/architecture/architecture-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.