# pbatard/uefi-shell architecture

> Architecture diagram of the GitHub repository pbatard/uefi-shell, 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/pbatard/uefi-shell
- Repository: https://github.com/pbatard/uefi-shell

## Overview

1. This repository is primarily a release-and-build wrapper, not a large application codebase. Its purpose is to publish pre-built UEFI Shell binaries and bootable ISO images derived from upstream EDK2.

2. The main source boundary is the `edk2` git submodule. That submodule points at the official Tianocore EDK2 repository and is the actual upstream source used to produce the shell binaries. The local repo itself mostly pins that dependency and automates packaging.

3. The second major subsystem is GitHub Actions, specifically `.github/workflows/linux_gcc_edk2.yml`. This is the build pipeline that checks out the repo plus submodules, builds the UEFI Shell on Linux with GCC, computes hashes, and publishes artifacts.

4. The build output boundary is release artifacts, not a deployed service. The pipeline produces individual `.efi` binaries for supported UEFI architectures and bootable `.iso` images intended for USB or optical media creation. These artifacts are what end users consume.

5. There is an explicit packaging step for boot media convenience: the ISO is the primary distribution format, while the individual EFI binaries are a secondary output for manual FAT-partition boot media use. So the data flow is: upstream EDK2 source -> CI build -> signed/hashed binary outputs -> GitHub Releases.

6. The repository also includes an optional bundled tool, Mosby, starting with release 24H2. It is packaged into the ISO as an extra command available from the UEFI Shell, but it is not part of the shell itself and does not change the core shell build path.

7. Security and trust validation are a prominent architectural concern. The README describes a reproducible-trust workflow: verify the Git commit used by the build, verify the `edk2` submodule commit, inspect the workflow definition, and compare logged SHA-256 values against the downloaded release files.

8. GitHub Releases is the distribution endpoint. The repo’s published binaries are expected to be identical to the CI-produced outputs, and the build log SHA-256 values are the integrity link between source, CI, and downloadable artifacts.

9. The runtime environment is UEFI firmware, not a traditional operating-system process. End users boot the ISO or FAT media on hardware whose firmware supports the architecture of the published shell build. Secure Boot is intentionally excluded because the external shell is not Microsoft-signed.

10. In architecture-diagram terms, the important nodes are: public upstream EDK2, this repository as a pinned integration/build wrapper, GitHub Actions as the automated build-and-verify system, and GitHub Releases as the artifact store. The arrows are source pinning, build/packaging, checksum verification, and release publication.

Main entry points: [`edk2`](https://github.com/pbatard/uefi-shell/tree/main/edk2) (EDK2), [`.github/workflows/linux_gcc_edk2.yml`](https://github.com/pbatard/uefi-shell/blob/main/.github/workflows/linux_gcc_edk2.yml) (Linux build), [`.gitmodules`](https://github.com/pbatard/uefi-shell/blob/main/.gitmodules) (Pinning), [`README.md`](https://github.com/pbatard/uefi-shell/blob/main/README.md) (Trust guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source"]
  node_repo["uefi-shell<br/>build wrapper"]
  node_edk2["EDK2<br/>upstream source"]
  node_gitmodules["Pinning<br/>submodule config<br/>[.gitmodules]"]
  node_readme["Trust guide<br/>docs<br/>[README.md]"]
end

subgraph group_ci["CI Build"]
  node_workflow["Linux build<br/>github actions<br/>[linux_gcc_edk2.yml]"]
  node_checkout["Checkout<br/>ci step"]
  node_build["Shell build<br/>edk2 build"]
  node_mosby["Mosby<br/>optional tool"]
  node_package["ISO pack<br/>packaging"]
  node_hash["SHA-256<br/>integrity check"]
  node_publish["Release publish<br/>release step"]
end

subgraph group_dist["Distribution"]
  node_releases[("GitHub Releases<br/>artifact store")]
  node_iso["Bootable ISO<br/>release artifact"]
  node_efi["EFI binaries<br/>release artifact"]
end

subgraph group_consumer["Boot Target"]
  node_firmware(("UEFI firmware<br/>runtime target"))
  node_secureboot(("No Secure Boot<br/>runtime constraint"))
end

node_repo -->|"pins"| node_edk2
node_gitmodules -->|"references"| node_edk2
node_readme -->|"describes"| node_workflow
node_workflow -->|"starts"| node_checkout
node_checkout -->|"fetches"| node_edk2
node_checkout -->|"feeds"| node_build
node_build -.->|"optionally includes"| node_mosby
node_build -->|"outputs"| node_package
node_mosby -.->|"bundled into"| node_package
node_package -->|"creates"| node_iso
node_package -->|"creates"| node_efi
node_iso -->|"verified by"| node_hash
node_efi -->|"verified by"| node_hash
node_hash -->|"attests"| node_publish
node_publish -->|"publishes to"| node_releases
node_releases -->|"distributes"| node_iso
node_releases -->|"distributes"| node_efi
node_iso -->|"boots on"| node_firmware
node_efi -->|"boots on"| node_firmware
node_firmware -.->|"excludes"| node_secureboot

click node_edk2 "https://github.com/pbatard/uefi-shell/tree/main/edk2"
click node_gitmodules "https://github.com/pbatard/uefi-shell/blob/main/.gitmodules"
click node_readme "https://github.com/pbatard/uefi-shell/blob/main/README.md"
click node_workflow "https://github.com/pbatard/uefi-shell/blob/main/.github/workflows/linux_gcc_edk2.yml"

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_repo,node_edk2,node_gitmodules,node_readme toneBlue
class node_workflow,node_checkout,node_build,node_mosby,node_package,node_hash,node_publish toneAmber
class node_releases,node_iso,node_efi toneMint
class node_firmware,node_secureboot toneRose
```

## Components

### Source

Upstream EDK2 source and local pinning

- **uefi-shell**: build wrapper · This repository pins upstream EDK2 and automates shell build and release packaging.
- [EDK2](https://github.com/pbatard/uefi-shell/tree/main/edk2): upstream source · Official Tianocore EDK2 submodule used as the build source boundary. · `edk2`
- [Pinning](https://github.com/pbatard/uefi-shell/blob/main/.gitmodules): submodule config · Declares the EDK2 submodule reference used by the repository. · `.gitmodules`
- [Trust guide](https://github.com/pbatard/uefi-shell/blob/main/README.md): docs · Documents verification, reproducibility, and release integrity checks. · `README.md`

### CI Build

GitHub Actions build, packaging, and integrity checks

- [Linux build](https://github.com/pbatard/uefi-shell/blob/main/.github/workflows/linux_gcc_edk2.yml): github actions · Primary CI workflow that checks out sources, builds, hashes, and publishes artifacts. · `.github/workflows/linux_gcc_edk2.yml`
- **Checkout**: ci step · Fetches this repo and the pinned EDK2 submodule.
- **Shell build**: edk2 build · Compiles the UEFI Shell for supported architectures on Linux with GCC.
- **Mosby**: optional tool · Bundled extra command included in ISO releases starting with 24H2.
- **ISO pack**: packaging · Assembles bootable ISO images and secondary EFI binaries for manual boot media use.
- **SHA-256**: integrity check · Computes and logs hashes used to verify CI-produced artifacts against downloads.
- **Release publish**: release step · Pushes the built artifacts to the repository release channel.

### Distribution

Release artifacts published for users

- **GitHub Releases**: artifact store · Distribution endpoint for downloadable release binaries and images.
- **Bootable ISO**: release artifact · Primary distribution format for booting UEFI Shell media.
- **EFI binaries**: release artifact · Secondary per-architecture shell binaries for FAT-partition boot media.

### Boot Target

UEFI firmware environment that consumes the artifacts

- **UEFI firmware**: runtime target · Target environment that boots the ISO or EFI media on compatible hardware.
- **No Secure Boot**: runtime constraint · External shell builds are intentionally not Microsoft-signed.

## Connections

- uefi-shell → EDK2: pins · The repository integrates the upstream EDK2 source as a submodule.
- Pinning → EDK2: references · Submodule metadata binds the local repo to the upstream commit.
- Trust guide → Linux build: describes · The README documents the build and verification workflow.
- Linux build → Checkout: starts · CI begins by checking out the repository and submodules.
- Checkout → EDK2: fetches · The build pipeline pulls the upstream source snapshot.
- Checkout → Shell build: feeds · Checked-out sources are passed into the EDK2 build stage.
- Shell build → Mosby: optionally includes · Some releases bundle Mosby as an extra ISO command.
- Shell build → ISO pack: outputs · Compiled shell binaries move into the packaging stage.
- Mosby → ISO pack: bundled into · The optional tool is inserted into the ISO package when enabled.
- ISO pack → Bootable ISO: creates · Packaging produces the bootable ISO image.
- ISO pack → EFI binaries: creates · Packaging also emits individual EFI binaries.
- Bootable ISO → SHA-256: verified by · The ISO is hashed for integrity verification.
- EFI binaries → SHA-256: verified by · The EFI binaries are hashed for integrity verification.
- SHA-256 → Release publish: attests · Logged hashes support trust in the published artifacts.
- Release publish → GitHub Releases: publishes to · CI uploads the generated artifacts to GitHub Releases.
- GitHub Releases → Bootable ISO: distributes · Users download the ISO from releases.
- GitHub Releases → EFI binaries: distributes · Users download the EFI binaries from releases.
- Bootable ISO → UEFI firmware: boots on · The ISO is intended to boot on compatible UEFI hardware.
- EFI binaries → UEFI firmware: boots on · EFI binaries are used on FAT-based boot media for UEFI firmware.
- UEFI firmware → No Secure Boot: excludes · The external shell is not Microsoft-signed, so Secure Boot is not part of the supported path.