# bitxeno/atvloadly architecture

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

- Interactive diagram: https://gitdiagram.com/bitxeno/atvloadly
- Repository: https://github.com/bitxeno/atvloadly

## Overview

atvloadly is a web service for sideloading and refreshing apps on Apple TV. The main workflow is to discover and pair a TV, choose an IPA or tracked source, install it using an Apple ID or external signing identity, and later refresh or update it. The map also includes device discovery, source tracking, certificate management, MCP, notifications, and screenshots. Edges use the sampled source index or README as evidence; several implementations were not sampled, so their internal connections are omitted.

Main entry points: [`web/router.go`](https://github.com/bitxeno/atvloadly/blob/master/web/router.go) (HTTP API), [`internal/service/external_install.go`](https://github.com/bitxeno/atvloadly/blob/master/internal/service/external_install.go) (Install workflow), [`internal/service/app_source.go`](https://github.com/bitxeno/atvloadly/blob/master/internal/service/app_source.go) (Source tracking), [`internal/task/task.go`](https://github.com/bitxeno/atvloadly/blob/master/internal/task/task.go) (Refresh scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User access"]
  node_webui["Web interface<br/>[App.vue]"]
  node_api["HTTP API<br/>[router.go]"]
  node_mcp["MCP tools<br/>[install.go]"]
  node_mcp_server["MCP endpoint<br/>[server.go]"]
end

subgraph group_devices["Apple TV devices"]
  node_discovery["Device discovery"]
  node_device_manager["Device registry<br/>[device_manager.go]"]
  node_pairing["Device pairing<br/>[pair_manager.go]"]
  node_install_engine["Sideload engine<br/>[install_manager.go]"]
  node_screenshot["Screenshots"]
end

subgraph group_apps["Apps and signing"]
  node_source_tracking["Source tracking<br/>[app_source.go]"]
  node_github_source["GitHub releases<br/>[github.go]"]
  node_altstore_source["AltStore sources<br/>[altstore.go]"]
  node_ipa["IPA handling<br/>[ipa.go]"]
  node_install_service["Install workflow"]
  node_signing_plan["Signing validation<br/>[plan.go]"]
  node_signing_api["Certificate management API<br/>[signing_routes.go]"]
end

subgraph group_operations["Background operations"]
  node_task_scheduler["Refresh scheduler<br/>[task.go]"]
  node_notifications["Notifications<br/>[notify.go]"]
  node_websocket["WebSocket service<br/>[websocket.go]"]
end

subgraph group_state["Persistent state"]
  node_database[("Database<br/>[db.go]")]
  node_settings["Settings<br/>[settings.go]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_webui
node_webui -.->|"sends requests"| node_api
node_operator -->|"pairs TV"| node_pairing
node_api -->|"lists devices"| node_device_manager
node_discovery -->|"updates devices"| node_device_manager
node_operator -->|"requests install"| node_api
node_api -->|"runs install"| node_install_service
node_api -->|"manages sources"| node_source_tracking
node_source_tracking -.->|"uses provider"| node_github_source
node_source_tracking -.->|"uses provider"| node_altstore_source
node_install_service -.->|"processes IPA"| node_ipa
node_install_service -->|"checks signing"| node_signing_plan
node_install_service -.->|"runs engine"| node_install_engine
node_signing_api -->|"checks install"| node_install_service
node_operator -->|"manages identity"| node_signing_api
node_task_scheduler -->|"runs refresh"| node_install_service
node_task_scheduler -->|"sends updates"| node_notifications
node_api -.->|"requests capture"| node_screenshot
node_api -.->|"opens connection"| node_websocket
node_mcp_server -->|"registers tools"| node_mcp
node_mcp -->|"runs install"| node_install_service
node_settings -.->|"persists settings"| node_database

click node_webui "https://github.com/bitxeno/atvloadly/blob/master/web/static/src/App.vue"
click node_api "https://github.com/bitxeno/atvloadly/blob/master/web/router.go"
click node_mcp "https://github.com/bitxeno/atvloadly/blob/master/internal/mcp/tools/install.go"
click node_discovery "https://github.com/bitxeno/atvloadly/blob/master/internal/manager/device_manager_avahi.go"
click node_device_manager "https://github.com/bitxeno/atvloadly/blob/master/internal/manager/device_manager.go"
click node_pairing "https://github.com/bitxeno/atvloadly/blob/master/internal/manager/pair_manager.go"
click node_install_engine "https://github.com/bitxeno/atvloadly/blob/master/internal/manager/install_manager.go"
click node_screenshot "https://github.com/bitxeno/atvloadly/blob/master/internal/manager/screenshot_manager.go"
click node_source_tracking "https://github.com/bitxeno/atvloadly/blob/master/internal/service/app_source.go"
click node_github_source "https://github.com/bitxeno/atvloadly/blob/master/internal/source/github.go"
click node_altstore_source "https://github.com/bitxeno/atvloadly/blob/master/internal/source/altstore.go"
click node_ipa "https://github.com/bitxeno/atvloadly/blob/master/internal/ipa/ipa.go"
click node_install_service "https://github.com/bitxeno/atvloadly/blob/master/internal/service/external_install.go"
click node_signing_plan "https://github.com/bitxeno/atvloadly/blob/master/internal/signing/appcheck/plan.go"
click node_signing_api "https://github.com/bitxeno/atvloadly/blob/master/web/signing_routes.go"
click node_task_scheduler "https://github.com/bitxeno/atvloadly/blob/master/internal/task/task.go"
click node_notifications "https://github.com/bitxeno/atvloadly/blob/master/internal/notify/notify.go"
click node_websocket "https://github.com/bitxeno/atvloadly/blob/master/internal/service/websocket.go"
click node_database "https://github.com/bitxeno/atvloadly/blob/master/internal/db/db.go"
click node_settings "https://github.com/bitxeno/atvloadly/blob/master/internal/app/settings.go"
click node_mcp_server "https://github.com/bitxeno/atvloadly/blob/master/internal/mcp/server.go"

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_webui,node_api,node_mcp,node_mcp_server toneBlue
class node_discovery,node_device_manager,node_pairing,node_install_engine,node_screenshot toneAmber
class node_source_tracking,node_github_source,node_altstore_source,node_ipa,node_install_service,node_signing_plan,node_signing_api toneMint
class node_task_scheduler,node_notifications,node_websocket toneRose
class node_database,node_settings,node_operator toneIndigo
```

## Components

### User access

- [Web interface](https://github.com/bitxeno/atvloadly/blob/master/web/static/src/App.vue): `web/static/src/App.vue`
- [HTTP API](https://github.com/bitxeno/atvloadly/blob/master/web/router.go): `web/router.go`
- [MCP tools](https://github.com/bitxeno/atvloadly/blob/master/internal/mcp/tools/install.go): `internal/mcp/tools/install.go`
- [MCP endpoint](https://github.com/bitxeno/atvloadly/blob/master/internal/mcp/server.go): `internal/mcp/server.go`

### Apple TV devices

- [Device discovery](https://github.com/bitxeno/atvloadly/blob/master/internal/manager/device_manager_avahi.go): `internal/manager/device_manager_avahi.go`
- [Device registry](https://github.com/bitxeno/atvloadly/blob/master/internal/manager/device_manager.go): `internal/manager/device_manager.go`
- [Device pairing](https://github.com/bitxeno/atvloadly/blob/master/internal/manager/pair_manager.go): `internal/manager/pair_manager.go`
- [Sideload engine](https://github.com/bitxeno/atvloadly/blob/master/internal/manager/install_manager.go): `internal/manager/install_manager.go`
- [Screenshots](https://github.com/bitxeno/atvloadly/blob/master/internal/manager/screenshot_manager.go): `internal/manager/screenshot_manager.go`

### Apps and signing

- [Source tracking](https://github.com/bitxeno/atvloadly/blob/master/internal/service/app_source.go): `internal/service/app_source.go`
- [GitHub releases](https://github.com/bitxeno/atvloadly/blob/master/internal/source/github.go): `internal/source/github.go`
- [AltStore sources](https://github.com/bitxeno/atvloadly/blob/master/internal/source/altstore.go): `internal/source/altstore.go`
- [IPA handling](https://github.com/bitxeno/atvloadly/blob/master/internal/ipa/ipa.go): `internal/ipa/ipa.go`
- [Install workflow](https://github.com/bitxeno/atvloadly/blob/master/internal/service/external_install.go): `internal/service/external_install.go`
- [Signing validation](https://github.com/bitxeno/atvloadly/blob/master/internal/signing/appcheck/plan.go): `internal/signing/appcheck/plan.go`
- [Certificate management API](https://github.com/bitxeno/atvloadly/blob/master/web/signing_routes.go): `web/signing_routes.go`

### Background operations

- [Refresh scheduler](https://github.com/bitxeno/atvloadly/blob/master/internal/task/task.go): `internal/task/task.go`
- [Notifications](https://github.com/bitxeno/atvloadly/blob/master/internal/notify/notify.go): `internal/notify/notify.go`
- [WebSocket service](https://github.com/bitxeno/atvloadly/blob/master/internal/service/websocket.go): `internal/service/websocket.go`

### Persistent state

- [Database](https://github.com/bitxeno/atvloadly/blob/master/internal/db/db.go): `internal/db/db.go`
- [Settings](https://github.com/bitxeno/atvloadly/blob/master/internal/app/settings.go): `internal/app/settings.go`

### Other components

- **Operator**

## Connections

- Operator → Web interface: uses (evidence: `README.md`)
- Web interface → HTTP API: sends requests
- Operator → Device pairing: pairs TV (evidence: `README.md`)
- HTTP API → Device registry: lists devices (evidence: `web/router.go`)
- Device discovery → Device registry: updates devices (evidence: `internal/manager/device_manager_avahi.go`)
- Operator → HTTP API: requests install (evidence: `web/router.go`)
- HTTP API → Install workflow: runs install (evidence: `web/router.go`)
- HTTP API → Source tracking: manages sources (evidence: `web/router.go`)
- Source tracking → GitHub releases: uses provider
- Source tracking → AltStore sources: uses provider
- Install workflow → IPA handling: processes IPA
- Install workflow → Signing validation: checks signing (evidence: `internal/service/external_install.go`)
- Install workflow → Sideload engine: runs engine
- Certificate management API → Install workflow: checks install (evidence: `web/signing_routes.go`)
- Operator → Certificate management API: manages identity (evidence: `web/signing_routes.go`)
- Refresh scheduler → Install workflow: runs refresh (evidence: `internal/task/task.go`)
- Refresh scheduler → Notifications: sends updates (evidence: `internal/task/task.go`)
- HTTP API → Screenshots: requests capture
- HTTP API → WebSocket service: opens connection
- MCP endpoint → MCP tools: registers tools (evidence: `internal/mcp/server.go`)
- MCP tools → Install workflow: runs install (evidence: `internal/mcp/tools/install.go`)
- Settings → Database: persists settings