# oxidecomputer/omicron architecture

> Architecture diagram of the GitHub repository oxidecomputer/omicron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oxidecomputer/omicron
- Repository: https://github.com/oxidecomputer/omicron
- Video tour (about a minute): https://gitdiagram.com/oxidecomputer/omicron/video

## Overview

Omicron is a rack-scale control plane: operators and services use its APIs to manage infrastructure, while Nexus coordinates persistent state and work across rack components. Major domains include database-backed inventory, deployment planning, sled-local instance and storage management, and supporting boot, installation, DNS, and management-gateway services. The README describes simulated and production modes; sampled source directly confirms several storage and instance-management behaviors, but not most service-to-service wiring, so uncertain links are omitted.

Main entry points: [`nexus/src/app/sagas/common_storage.rs`](https://github.com/oxidecomputer/omicron/blob/main/nexus/src/app/sagas/common_storage.rs) (Nexus), [`nexus/db-queries/src/db/datastore/local_storage.rs`](https://github.com/oxidecomputer/omicron/blob/main/nexus/db-queries/src/db/datastore/local_storage.rs) (Datastore queries), [`nexus/reconfigurator/rendezvous/src/local_storage_unencrypted_dataset.rs`](https://github.com/oxidecomputer/omicron/blob/main/nexus/reconfigurator/rendezvous/src/local_storage_unencrypted_dataset.rs) (Storage rendezvous), [`nexus/db-model/src/local_storage_dataset_allocation.rs`](https://github.com/oxidecomputer/omicron/blob/main/nexus/db-model/src/local_storage_dataset_allocation.rs) (Database models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_nexus["Nexus<br/>[common_storage.rs]"]
  node_auth["Authentication and authorization<br/>[storage.rs]"]
end

subgraph group_state["State and planning"]
  node_dbqueries["Datastore queries<br/>[local_storage.rs]"]
  node_dbmodel["Database models"]
  node_rendezvous["Storage rendezvous"]
  node_reconfig["Rack reconfiguration"]
end

subgraph group_rack["Rack services"]
  node_sled["Sled agent"]
  node_simstorage["Simulated storage<br/>[storage.rs]"]
  node_bundles["Support bundles<br/>[storage.rs]"]
  node_gateway["Management gateway"]
  node_dns["DNS service<br/>[storage.rs]"]
end

subgraph group_operations["Lifecycle operations"]
  node_bootstore["Boot state<br/>[storage.rs]"]
  node_install["Sled installation<br/>[dispatch.rs]"]
end

node_operator(("Operator or client"))
node_ledger[("Persistent ledger")]
node_crucible["Crucible pantry"]
node_database[("Persistent database")]

node_operator -->|"requests management"| node_nexus
node_nexus -->|"authorizes actions"| node_auth
node_nexus -->|"queries state"| node_dbqueries
node_dbqueries -->|"reads and writes"| node_database
node_dbmodel -->|"models records"| node_dbqueries
node_rendezvous -->|"tombstones datasets"| node_dbqueries
node_nexus -->|"attaches volumes"| node_crucible
node_reconfig -->|"reconciles datasets"| node_rendezvous
node_sled -.->|"uses in simulation"| node_simstorage
node_bootstore -->|"persists state"| node_ledger

click node_nexus "https://github.com/oxidecomputer/omicron/blob/main/nexus/src/app/sagas/common_storage.rs"
click node_auth "https://github.com/oxidecomputer/omicron/blob/main/nexus/auth/src/storage.rs"
click node_dbqueries "https://github.com/oxidecomputer/omicron/blob/main/nexus/db-queries/src/db/datastore/local_storage.rs"
click node_dbmodel "https://github.com/oxidecomputer/omicron/blob/main/nexus/db-model/src/local_storage_dataset_allocation.rs"
click node_rendezvous "https://github.com/oxidecomputer/omicron/blob/main/nexus/reconfigurator/rendezvous/src/local_storage_unencrypted_dataset.rs"
click node_reconfig "https://github.com/oxidecomputer/omicron/tree/main/nexus/reconfigurator"
click node_sled "https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/instance_manager.rs"
click node_simstorage "https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/sim/storage.rs"
click node_bundles "https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/support_bundle/storage.rs"
click node_gateway "https://github.com/oxidecomputer/omicron/blob/main/gateway/src/http_entrypoints.rs"
click node_dns "https://github.com/oxidecomputer/omicron/blob/main/dns-server/src/storage.rs"
click node_bootstore "https://github.com/oxidecomputer/omicron/blob/main/bootstore/src/schemes/v0/storage.rs"
click node_install "https://github.com/oxidecomputer/omicron/blob/main/installinator/src/dispatch.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nexus,node_auth,node_operator toneBlue
class node_dbqueries,node_dbmodel,node_rendezvous,node_reconfig,node_ledger,node_database toneAmber
class node_sled,node_simstorage,node_bundles,node_gateway,node_dns toneMint
class node_bootstore,node_install toneRose
class node_crucible toneIndigo
```

## Components

### Control plane

- [Nexus](https://github.com/oxidecomputer/omicron/blob/main/nexus/src/app/sagas/common_storage.rs): `nexus/src/app/sagas/common_storage.rs`
- [Authentication and authorization](https://github.com/oxidecomputer/omicron/blob/main/nexus/auth/src/storage.rs): `nexus/auth/src/storage.rs`

### State and planning

- [Datastore queries](https://github.com/oxidecomputer/omicron/blob/main/nexus/db-queries/src/db/datastore/local_storage.rs): `nexus/db-queries/src/db/datastore/local_storage.rs`
- [Database models](https://github.com/oxidecomputer/omicron/blob/main/nexus/db-model/src/local_storage_dataset_allocation.rs): `nexus/db-model/src/local_storage_dataset_allocation.rs`
- [Storage rendezvous](https://github.com/oxidecomputer/omicron/blob/main/nexus/reconfigurator/rendezvous/src/local_storage_unencrypted_dataset.rs): `nexus/reconfigurator/rendezvous/src/local_storage_unencrypted_dataset.rs`
- [Rack reconfiguration](https://github.com/oxidecomputer/omicron/tree/main/nexus/reconfigurator): `nexus/reconfigurator`

### Rack services

- [Sled agent](https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/instance_manager.rs): `sled-agent/src/instance_manager.rs`
- [Simulated storage](https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/sim/storage.rs): `sled-agent/src/sim/storage.rs`
- [Support bundles](https://github.com/oxidecomputer/omicron/blob/main/sled-agent/src/support_bundle/storage.rs): `sled-agent/src/support_bundle/storage.rs`
- [Management gateway](https://github.com/oxidecomputer/omicron/blob/main/gateway/src/http_entrypoints.rs): `gateway/src/http_entrypoints.rs`
- [DNS service](https://github.com/oxidecomputer/omicron/blob/main/dns-server/src/storage.rs): `dns-server/src/storage.rs`

### Lifecycle operations

- [Boot state](https://github.com/oxidecomputer/omicron/blob/main/bootstore/src/schemes/v0/storage.rs): `bootstore/src/schemes/v0/storage.rs`
- [Sled installation](https://github.com/oxidecomputer/omicron/blob/main/installinator/src/dispatch.rs): `installinator/src/dispatch.rs`

### Other components

- **Operator or client**
- **Persistent ledger**
- **Crucible pantry**
- **Persistent database**

## Connections

- Operator or client → Nexus: requests management
- Nexus → Authentication and authorization: authorizes actions
- Nexus → Datastore queries: queries state
- Datastore queries → Persistent database: reads and writes
- Database models → Datastore queries: models records
- Storage rendezvous → Datastore queries: tombstones datasets
- Nexus → Crucible pantry: attaches volumes
- Rack reconfiguration → Storage rendezvous: reconciles datasets
- Sled agent → Simulated storage: uses in simulation
- Boot state → Persistent ledger: persists state