# shorebirdtech/updater architecture

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

- Interactive diagram: https://gitdiagram.com/shorebirdtech/updater
- Repository: https://github.com/shorebirdtech/updater

## Overview

This repository provides Shorebird’s Flutter code-push runtime, patch-packaging tool, and optional Dart bindings. The principal app workflow enters through the Flutter engine’s C API, initializes the updater, checks for and downloads updates, manages patch state and files, and exposes boot/launch validation. The graph also preserves patch packaging and Dart/web surfaces documented in the README. Internal links follow the SOURCE INDEX; unsampled implementations are represented only where the README establishes their role.

Main entry points: [`library/src/updater.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/updater.rs) (Update Orchestration), [`library/src/cache/updater_state.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/updater_state.rs) (Updater State), [`library/src/config.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/config.rs) (Runtime Config), [`library/src/cache/lifecycle.rs`](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/lifecycle.rs) (Patch Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Updater Runtime"]
  node_updater["Update Orchestration<br/>[updater.rs]"]
  node_config["Runtime Config<br/>[config.rs]"]
  node_yaml["App YAML Config<br/>[yaml.rs]"]
  node_network["Update Networking<br/>[network.rs]"]
  node_events["Patch Events<br/>[events.rs]"]
end

subgraph group_state["Patch State and Storage"]
  node_state[("Updater State<br/>[updater_state.rs]")]
  node_lifecycle["Patch Lifecycle<br/>[lifecycle.rs]"]
  node_disk_io["State File I/O<br/>[disk_io.rs]"]
  node_signing["Patch Verification<br/>[signing.rs]"]
  node_file_errors["File Error Context<br/>[file_errors.rs]"]
end

subgraph group_interfaces["App Interfaces"]
  node_c_engine["Engine C API<br/>[engine.rs]"]
  node_c_file["File Callbacks<br/>[c_file.rs]"]
  node_dart_c["Dart C API<br/>[dart.rs]"]
  node_dart_io["Dart IO Bindings"]
  node_dart_web["Dart Web Bindings"]
  node_dart_facade["Dart Updater API"]
end

subgraph group_tooling["Patch Packaging"]
  node_patch_tool["Patch Packaging Tool<br/>[main.rs]"]
  node_patch_lib["Patch Library<br/>[lib.rs]"]
  node_string_patch["String Patch Tool<br/>[string_patch.rs]"]
end

node_engine(("Flutter Engine"))
node_dart_app(("Flutter App"))
node_server[("Update Server")]
node_patch_cli(("Shorebird CLI"))

node_engine -->|"calls"| node_c_engine
node_c_engine -->|"dispatches"| node_updater
node_c_engine -->|"uses callbacks"| node_c_file
node_dart_app -->|"uses"| node_dart_facade
node_dart_facade -.->|"selects platform"| node_dart_io
node_dart_facade -.->|"selects platform"| node_dart_web
node_dart_io -.->|"calls native API"| node_dart_c
node_dart_web -.->|"communicates updates"| node_server
node_updater -->|"reads config"| node_config
node_updater -->|"requests updates"| node_network
node_updater -->|"manages patches"| node_state
node_updater -.->|"reports events"| node_events
node_config -->|"parses settings"| node_yaml
node_config -->|"configures hooks"| node_network
node_network -->|"sends requests"| node_server
node_state -->|"tracks patches"| node_lifecycle
node_state -.->|"persists state"| node_disk_io
node_state -.->|"verifies patches"| node_signing
node_lifecycle -->|"reads and writes"| node_disk_io
node_lifecycle -->|"uses verification"| node_signing
node_disk_io -->|"adds error context"| node_file_errors
node_patch_cli -->|"runs"| node_patch_tool
node_patch_tool -.->|"packages patches"| node_patch_lib

click node_c_engine "https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/engine.rs"
click node_c_file "https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/c_file.rs"
click node_dart_c "https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/dart.rs"
click node_dart_io "https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater_io.dart"
click node_dart_web "https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater_web.dart"
click node_dart_facade "https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater.dart"
click node_updater "https://github.com/shorebirdtech/updater/blob/main/library/src/updater.rs"
click node_config "https://github.com/shorebirdtech/updater/blob/main/library/src/config.rs"
click node_yaml "https://github.com/shorebirdtech/updater/blob/main/library/src/yaml.rs"
click node_network "https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs"
click node_events "https://github.com/shorebirdtech/updater/blob/main/library/src/events.rs"
click node_state "https://github.com/shorebirdtech/updater/blob/main/library/src/cache/updater_state.rs"
click node_lifecycle "https://github.com/shorebirdtech/updater/blob/main/library/src/cache/lifecycle.rs"
click node_disk_io "https://github.com/shorebirdtech/updater/blob/main/library/src/cache/disk_io.rs"
click node_signing "https://github.com/shorebirdtech/updater/blob/main/library/src/cache/signing.rs"
click node_file_errors "https://github.com/shorebirdtech/updater/blob/main/library/src/file_errors.rs"
click node_patch_tool "https://github.com/shorebirdtech/updater/blob/main/patch/src/main.rs"
click node_patch_lib "https://github.com/shorebirdtech/updater/blob/main/patch/src/lib.rs"
click node_string_patch "https://github.com/shorebirdtech/updater/blob/main/patch/src/bin/string_patch.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_updater,node_config,node_yaml,node_network,node_events toneBlue
class node_state,node_lifecycle,node_disk_io,node_signing,node_file_errors,node_server toneAmber
class node_c_engine,node_c_file,node_dart_c,node_dart_io,node_dart_web,node_dart_facade toneMint
class node_patch_tool,node_patch_lib,node_string_patch toneRose
class node_engine,node_dart_app,node_patch_cli toneIndigo
```

## Components

### Updater Runtime

- [Update Orchestration](https://github.com/shorebirdtech/updater/blob/main/library/src/updater.rs): `library/src/updater.rs`
- [Runtime Config](https://github.com/shorebirdtech/updater/blob/main/library/src/config.rs): `library/src/config.rs`
- [App YAML Config](https://github.com/shorebirdtech/updater/blob/main/library/src/yaml.rs): `library/src/yaml.rs`
- [Update Networking](https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs): `library/src/network.rs`
- [Patch Events](https://github.com/shorebirdtech/updater/blob/main/library/src/events.rs): `library/src/events.rs`

### Patch State and Storage

- [Updater State](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/updater_state.rs): `library/src/cache/updater_state.rs`
- [Patch Lifecycle](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/lifecycle.rs): `library/src/cache/lifecycle.rs`
- [State File I/O](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/disk_io.rs): `library/src/cache/disk_io.rs`
- [Patch Verification](https://github.com/shorebirdtech/updater/blob/main/library/src/cache/signing.rs): `library/src/cache/signing.rs`
- [File Error Context](https://github.com/shorebirdtech/updater/blob/main/library/src/file_errors.rs): `library/src/file_errors.rs`

### App Interfaces

- [Engine C API](https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/engine.rs): `library/src/c_api/engine.rs`
- [File Callbacks](https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/c_file.rs): `library/src/c_api/c_file.rs`
- [Dart C API](https://github.com/shorebirdtech/updater/blob/main/library/src/c_api/dart.rs): `library/src/c_api/dart.rs`
- [Dart IO Bindings](https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater_io.dart): `shorebird_code_push/lib/src/shorebird_updater_io.dart`
- [Dart Web Bindings](https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater_web.dart): `shorebird_code_push/lib/src/shorebird_updater_web.dart`
- [Dart Updater API](https://github.com/shorebirdtech/updater/blob/main/shorebird_code_push/lib/src/shorebird_updater.dart): `shorebird_code_push/lib/src/shorebird_updater.dart`

### Patch Packaging

- [Patch Packaging Tool](https://github.com/shorebirdtech/updater/blob/main/patch/src/main.rs): `patch/src/main.rs`
- [Patch Library](https://github.com/shorebirdtech/updater/blob/main/patch/src/lib.rs): `patch/src/lib.rs`
- [String Patch Tool](https://github.com/shorebirdtech/updater/blob/main/patch/src/bin/string_patch.rs): `patch/src/bin/string_patch.rs`

### Other components

- **Flutter Engine**
- **Flutter App**
- **Update Server**
- **Shorebird CLI**

## Connections

- Flutter Engine → Engine C API: calls (evidence: `library/src/c_api/engine.rs`)
- Engine C API → Update Orchestration: dispatches (evidence: `library/src/c_api/engine.rs`)
- Engine C API → File Callbacks: uses callbacks (evidence: `library/src/c_api/engine.rs`)
- Flutter App → Dart Updater API: uses (evidence: `README.md`)
- Dart Updater API → Dart IO Bindings: selects platform
- Dart Updater API → Dart Web Bindings: selects platform
- Dart IO Bindings → Dart C API: calls native API
- Dart Web Bindings → Update Server: communicates updates
- Update Orchestration → Runtime Config: reads config (evidence: `library/src/updater.rs`)
- Update Orchestration → Update Networking: requests updates (evidence: `library/src/updater.rs`)
- Update Orchestration → Updater State: manages patches (evidence: `library/src/updater.rs`)
- Update Orchestration → Patch Events: reports events (evidence: `library/src/updater.rs`)
- Runtime Config → App YAML Config: parses settings (evidence: `library/src/config.rs`)
- Runtime Config → Update Networking: configures hooks (evidence: `library/src/config.rs`)
- Update Networking → Update Server: sends requests (evidence: `library/src/network.rs`)
- Updater State → Patch Lifecycle: tracks patches (evidence: `library/src/cache/updater_state.rs`)
- Updater State → State File I/O: persists state (evidence: `library/src/cache/updater_state.rs`)
- Updater State → Patch Verification: verifies patches (evidence: `library/src/cache/updater_state.rs`)
- Patch Lifecycle → State File I/O: reads and writes (evidence: `library/src/cache/lifecycle.rs`)
- Patch Lifecycle → Patch Verification: uses verification (evidence: `library/src/cache/lifecycle.rs`)
- State File I/O → File Error Context: adds error context (evidence: `library/src/cache/disk_io.rs`)
- Shorebird CLI → Patch Packaging Tool: runs (evidence: `README.md`)
- Patch Packaging Tool → Patch Library: packages patches
