# openbmc/docs architecture

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

- Interactive diagram: https://gitdiagram.com/openbmc/docs
- Repository: https://github.com/openbmc/docs

## Overview

1. **What this repository is**
   - This is the **OpenBMC documentation repository**, not the firmware implementation itself.
   - Its job is to define the **architecture, design decisions, usage patterns, and development process** for the OpenBMC ecosystem.
   - The actual runtime components live in separate component repositories and Yocto layers; this repo explains how they fit together.

2. **Top-level structure as an architecture map**
   - `architecture/` contains the most stable system-level architecture docs.
   - `designs/` contains feature and subsystem design proposals, often more detailed and narrower than the architecture docs.
   - `development/`, `testing/`, `release/`, and `process/` describe the engineering workflow around the platform.
   - `security/`, `style/`, and `tof/` are governance and policy boundaries rather than product features.
   - `userguide/` and cheatsheets provide operator-facing usage guidance.

3. **Core system architecture themes**
   - The docs center on OpenBMC as a **BMC firmware stack for out-of-band server management**.
   - Major architecture areas documented here include:
     - **management interfaces** such as Redfish, REST, and IPMI,
     - **sensors and inventory**,
     - **code/firmware update**,
     - **event and error logging**,
     - **user and authorization management**,
     - **power, LED, and host control**,
     - and **platform integration** through D-Bus, systemd, and object mapping.

4. **The interface boundary to the outside world**
   - OpenBMC’s main external consumers are **operators, automation tools, and the managed host platform**.
   - The repository documents multiple access protocols:
     - **Redfish** as the modern API surface,
     - **REST** as a general HTTP API,
     - **IPMI** as the legacy management interface,
     - plus protocol-specific areas like **PLDM**, **MCTP**, and **USB/network-based update paths**.
   - These docs establish where each protocol fits, and which features are exposed through which interface.

5. **Data and control flow around hardware management**
   - A key architectural pattern is that hardware state is discovered and normalized inside BMC services, then surfaced through management interfaces.
   - The docs for **sensors**, **object mapper**, **entity/inventory management**, and **physical topology** imply a flow from hardware signals and platform description into a centralized representation, then outward to Redfish/IPMI.
   - This is the backbone for inventory, health, telemetry, and platform status reporting.

6. **Firmware and code update subsystem**
   - `architecture/code-update/` and several `designs/code-update*` docs describe one of the most important workflows in the system: **updating the BMC itself and, in some cases, host firmware**.
   - The architecture boundary here includes:
     - image layout and flash storage,
     - update transport mechanisms,
     - staging/activation behavior,
     - and host-vs-BMC update separation.
   - Related designs cover update paths over **Redfish**, **blobs**, **USB**, and platform-specific storage layouts.

7. **Logging, events, and diagnostics**
   - Several docs cover **event logging, SEL/error handling, dump management, and telemetry**.
   - This indicates a pipeline where platform faults and operational events are captured locally, normalized, and then exposed to external consumers.
   - There is also explicit attention to **Redfish eventing/logging**, showing that observability is part of the management-plane architecture, not an afterthought.

8. **Security, identity, and authorization**
   - `security/` and design docs on **user management**, **TLS**, **authorization**, **certificate handling**, and **attestation** define the trust boundary for the management plane.
   - The architecture distinguishes between:
     - local BMC authentication and user lifecycle,
     - transport security for API access,
     - and broader platform trust features such as certificates, revocation, and attestation.
   - This is important for diagramming because security is layered across the API surfaces rather than isolated in one component.

9. **Platform integration and service composition**
   - OpenBMC is documented as a **service-oriented Linux userspace** built on top of system services and D-Bus-style integration.
   - The `architecture/openbmc-systemd.md`, `architecture/object-mapper.md`, and related docs suggest that system services are coordinated through standard Linux mechanisms rather than a monolithic application.
   - The repo also references **Yocto** and Linux kernel development, which frames the platform as a firmware distribution assembled from multiple layers.

10. **Host/BMC interaction model**
   - Many design docs focus on interactions between the BMC and the managed host: power recovery, boot progress, postcodes, virtual media, console access, NMI, and reset behavior.
   - This shows a two-plane architecture:
     - the **BMC management plane** running independently,
     - and the **host control/monitoring plane** that the BMC influences or observes.
   - These flows are central to understanding OpenBMC’s purpose in a system diagram.

11. **Hardware-specific and vendor-specific extensions**
   - The `designs/oem/` area and multiple platform-oriented docs show that OpenBMC is intentionally **extensible per board or vendor**.
   - This repository therefore documents the **common architecture** plus places where OEM-specific behavior plugs in without redefining the core stack.
   - That makes the repo useful as the shared contract between upstream architecture and downstream platform adaptations.

12. **Engineering workflow and project governance**
   - `development/`, `testing/`, `process/`, `release/`, and `maintainer`/`membership` docs describe how the project is built, reviewed, tested, and released.
   - The collaboration model includes mailing lists, Gerrit-based development, and documented contribution rules.
   - These are not runtime subsystems, but they define the organizational boundary around how the architecture evolves.

13. **How to read this repo for an architecture diagram**
   - Treat the repo as a **documentation hub** for a layered firmware platform:
     - hardware and platform description at the bottom,
     - Linux/system services and D-Bus coordination in the middle,
     - management protocols and security at the boundary,
     - and operator/automation consumers at the top.
   - The most important diagram anchors are: **inventory/sensors**, **logging/events**, **code update**, **host control**, and **external management APIs**.

Main entry points: [`architecture/interface-overview.md`](https://github.com/openbmc/docs/blob/master/architecture/interface-overview.md) (Architecture), [`README.md`](https://github.com/openbmc/docs/blob/master/README.md) (Docs home), [`development/README.md`](https://github.com/openbmc/docs/blob/master/development/README.md) (Development), [`designs/physical-topology.md`](https://github.com/openbmc/docs/blob/master/designs/physical-topology.md) (Topology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repository"]
  node_readme["Docs home<br/>entry<br/>[README.md]"]
end

subgraph group_architecture["Architecture"]
  node_arch_overview["Architecture<br/>doc hub"]
  node_arch_systemd["Systemd<br/>service model<br/>[openbmc-systemd.md]"]
  node_arch_mapper["Object mapper<br/>service registry<br/>[object-mapper.md]"]
  node_arch_sensors["Sensors<br/>telemetry model"]
  node_arch_update["Code update<br/>update system<br/>[code-update.md]"]
  node_arch_identity["User mgmt<br/>auth model<br/>[user-management.md]"]
  node_arch_ipmi["IPMI<br/>legacy API"]
  node_arch_redfish_log["Redfish logging<br/>api integration"]
  node_arch_led["LEDs<br/>control model"]
end

subgraph group_designs["Designs"]
  node_design_topology["Topology<br/>platform model"]
  node_design_entities["Inventory<br/>[entity-manager.md]"]
  node_design_events["Events<br/>logging pipeline<br/>[event-logging.md]"]
  node_design_dumps["Dumps<br/>diagnostics<br/>[dump-manager.md]"]
  node_design_boot["Boot flow<br/>state machine<br/>[boot-progress.md]"]
  node_design_power["Power<br/>host control<br/>[power-recovery.md]"]
  node_design_virtual["Virtual media<br/>host interface<br/>[virtual-media.md]"]
  node_design_pldm["PLDM<br/>protocol stack<br/>[pldm-stack.md]"]
  node_design_redfish_events["EventService<br/>redfish feature"]
  node_design_tls["TLS auth<br/>security design"]
end

subgraph group_workflow["Workflow"]
  node_workflow_dev["Development<br/>workflow<br/>[README.md]"]
  node_workflow_test["Testing<br/>validation<br/>[local-ci-build.md]"]
  node_workflow_release["Release metrics<br/>release ops"]
  node_workflow_maint["Maintainership<br/>process"]
end

subgraph group_governance["Governance"]
  node_gov_style["Style<br/>coding standard"]
  node_gov_membership["Membership<br/>community policy"]
end

subgraph group_security["Security"]
  node_sec_policy["Security<br/>policy<br/>[SECURITY.md]"]
  node_sec_tls["TLS config<br/>hardening"]
  node_sec_net["Network sec<br/>hardening"]
end

node_readme -->|"documents"| node_arch_overview
node_readme -->|"covers"| node_design_topology
node_readme -->|"explains"| node_workflow_dev
node_readme -->|"sets"| node_sec_policy
node_arch_overview -->|"runs on"| node_arch_systemd
node_arch_overview -->|"coordinates"| node_arch_mapper
node_arch_overview -->|"surfaces"| node_arch_sensors
node_arch_overview -->|"updates"| node_arch_update
node_arch_overview -->|"secures"| node_arch_identity
node_arch_overview -->|"exposes"| node_arch_ipmi
node_arch_overview -->|"exposes"| node_arch_redfish_log
node_arch_overview -->|"controls"| node_arch_led
node_design_topology -->|"feeds"| node_design_entities
node_design_topology -->|"informs"| node_design_power
node_design_entities -->|"publishes"| node_arch_mapper
node_design_events -->|"surfaces"| node_arch_redfish_log
node_design_dumps -->|"extends"| node_design_events
node_design_boot -->|"depends on"| node_design_power
node_design_virtual -->|"fronts"| node_arch_overview
node_design_pldm -->|"integrates"| node_arch_overview
node_design_redfish_events -->|"extends"| node_arch_redfish_log
node_design_tls -->|"implements"| node_sec_policy
node_workflow_dev -->|"pairs with"| node_workflow_test
node_workflow_dev -->|"governed by"| node_workflow_maint
node_workflow_release -->|"requires"| node_workflow_test
node_gov_style -->|"guides"| node_workflow_dev
node_gov_membership -->|"supports"| node_workflow_maint
node_sec_tls -->|"complements"| node_sec_net
node_sec_policy -->|"covers"| node_design_tls

click node_readme "https://github.com/openbmc/docs/blob/master/README.md"
click node_arch_overview "https://github.com/openbmc/docs/blob/master/architecture/interface-overview.md"
click node_arch_systemd "https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md"
click node_arch_mapper "https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md"
click node_arch_sensors "https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md"
click node_arch_update "https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md"
click node_arch_identity "https://github.com/openbmc/docs/blob/master/architecture/user-management.md"
click node_arch_ipmi "https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md"
click node_arch_redfish_log "https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md"
click node_arch_led "https://github.com/openbmc/docs/blob/master/architecture/LED-architecture.md"
click node_design_topology "https://github.com/openbmc/docs/blob/master/designs/physical-topology.md"
click node_design_entities "https://github.com/openbmc/docs/blob/master/designs/entity-manager.md"
click node_design_events "https://github.com/openbmc/docs/blob/master/designs/event-logging.md"
click node_design_dumps "https://github.com/openbmc/docs/blob/master/designs/dump-manager.md"
click node_design_boot "https://github.com/openbmc/docs/blob/master/designs/boot-progress.md"
click node_design_power "https://github.com/openbmc/docs/blob/master/designs/power-recovery.md"
click node_design_virtual "https://github.com/openbmc/docs/blob/master/designs/virtual-media.md"
click node_design_pldm "https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md"
click node_design_redfish_events "https://github.com/openbmc/docs/blob/master/designs/redfish-eventservice.md"
click node_design_tls "https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md"
click node_workflow_dev "https://github.com/openbmc/docs/blob/master/development/README.md"
click node_workflow_test "https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md"
click node_workflow_release "https://github.com/openbmc/docs/tree/master/release/metrics/2022-12"
click node_workflow_maint "https://github.com/openbmc/docs/blob/master/process/subproject-maintainership.md"
click node_gov_style "https://github.com/openbmc/docs/blob/master/cpp-style-and-conventions.md"
click node_gov_membership "https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md"
click node_sec_policy "https://github.com/openbmc/docs/blob/master/SECURITY.md"
click node_sec_tls "https://github.com/openbmc/docs/blob/master/security/TLS-configuration.md"
click node_sec_net "https://github.com/openbmc/docs/blob/master/security/network-security-considerations.md"

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_readme toneBlue
class node_arch_overview,node_arch_systemd,node_arch_mapper,node_arch_sensors,node_arch_update,node_arch_identity,node_arch_ipmi,node_arch_redfish_log,node_arch_led toneAmber
class node_design_topology,node_design_entities,node_design_events,node_design_dumps,node_design_boot,node_design_power,node_design_virtual,node_design_pldm,node_design_redfish_events,node_design_tls toneMint
class node_workflow_dev,node_workflow_test,node_workflow_release,node_workflow_maint toneRose
class node_gov_style,node_gov_membership toneIndigo
class node_sec_policy,node_sec_tls,node_sec_net toneTeal
```

## Components

### Repository

Top-level entry and overview for the documentation repo.

- [Docs home](https://github.com/openbmc/docs/blob/master/README.md): entry · Repository overview and navigation starting point. · `README.md`

### Architecture

Stable system-level architecture and platform boundaries.

- [Architecture](https://github.com/openbmc/docs/blob/master/architecture/interface-overview.md): doc hub · High-level OpenBMC architecture and interface boundaries. · `architecture/interface-overview.md`
- [Systemd](https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md): service model · How OpenBMC services are composed and coordinated on Linux. · `architecture/openbmc-systemd.md`
- [Object mapper](https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md): service registry · Central D-Bus object discovery and lookup boundary. · `architecture/object-mapper.md`
- [Sensors](https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md): telemetry model · Hardware state, sensor normalization, and reporting architecture. · `architecture/sensor-architecture.md`
- [Code update](https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md): update system · BMC and host firmware update architecture and activation flow. · `architecture/code-update/code-update.md`
- [User mgmt](https://github.com/openbmc/docs/blob/master/architecture/user-management.md): auth model · BMC user accounts, roles, and authorization boundaries. · `architecture/user-management.md`
- [IPMI](https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md): legacy API · Legacy management interface architecture and scope. · `architecture/ipmi-architecture.md`
- [Redfish logging](https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md): api integration · Logging and event exposure through the Redfish boundary. · `architecture/redfish-logging-in-bmcweb.md`
- [LEDs](https://github.com/openbmc/docs/blob/master/architecture/LED-architecture.md): control model · System LED policy and control architecture. · `architecture/LED-architecture.md`

### Designs

Feature, subsystem, and OEM design proposals.

- [Topology](https://github.com/openbmc/docs/blob/master/designs/physical-topology.md): platform model · Physical topology and platform description used by downstream services. · `designs/physical-topology.md`
- [Inventory](https://github.com/openbmc/docs/blob/master/designs/entity-manager.md): inventory model · Entity manager and hardware inventory discovery patterns. · `designs/entity-manager.md`
- [Events](https://github.com/openbmc/docs/blob/master/designs/event-logging.md): logging pipeline · Event logging, SEL handling, and diagnostic flow. · `designs/event-logging.md`
- [Dumps](https://github.com/openbmc/docs/blob/master/designs/dump-manager.md): diagnostics · Crash and diagnostic dump collection and exposure. · `designs/dump-manager.md`
- [Boot flow](https://github.com/openbmc/docs/blob/master/designs/boot-progress.md): state machine · Boot progress, readiness, and host-visible startup state. · `designs/boot-progress.md`
- [Power](https://github.com/openbmc/docs/blob/master/designs/power-recovery.md): host control · Power recovery and reset behavior between BMC and host. · `designs/power-recovery.md`
- [Virtual media](https://github.com/openbmc/docs/blob/master/designs/virtual-media.md): host interface · Remote media and host access through the BMC. · `designs/virtual-media.md`
- [PLDM](https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md): protocol stack · PLDM stack and related protocol integration. · `designs/pldm-stack.md`
- [EventService](https://github.com/openbmc/docs/blob/master/designs/redfish-eventservice.md): redfish feature · Redfish event delivery and subscription model. · `designs/redfish-eventservice.md`
- [TLS auth](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md): security design · Transport security and authenticated access for management APIs. · `designs/redfish-tls-user-authentication.md`

### Workflow

Development, testing, release, and contribution process.

- [Development](https://github.com/openbmc/docs/blob/master/development/README.md): workflow · Contributor setup, coding, and development workflow. · `development/README.md`
- [Testing](https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md): validation · Local and CI test practices for the platform. · `testing/local-ci-build.md`
- [Release metrics](https://github.com/openbmc/docs/tree/master/release/metrics/2022-12): release ops · Release tracking and operational metrics over time. · `release/metrics/2022-12`
- [Maintainership](https://github.com/openbmc/docs/blob/master/process/subproject-maintainership.md): process · Subproject ownership and governance process. · `process/subproject-maintainership.md`

### Governance

Policy, style, and membership documents.

- [Style](https://github.com/openbmc/docs/blob/master/cpp-style-and-conventions.md): coding standard · Language and formatting conventions for the project. · `cpp-style-and-conventions.md`
- [Membership](https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md): community policy · Project membership, voting, and community rules. · `tof/membership-and-voting.md`

### Security

Security-specific guidance and response process.

- [Security](https://github.com/openbmc/docs/blob/master/SECURITY.md): policy · Security response and vulnerability reporting policy. · `SECURITY.md`
- [TLS config](https://github.com/openbmc/docs/blob/master/security/TLS-configuration.md): hardening · TLS configuration guidance for secure transport. · `security/TLS-configuration.md`
- [Network sec](https://github.com/openbmc/docs/blob/master/security/network-security-considerations.md): hardening · Network-facing security considerations for the management plane. · `security/network-security-considerations.md`

## Connections

- Docs home → Architecture: documents · Repository home points into the architecture map.
- Docs home → Topology: covers · The repo also contains detailed subsystem design docs.
- Docs home → Development: explains · Contributor workflow and development practices.
- Docs home → Security: sets · Security reporting and response boundary.
- Architecture → Systemd: runs on · OpenBMC is framed as coordinated Linux services.
- Architecture → Object mapper: coordinates · D-Bus object discovery is a central integration point.
- Architecture → Sensors: surfaces · Hardware state and telemetry are normalized for consumers.
- Architecture → Code update: updates · Firmware update is a core management workflow.
- Architecture → User mgmt: secures · User and authorization management bounds API access.
- Architecture → IPMI: exposes · Legacy management access is documented as a boundary.
- Architecture → Redfish logging: exposes · Redfish is the modern management interface surface.
- Architecture → LEDs: controls · LED behavior is part of platform management.
- Topology → Inventory: feeds · Topology and platform description support inventory discovery.
- Topology → Power: informs · Platform topology shapes host power and recovery flows.
- Inventory → Object mapper: publishes · Inventory is represented through the object mapping layer.
- Events → Redfish logging: surfaces · Events and logs are exposed through management APIs.
- Dumps → Events: extends · Diagnostics complement the event and logging pipeline.
- Boot flow → Power: depends on · Boot and readiness state are tied to host power control.
- Virtual media → Architecture: fronts · Remote media is one of the external management capabilities.
- PLDM → Architecture: integrates · PLDM is part of the protocol landscape around OpenBMC.
- EventService → Redfish logging: extends · Redfish eventing is part of the API-facing observability path.
- TLS auth → Security: implements · Transport authentication is a concrete security control.
- Development → Testing: pairs with · Development flows into local and CI validation.
- Development → Maintainership: governed by · Contribution and review are shaped by maintainership.
- Release metrics → Testing: requires · Release tracking depends on validated builds and test results.
- Style → Development: guides · Style rules shape implementation work.
- Membership → Maintainership: supports · Membership rules underpin subproject governance.
- TLS config → Network sec: complements · Transport security and network guidance are paired controls.
- Security → TLS auth: covers · Policy documents the security requirements for management access.