# balena-os/meta-balena architecture

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

- Interactive diagram: https://gitdiagram.com/balena-os/meta-balena
- Repository: https://github.com/balena-os/meta-balena

## Overview

This repository is a set of Yocto layers used to build balenaOS across device types and Yocto releases. The main workflow is a device booting through bootloader logic that selects a root filesystem and launches Linux; the OS then provides connectivity, time synchronization, and device services. The graph also captures documented image configuration, updates, and support features. Edges rely on README statements or the shown U-Boot environment excerpt; other recipe-level wiring was not sampled, so it is not inferred.

Main entry points: [`meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h`](https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h) (Bootloader), [`meta-balena-common/recipes-core/images`](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/images) (OS image), [`meta-balena-common`](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common) (Common recipes), [`meta-balena-scarthgap`](https://github.com/balena-os/meta-balena/tree/master/meta-balena-scarthgap) (Yocto-version layers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_layers["Yocto layers"]
  node_common_layer["Common recipes"]
  node_version_layers["Yocto-version layers"]
  node_image["OS image"]
end

subgraph group_boot["Boot and updates"]
  node_bootloader["Bootloader<br/>[env_resin.h]"]
  node_bootenv["Boot environment<br/>[env_resin.h]"]
  node_crc_check["Kernel CRC check"]
  node_kernel["Linux kernel"]
  node_host_update["Host OS update"]
end

subgraph group_connectivity["Connectivity and time"]
  node_network["Network manager"]
  node_https_time["HTTPS time sync"]
  node_ntp["NTP time service"]
end

subgraph group_device["Device services"]
  node_ssh["SSH service"]
  node_avahi["Avahi discovery"]
end

subgraph group_support["OS support"]
  node_device_registration["Device registration"]
  node_state_reset["State reset"]
  node_persistent_logs["Persistent logs"]
end

node_integrator(("OS integrator"))

node_integrator -->|"configures"| node_common_layer
node_integrator -->|"selects"| node_version_layers
node_common_layer -.->|"provides recipes"| node_image
node_version_layers -.->|"provides recipes"| node_image
node_image -.->|"boots through"| node_bootloader
node_bootloader -->|"uses environment"| node_bootenv
node_bootloader -->|"loads and launches"| node_kernel
node_bootenv -->|"selects root for"| node_kernel
node_network -->|"connectivity gates"| node_https_time
node_https_time -->|"precedes"| node_ntp
node_ssh -->|"hostname advertised via"| node_avahi

click node_common_layer "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common"
click node_version_layers "https://github.com/balena-os/meta-balena/tree/master/meta-balena-scarthgap"
click node_image "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/images"
click node_bootloader "https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h"
click node_bootenv "https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h"
click node_crc_check "https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/files/balena_check_crc32.c"
click node_kernel "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-kernel/linux"
click node_host_update "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-containers/hostapp-update"
click node_network "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/networkmanager"
click node_https_time "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/systemd/timeinit"
click node_ntp "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/chrony"
click node_ssh "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/openssh"
click node_avahi "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/avahi"
click node_device_registration "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/resin-device-register"
click node_state_reset "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/resin-state-reset"
click node_persistent_logs "https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/balena-persistent-logs"

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_common_layer,node_version_layers,node_image toneBlue
class node_bootloader,node_bootenv,node_crc_check,node_kernel,node_host_update toneAmber
class node_network,node_https_time,node_ntp toneMint
class node_ssh,node_avahi toneRose
class node_device_registration,node_state_reset,node_persistent_logs,node_integrator toneIndigo
```

## Components

### Yocto layers

- [Common recipes](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common): `meta-balena-common`
- [Yocto-version layers](https://github.com/balena-os/meta-balena/tree/master/meta-balena-scarthgap): `meta-balena-scarthgap`
- [OS image](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/images): `meta-balena-common/recipes-core/images`

### Boot and updates

- [Bootloader](https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h): `meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h`
- [Boot environment](https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h): `meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h`
- [Kernel CRC check](https://github.com/balena-os/meta-balena/blob/master/meta-balena-common/recipes-bsp/u-boot/files/balena_check_crc32.c): `meta-balena-common/recipes-bsp/u-boot/files/balena_check_crc32.c`
- [Linux kernel](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-kernel/linux): `meta-balena-common/recipes-kernel/linux`
- [Host OS update](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-containers/hostapp-update): `meta-balena-common/recipes-containers/hostapp-update`

### Connectivity and time

- [Network manager](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/networkmanager): `meta-balena-common/recipes-connectivity/networkmanager`
- [HTTPS time sync](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/systemd/timeinit): `meta-balena-common/recipes-core/systemd/timeinit`
- [NTP time service](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-core/chrony): `meta-balena-common/recipes-core/chrony`

### Device services

- [SSH service](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/openssh): `meta-balena-common/recipes-connectivity/openssh`
- [Avahi discovery](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-connectivity/avahi): `meta-balena-common/recipes-connectivity/avahi`

### OS support

- [Device registration](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/resin-device-register): `meta-balena-common/recipes-support/resin-device-register`
- [State reset](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/resin-state-reset): `meta-balena-common/recipes-support/resin-state-reset`
- [Persistent logs](https://github.com/balena-os/meta-balena/tree/master/meta-balena-common/recipes-support/balena-persistent-logs): `meta-balena-common/recipes-support/balena-persistent-logs`

### Other components

- **OS integrator**

## Connections

- OS integrator → Common recipes: configures
- OS integrator → Yocto-version layers: selects
- Common recipes → OS image: provides recipes
- Yocto-version layers → OS image: provides recipes
- OS image → Bootloader: boots through
- Bootloader → Boot environment: uses environment (evidence: `meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h`)
- Bootloader → Linux kernel: loads and launches
- Boot environment → Linux kernel: selects root for (evidence: `meta-balena-common/recipes-bsp/u-boot/patches/env_resin.h`)
- Network manager → HTTPS time sync: connectivity gates
- HTTPS time sync → NTP time service: precedes
- SSH service → Avahi discovery: hostname advertised via
