# jsonbored/aio-fleet architecture

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

- Interactive diagram: https://gitdiagram.com/jsonbored/aio-fleet
- Repository: https://github.com/jsonbored/aio-fleet

## Overview

AIO Fleet is a Python control plane and CLI for managing a fleet of Unraid app repositories. Its main workflow starts with manifest-driven repository discovery, runs validation and required GitHub checks, then coordinates upstream updates, release readiness, registry verification, and fleet reporting. Separate branches cover catalog synchronization, alerting, cleanup, and local check overlays. The README documents these capabilities; source excerpts and the SOURCE INDEX establish some internal links, but unsampled implementation details are not inferred.

Main entry points: [`src/aio_fleet/cli.py`](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/cli.py) (Fleet CLI), [`src/aio_fleet/upstream.py`](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/upstream.py) (Upstream monitor), [`src/aio_fleet/hooks.py`](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/hooks.py) (Local hooks), [`src/aio_fleet/control_plane.py`](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/control_plane.py) (Control plane)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Fleet control"]
  node_cli["Fleet CLI<br/>[cli.py]"]
  node_manifest["Fleet manifest<br/>[manifest.py]"]
  node_poll["Repository polling<br/>[poll.py]"]
  node_control["Control plane<br/>[control_plane.py]"]
end

subgraph group_quality["Validation and checks"]
  node_checks["Required checks<br/>[checks.py]"]
  node_validators["Repository validators<br/>[validators.py]"]
  node_safety["Change safety<br/>[safety.py]"]
  node_workflow_security["Workflow security"]
  node_app_testing["App test support<br/>[app_testing.py]"]
end

subgraph group_release["Updates and releases"]
  node_upstream["Upstream monitor<br/>[upstream.py]"]
  node_release_plan["Release planning<br/>[release_plan.py]"]
  node_changelog["Changelog rendering<br/>[changelog.py]"]
  node_release_tx["Release execution"]
  node_signing["Commit signing<br/>[signing.py]"]
  node_registry["Registry operations<br/>[registry.py]"]
end

subgraph group_ops["Fleet operations"]
  node_catalog["Catalog sync<br/>[catalog.py]"]
  node_dashboard["Fleet dashboard<br/>[fleet_dashboard.py]"]
  node_report["Fleet reports<br/>[report.py]"]
  node_alerts["Fleet alerts<br/>[alerts.py]"]
  node_cleanup["Repository cleanup<br/>[cleanup.py]"]
  node_hooks["Local hooks<br/>[hooks.py]"]
  node_trunk["Trunk overlay<br/>[trunk_overlay.py]"]
  node_app_manifest["App manifest export<br/>[app_manifest.py]"]
end

subgraph group_integration["External integrations"]
  node_github["GitHub"]
  node_app_repos["App repositories"]
  node_registries[("Docker Hub and GHCR")]
  node_awesome_unraid[("awesome-unraid catalog")]
  node_alert_sinks["Heartbeat and webhooks"]
end

node_operator(("Operator"))

node_operator -->|"runs commands"| node_cli
node_cli -->|"validates and reads"| node_manifest
node_cli -->|"starts polling"| node_poll
node_poll -->|"creates or updates"| node_checks
node_checks -->|"posts check runs"| node_github
node_cli -->|"runs control path"| node_control
node_control -->|"runs repo checks"| node_app_repos
node_cli -->|"validates repositories"| node_validators
node_cli -->|"assesses changes"| node_safety
node_cli -->|"audits workflows"| node_workflow_security
node_cli -->|"supports app tests"| node_app_testing
node_cli -->|"monitors upstream"| node_upstream
node_upstream -->|"updates and opens PRs"| node_app_repos
node_upstream -->|"writes PRs"| node_github
node_cli -->|"plans releases"| node_release_plan
node_release_plan -->|"uses release data"| node_changelog
node_cli -->|"prepares and publishes"| node_release_tx
node_release_tx -->|"checks signatures"| node_signing
node_cli -->|"verifies and publishes"| node_registry
node_registry -->|"checks image tags"| node_registries
node_cli -->|"syncs catalog assets"| node_catalog
node_catalog -->|"stages assets"| node_awesome_unraid
node_cli -->|"updates dashboard"| node_dashboard
node_cli -->|"generates reports"| node_report
node_cli -->|"sends alerts"| node_alerts
node_alerts -->|"sends heartbeat and digests"| node_alert_sinks
node_cli -->|"checks repository drift"| node_cleanup
node_cli -->|"installs hooks"| node_hooks
node_hooks -->|"runs central checks"| node_control
node_hooks -->|"uses overlay"| node_trunk
node_cli -->|"exports app contract"| node_app_manifest
node_manifest -->|"defines fleet metadata"| node_app_repos

click node_cli "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/cli.py"
click node_manifest "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/manifest.py"
click node_poll "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/poll.py"
click node_control "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/control_plane.py"
click node_checks "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/checks.py"
click node_validators "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/validators.py"
click node_safety "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/safety.py"
click node_workflow_security "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/workflow_security.py"
click node_app_testing "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/app_testing.py"
click node_upstream "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/upstream.py"
click node_release_plan "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/release_plan.py"
click node_changelog "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/changelog.py"
click node_release_tx "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/release_transaction.py"
click node_signing "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/signing.py"
click node_registry "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/registry.py"
click node_catalog "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/catalog.py"
click node_dashboard "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/fleet_dashboard.py"
click node_report "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/report.py"
click node_alerts "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/alerts.py"
click node_cleanup "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/cleanup.py"
click node_hooks "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/hooks.py"
click node_trunk "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/trunk_overlay.py"
click node_app_manifest "https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/app_manifest.py"

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_cli,node_manifest,node_poll,node_control toneBlue
class node_checks,node_validators,node_safety,node_workflow_security,node_app_testing toneAmber
class node_upstream,node_release_plan,node_changelog,node_release_tx,node_signing,node_registry toneMint
class node_catalog,node_dashboard,node_report,node_alerts,node_cleanup,node_hooks,node_trunk,node_app_manifest toneRose
class node_github,node_app_repos,node_registries,node_awesome_unraid,node_alert_sinks,node_operator toneIndigo
```

## Components

### Fleet control

- [Fleet CLI](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/cli.py): `src/aio_fleet/cli.py`
- [Fleet manifest](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/manifest.py): `src/aio_fleet/manifest.py`
- [Repository polling](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/poll.py): `src/aio_fleet/poll.py`
- [Control plane](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/control_plane.py): `src/aio_fleet/control_plane.py`

### Validation and checks

- [Required checks](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/checks.py): `src/aio_fleet/checks.py`
- [Repository validators](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/validators.py): `src/aio_fleet/validators.py`
- [Change safety](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/safety.py): `src/aio_fleet/safety.py`
- [Workflow security](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/workflow_security.py): `src/aio_fleet/workflow_security.py`
- [App test support](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/app_testing.py): `src/aio_fleet/app_testing.py`

### Updates and releases

- [Upstream monitor](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/upstream.py): `src/aio_fleet/upstream.py`
- [Release planning](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/release_plan.py): `src/aio_fleet/release_plan.py`
- [Changelog rendering](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/changelog.py): `src/aio_fleet/changelog.py`
- [Release execution](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/release_transaction.py): `src/aio_fleet/release_transaction.py`
- [Commit signing](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/signing.py): `src/aio_fleet/signing.py`
- [Registry operations](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/registry.py): `src/aio_fleet/registry.py`

### Fleet operations

- [Catalog sync](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/catalog.py): `src/aio_fleet/catalog.py`
- [Fleet dashboard](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/fleet_dashboard.py): `src/aio_fleet/fleet_dashboard.py`
- [Fleet reports](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/report.py): `src/aio_fleet/report.py`
- [Fleet alerts](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/alerts.py): `src/aio_fleet/alerts.py`
- [Repository cleanup](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/cleanup.py): `src/aio_fleet/cleanup.py`
- [Local hooks](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/hooks.py): `src/aio_fleet/hooks.py`
- [Trunk overlay](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/trunk_overlay.py): `src/aio_fleet/trunk_overlay.py`
- [App manifest export](https://github.com/jsonbored/aio-fleet/blob/main/src/aio_fleet/app_manifest.py): `src/aio_fleet/app_manifest.py`

### External integrations

- **GitHub**
- **App repositories**
- **Docker Hub and GHCR**
- **awesome-unraid catalog**
- **Heartbeat and webhooks**

### Other components

- **Operator**

## Connections

- Operator → Fleet CLI: runs commands (evidence: `README.md`)
- Fleet CLI → Fleet manifest: validates and reads (evidence: `README.md`)
- Fleet CLI → Repository polling: starts polling (evidence: `README.md`)
- Repository polling → Required checks: creates or updates (evidence: `README.md`)
- Required checks → GitHub: posts check runs (evidence: `src/aio_fleet/checks.py`)
- Fleet CLI → Control plane: runs control path (evidence: `README.md`)
- Control plane → App repositories: runs repo checks (evidence: `README.md`)
- Fleet CLI → Repository validators: validates repositories (evidence: `README.md`)
- Fleet CLI → Change safety: assesses changes (evidence: `README.md`)
- Fleet CLI → Workflow security: audits workflows (evidence: `README.md`)
- Fleet CLI → App test support: supports app tests (evidence: `README.md`)
- Fleet CLI → Upstream monitor: monitors upstream (evidence: `README.md`)
- Upstream monitor → App repositories: updates and opens PRs (evidence: `README.md`)
- Upstream monitor → GitHub: writes PRs (evidence: `src/aio_fleet/upstream.py`)
- Fleet CLI → Release planning: plans releases (evidence: `README.md`)
- Release planning → Changelog rendering: uses release data (evidence: `src/aio_fleet/release_plan.py`)
- Fleet CLI → Release execution: prepares and publishes (evidence: `README.md`)
- Release execution → Commit signing: checks signatures (evidence: `src/aio_fleet/release_transaction.py`)
- Fleet CLI → Registry operations: verifies and publishes (evidence: `README.md`)
- Registry operations → Docker Hub and GHCR: checks image tags (evidence: `README.md`)
- Fleet CLI → Catalog sync: syncs catalog assets (evidence: `README.md`)
- Catalog sync → awesome-unraid catalog: stages assets (evidence: `README.md`)
- Fleet CLI → Fleet dashboard: updates dashboard (evidence: `README.md`)
- Fleet CLI → Fleet reports: generates reports (evidence: `README.md`)
- Fleet CLI → Fleet alerts: sends alerts (evidence: `README.md`)
- Fleet alerts → Heartbeat and webhooks: sends heartbeat and digests (evidence: `README.md`)
- Fleet CLI → Repository cleanup: checks repository drift (evidence: `README.md`)
- Fleet CLI → Local hooks: installs hooks (evidence: `README.md`)
- Local hooks → Control plane: runs central checks (evidence: `src/aio_fleet/hooks.py`)
- Local hooks → Trunk overlay: uses overlay (evidence: `src/aio_fleet/hooks.py`)
- Fleet CLI → App manifest export: exports app contract (evidence: `README.md`)
- Fleet manifest → App repositories: defines fleet metadata (evidence: `README.md`)
