# aakashdeeeep/wallops architecture

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

- Interactive diagram: https://gitdiagram.com/aakashdeeeep/wallops
- Repository: https://github.com/aakashdeeeep/wallops

## Overview

#### Purpose and entry points
Quickplay SOC Automation is a local Flask control system for a 56-device TV wall used in OTT live/VOD testing. The server starts at `app.py`; database initialization is performed by `db.py`. Operators use rendered dashboard/admin pages, while automation clients can call JSON endpoints such as network scanning.

#### Flask application boundary
`app.py` assembles the web application and registers page/API route modules. `routes/views.py` owns operator-facing navigation and dashboard pages; `routes/api.py` exposes action-oriented endpoints for device management, scans, status, and launches. UI behavior is implemented by page-specific scripts such as `static/js/tv_dashboard.js` and `static/js/admin_devices.js`.

#### Persistent device registry and domain model
SQLite is the source of truth for known wall devices, created at runtime under `data/wall.db`. `models.py` defines registry-oriented data access/model structures, while `db.py` initializes storage. Device MAC addresses are treated as permanent identities; IP addresses and network assignments are mutable discovery results. Bulk bootstrap/import paths include `seed_devices.py` and `import_device_registry.py`.

#### Slot and content assignment layer
A device slot represents a wall position/channel, with identifiers such as `TV1-CH11`. `slot_naming.py` converts those IDs into TV-group and channel semantics used by selection and grouping flows. `content_catalog.py` maintains content/platform/title/type assignments for slots, with import support in `import_content_catalog.py`; these assignments feed launch decisions rather than directly controlling devices.

#### Device-control dispatcher
`device_control/launcher.py` is the protocol-neutral launch boundary: route-level requests should resolve a registered device and dispatch to the correct platform adapter. `device_control/roku.py` implements Roku launches through ECP HTTP requests. `device_control/adb.py` implements Android TV, Fire TV, and Google TV operations through wireless ADB subprocess calls. `device_control/appletv.py` exists as an extension point for planned Apple TV support.

#### Discovery, identity refresh, and connectivity
Network discovery is separated from registry persistence and control. `device_control/scanner.py` finds reachable devices, `device_control/mac_lookup.py` resolves MAC identity through ARP-based lookup, and `device_control/background_scanner.py` supports ongoing refresh work. `device_control/status.py` performs online/offline probing. Discovery results update transient IP/network data for registered MAC identities; scripts such as `scan_subnet.py`, `discover_roku.py`, and `discover_adb_port.py` support operational discovery workflows.

#### Infrastructure and external protocols
The runtime is Python 3 with Flask and SQLite. Roku devices are controlled over Roku ECP via HTTP (`requests`); Android-family devices are controlled via wireless ADB using OS subprocess execution. Network scanning, ARP/MAC resolution, and ADB pairing/reconnection are operational dependencies, with support scripts in `pair_wireless_adb.py` and `reconnect_wireless_adb.py`. Network definitions, protocol ports, platform app identifiers, presets, and OPS access restrictions are centralized in `config.py`.

Main entry points: [`device_control/launcher.py`](https://github.com/aakashdeeeep/wallops/blob/main/device_control/launcher.py) (Launch dispatcher), [`device_control/scanner.py`](https://github.com/aakashdeeeep/wallops/blob/main/device_control/scanner.py) (Network discovery), [`models.py`](https://github.com/aakashdeeeep/wallops/blob/main/models.py) (Registry model access), [`routes/api.py`](https://github.com/aakashdeeeep/wallops/blob/main/routes/api.py) (Automation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Flask UI & API"]
  node_app["Flask application<br/>[app.py]"]
  node_views["Operator pages<br/>Flask views<br/>[views.py]"]
  node_api["Automation API<br/>Flask API<br/>[api.py]"]
  node_dashboard_js["TV dashboard UI<br/>browser script<br/>[tv_dashboard.js]"]
  node_admin_js["Device admin UI<br/>browser script<br/>[admin_devices.js]"]
end

subgraph group_domain["Registry &amp; Assignments"]
  node_db_init["Database initialization<br/>SQLite bootstrap<br/>[db.py]"]
  node_wall_db[("Wall device registry<br/>SQLite database")]
  node_models["Registry model access<br/>data model<br/>[models.py]"]
  node_slots["Slot naming<br/>slot semantics<br/>[slot_naming.py]"]
  node_catalog["Content catalog<br/>assignment catalog<br/>[content_catalog.py]"]
end

subgraph group_control["Control &amp; Discovery"]
  node_launcher{{"Launch dispatcher<br/>control boundary<br/>[launcher.py]"}}
  node_scanner["Network discovery<br/>device scanner<br/>[scanner.py]"]
  node_mac_lookup["MAC identity lookup<br/>ARP resolver<br/>[mac_lookup.py]"]
  node_background_scanner["Background refresh<br/>scanner worker"]
  node_status["Connectivity status<br/>reachability probe<br/>[status.py]"]
end

subgraph group_platforms["Platform Protocols"]
  node_roku["Roku adapter<br/>Roku ECP<br/>[roku.py]"]
  node_adb["Android-family adapter<br/>wireless ADB<br/>[adb.py]"]
  node_appletv["Apple TV adapter<br/>extension point<br/>[appletv.py]"]
end

node_config["Runtime configuration<br/>[config.py]"]

node_app -->|"registers"| node_views
node_app -->|"registers"| node_api
node_views -->|"serves UI for"| node_dashboard_js
node_views -->|"serves UI for"| node_admin_js
node_api -->|"launch requests"| node_launcher
node_api -->|"scan requests"| node_scanner
node_api -->|"status requests"| node_status
node_db_init -->|"creates"| node_wall_db
node_models -->|"reads and writes"| node_wall_db
node_launcher -->|"resolves device"| node_models
node_launcher -->|"uses assignment"| node_catalog
node_catalog -->|"assigns by slot"| node_slots
node_launcher -->|"dispatches Roku"| node_roku
node_launcher -->|"dispatches Android family"| node_adb
node_launcher -.->|"future dispatch"| node_appletv
node_scanner -->|"resolves identity"| node_mac_lookup
node_mac_lookup -->|"matches MAC registry"| node_models
node_scanner -->|"refreshes IP and network"| node_models
node_background_scanner -->|"runs ongoing refresh"| node_scanner
node_status -->|"probes registered devices"| node_models
node_config -->|"platform settings"| node_launcher
node_config -->|"network definitions"| node_scanner
node_config -->|"ADB settings"| node_adb

click node_app "https://github.com/aakashdeeeep/wallops/blob/main/app.py"
click node_views "https://github.com/aakashdeeeep/wallops/blob/main/routes/views.py"
click node_api "https://github.com/aakashdeeeep/wallops/blob/main/routes/api.py"
click node_dashboard_js "https://github.com/aakashdeeeep/wallops/blob/main/static/js/tv_dashboard.js"
click node_admin_js "https://github.com/aakashdeeeep/wallops/blob/main/static/js/admin_devices.js"
click node_db_init "https://github.com/aakashdeeeep/wallops/blob/main/db.py"
click node_models "https://github.com/aakashdeeeep/wallops/blob/main/models.py"
click node_slots "https://github.com/aakashdeeeep/wallops/blob/main/slot_naming.py"
click node_catalog "https://github.com/aakashdeeeep/wallops/blob/main/content_catalog.py"
click node_launcher "https://github.com/aakashdeeeep/wallops/blob/main/device_control/launcher.py"
click node_scanner "https://github.com/aakashdeeeep/wallops/blob/main/device_control/scanner.py"
click node_mac_lookup "https://github.com/aakashdeeeep/wallops/blob/main/device_control/mac_lookup.py"
click node_background_scanner "https://github.com/aakashdeeeep/wallops/blob/main/device_control/background_scanner.py"
click node_status "https://github.com/aakashdeeeep/wallops/blob/main/device_control/status.py"
click node_roku "https://github.com/aakashdeeeep/wallops/blob/main/device_control/roku.py"
click node_adb "https://github.com/aakashdeeeep/wallops/blob/main/device_control/adb.py"
click node_appletv "https://github.com/aakashdeeeep/wallops/blob/main/device_control/appletv.py"
click node_config "https://github.com/aakashdeeeep/wallops/blob/main/config.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_app,node_views,node_api,node_dashboard_js,node_admin_js toneBlue
class node_db_init,node_wall_db,node_models,node_slots,node_catalog toneAmber
class node_launcher,node_scanner,node_mac_lookup,node_background_scanner,node_status toneMint
class node_roku,node_adb,node_appletv toneRose
class node_config toneNeutral
```

## Components

### Flask UI & API

- [Flask application](https://github.com/aakashdeeeep/wallops/blob/main/app.py): application · Assembles the server and registers route modules. · `app.py`
- [Operator pages](https://github.com/aakashdeeeep/wallops/blob/main/routes/views.py): Flask views · `routes/views.py`
- [Automation API](https://github.com/aakashdeeeep/wallops/blob/main/routes/api.py): Flask API · Action endpoints for devices, scans, status, and launches. · `routes/api.py`
- [TV dashboard UI](https://github.com/aakashdeeeep/wallops/blob/main/static/js/tv_dashboard.js): browser script · `static/js/tv_dashboard.js`
- [Device admin UI](https://github.com/aakashdeeeep/wallops/blob/main/static/js/admin_devices.js): browser script · `static/js/admin_devices.js`

### Registry & Assignments

- [Database initialization](https://github.com/aakashdeeeep/wallops/blob/main/db.py): SQLite bootstrap · `db.py`
- **Wall device registry**: SQLite database · MAC identity is permanent; IP and network fields are refreshed.
- [Registry model access](https://github.com/aakashdeeeep/wallops/blob/main/models.py): data model · `models.py`
- [Slot naming](https://github.com/aakashdeeeep/wallops/blob/main/slot_naming.py): slot semantics · Maps slot IDs to TV-group and channel meanings. · `slot_naming.py`
- [Content catalog](https://github.com/aakashdeeeep/wallops/blob/main/content_catalog.py): assignment catalog · Slot content assignments inform launch decisions. · `content_catalog.py`

### Control & Discovery

- [Launch dispatcher](https://github.com/aakashdeeeep/wallops/blob/main/device_control/launcher.py): control boundary · Resolves a registered device and selects its platform adapter. · `device_control/launcher.py`
- [Network discovery](https://github.com/aakashdeeeep/wallops/blob/main/device_control/scanner.py): device scanner · `device_control/scanner.py`
- [MAC identity lookup](https://github.com/aakashdeeeep/wallops/blob/main/device_control/mac_lookup.py): ARP resolver · `device_control/mac_lookup.py`
- [Background refresh](https://github.com/aakashdeeeep/wallops/blob/main/device_control/background_scanner.py): scanner worker · `device_control/background_scanner.py`
- [Connectivity status](https://github.com/aakashdeeeep/wallops/blob/main/device_control/status.py): reachability probe · `device_control/status.py`

### Platform Protocols

- [Roku adapter](https://github.com/aakashdeeeep/wallops/blob/main/device_control/roku.py): Roku ECP · Launches through ECP HTTP requests. · `device_control/roku.py`
- [Android-family adapter](https://github.com/aakashdeeeep/wallops/blob/main/device_control/adb.py): wireless ADB · Controls Android TV, Fire TV, and Google TV via subprocess calls. · `device_control/adb.py`
- [Apple TV adapter](https://github.com/aakashdeeeep/wallops/blob/main/device_control/appletv.py): extension point · Planned Apple TV control adapter. · `device_control/appletv.py`

### Other components

- [Runtime configuration](https://github.com/aakashdeeeep/wallops/blob/main/config.py): configuration · Centralizes network, ports, app IDs, presets, and access restrictions. · `config.py`

## Connections

- Flask application → Operator pages: registers
- Flask application → Automation API: registers
- Operator pages → TV dashboard UI: serves UI for
- Operator pages → Device admin UI: serves UI for
- Automation API → Launch dispatcher: launch requests
- Automation API → Network discovery: scan requests
- Automation API → Connectivity status: status requests
- Database initialization → Wall device registry: creates
- Registry model access → Wall device registry: reads and writes
- Launch dispatcher → Registry model access: resolves device
- Launch dispatcher → Content catalog: uses assignment
- Content catalog → Slot naming: assigns by slot
- Launch dispatcher → Roku adapter: dispatches Roku
- Launch dispatcher → Android-family adapter: dispatches Android family
- Launch dispatcher → Apple TV adapter: future dispatch
- Network discovery → MAC identity lookup: resolves identity
- MAC identity lookup → Registry model access: matches MAC registry
- Network discovery → Registry model access: refreshes IP and network
- Background refresh → Network discovery: runs ongoing refresh
- Connectivity status → Registry model access: probes registered devices
- Runtime configuration → Launch dispatcher: platform settings
- Runtime configuration → Network discovery: network definitions
- Runtime configuration → Android-family adapter: ADB settings