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

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.