# screenly/anthias architecture

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

- Interactive diagram: https://gitdiagram.com/screenly/anthias
- Repository: https://github.com/screenly/anthias

## Overview

#### 1. Purpose and deployment shape
Anthias is a self-hosted digital-signage appliance for Raspberry Pi, generic ARM64 SBCs, and PCs. It manages a local asset library and schedules images, videos, and web content for a directly attached display. The deployable stack is container-oriented and supports balena fleets; native installation provisions hosts with Ansible.
- `docker-compose.yml.tmpl`
- `balena.yml`
- `ansible/site.yml`

#### 2. Runtime entry points
Three Python processes form the device runtime: a Django server/control plane, a display viewer, and a host agent. Container startup wrappers select and launch these roles.
- Server: `src/anthias_server/manage.py`, `bin/start_server.sh`
- Viewer: `src/anthias_viewer/__main__.py`, `bin/start_viewer.sh`
- Host agent: `src/anthias_host_agent/__main__.py`, `ansible/roles/anthias/templates/anthias-host-agent.service`

#### 3. Server: control plane and persistence
The Django application owns asset, schedule, and application-domain state, exposes the management UI and versioned REST APIs, and serves files/UI assets. ASGI routing supports realtime connections; model migrations define persistent schema evolution.
- `src/anthias_server/app/models.py`
- `src/anthias_server/app/views.py`
- `src/anthias_server/api/urls/v2.py`
- `src/anthias_server/django_project/asgi.py`

#### 4. Asset ingestion, processing, and integrations
Assets enter through dashboard/API upload and import/migration workflows. Server-side processing prepares or validates media; integrations use common ingestion abstractions to import external signage content. Remote-video, YouTube, and HTTP handling live in shared modules.
- `src/anthias_server/processing.py`
- `src/anthias_server/lib/integrations/ingest.py`
- `src/anthias_server/lib/integrations/registry.py`
- `src/anthias_server/lib/screenly_migration.py`
- `src/anthias_common/remote_video.py`

#### 5. Scheduling and playback pipeline
The viewer consumes server-provided asset state, applies scheduling, and dispatches each selected asset to media or web rendering. Playback includes a GStreamer framebuffer path; supported web content is rendered by a separate Qt WebView executable. This is the principal boundary between management state and physical display output.
- `src/anthias_viewer/scheduling.py`
- `src/anthias_viewer/playback.py`
- `src/anthias_viewer/media_player.py`
- `src/anthias_viewer/gst_fbdev_player.py`
- `src/anthias_webview/src/main.cpp`

#### 6. Device operations and hardware boundary
The host agent and server libraries inspect device/network characteristics and control or monitor attached hardware: HDMI-CEC/display power, storage health, and undervoltage. These isolate Linux/device-specific behavior from Django views and viewer policy.
- `src/anthias_host_agent/ifaddrs.py`
- `src/anthias_server/lib/display_power.py`
- `src/anthias_server/lib/cec_client.py`
- `src/anthias_server/lib/storage_watcher.py`
- `src/anthias_common/undervoltage.py`

#### 7. Background, infrastructure, and packaging
Celery handles deferred server work, with Redis supplied as an infrastructure service. Docker images encapsulate server, viewer, Redis, and specialized Qt build stages. Balena deployment and Ansible provisioning provide alternative operational boundaries; GitHub Actions build images, test, generate OpenAPI, and deploy artifacts.
- `src/anthias_server/celery_tasks.py`
- `docker/Dockerfile.server.j2`
- `docker/Dockerfile.viewer.j2`
- `docker/Dockerfile.redis.j2`
- `docker-compose.balena.yml.tmpl`

Main entry points: [`src/anthias_server/manage.py`](https://github.com/screenly/anthias/blob/master/src/anthias_server/manage.py) (Django server), [`docker-compose.yml.tmpl`](https://github.com/screenly/anthias/blob/master/docker-compose.yml.tmpl) (Container stack), [`src/anthias_viewer/playback.py`](https://github.com/screenly/anthias/blob/master/src/anthias_viewer/playback.py) (Playback dispatch), [`src/anthias_server/app/models.py`](https://github.com/screenly/anthias/blob/master/src/anthias_server/app/models.py) (Assets and schedules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_compose["Container stack<br/>Compose deployment"]
  node_balena["Balena fleet<br/>Fleet deployment<br/>[balena.yml]"]
  node_ansible["Native provisioning<br/>Ansible playbook<br/>[site.yml]"]
end

subgraph group_control["Control plane"]
  node_server["Django server<br/>Control-plane process<br/>[manage.py]"]
  node_server_ui_api["Management UI and v2 API<br/>Django endpoints<br/>[v2.py]"]
  node_domain_models[("Assets and schedules<br/>Persistent domain models<br/>[models.py]")]
  node_realtime["ASGI realtime routing<br/>Realtime endpoint<br/>[asgi.py]"]
  node_ingestion["Asset ingestion<br/>Import pipeline<br/>[ingest.py]"]
  node_processing["Media processing<br/>Asset processing<br/>[processing.py]"]
  node_celery["Deferred tasks<br/>Celery workers<br/>[celery_tasks.py]"]
  node_redis[("Redis<br/>Task infrastructure")]
end

subgraph group_playback["Playback"]
  node_viewer["Display viewer<br/>Playback process<br/>[__main__.py]"]
  node_scheduling["Schedule selection<br/>Viewer policy<br/>[scheduling.py]"]
  node_playback_dispatch["Playback dispatch<br/>Renderer selection<br/>[playback.py]"]
  node_media_renderer["GStreamer framebuffer<br/>Media renderer"]
  node_webview["Qt WebView<br/>Web renderer<br/>[main.cpp]"]
end

subgraph group_device["Device operations"]
  node_display{{"Attached display<br/>Hardware output"}}
  node_host_agent["Host agent<br/>Device agent process<br/>[__main__.py]"]
  node_hardware_ops["Display and health control<br/>Hardware integration<br/>[display_power.py]"]
end

node_compose -->|"runs"| node_server
node_compose -->|"runs"| node_viewer
node_compose -->|"runs"| node_redis
node_balena -->|"deploys stack"| node_compose
node_ansible -->|"provisions service"| node_host_agent
node_server -->|"serves"| node_server_ui_api
node_server -->|"owns"| node_domain_models
node_server -->|"exposes"| node_realtime
node_server_ui_api -->|"accepts assets"| node_ingestion
node_ingestion -->|"prepares media"| node_processing
node_processing -->|"stores asset state"| node_domain_models
node_server -->|"queues deferred work"| node_celery
node_celery -->|"uses"| node_redis
node_domain_models -->|"provides asset state"| node_viewer
node_viewer -->|"applies"| node_scheduling
node_scheduling -->|"selects asset"| node_playback_dispatch
node_playback_dispatch -->|"media content"| node_media_renderer
node_playback_dispatch -->|"web content"| node_webview
node_media_renderer -->|"framebuffer output"| node_display
node_webview -->|"rendered output"| node_display
node_host_agent -->|"reports host state"| node_server
node_server -->|"requests device control"| node_hardware_ops
node_hardware_ops -->|"CEC and power control"| node_display

click node_compose "https://github.com/screenly/anthias/blob/master/docker-compose.yml.tmpl"
click node_balena "https://github.com/screenly/anthias/blob/master/balena.yml"
click node_ansible "https://github.com/screenly/anthias/blob/master/ansible/site.yml"
click node_server "https://github.com/screenly/anthias/blob/master/src/anthias_server/manage.py"
click node_server_ui_api "https://github.com/screenly/anthias/blob/master/src/anthias_server/api/urls/v2.py"
click node_domain_models "https://github.com/screenly/anthias/blob/master/src/anthias_server/app/models.py"
click node_realtime "https://github.com/screenly/anthias/blob/master/src/anthias_server/django_project/asgi.py"
click node_ingestion "https://github.com/screenly/anthias/blob/master/src/anthias_server/lib/integrations/ingest.py"
click node_processing "https://github.com/screenly/anthias/blob/master/src/anthias_server/processing.py"
click node_celery "https://github.com/screenly/anthias/blob/master/src/anthias_server/celery_tasks.py"
click node_redis "https://github.com/screenly/anthias/blob/master/docker/Dockerfile.redis.j2"
click node_viewer "https://github.com/screenly/anthias/blob/master/src/anthias_viewer/__main__.py"
click node_scheduling "https://github.com/screenly/anthias/blob/master/src/anthias_viewer/scheduling.py"
click node_playback_dispatch "https://github.com/screenly/anthias/blob/master/src/anthias_viewer/playback.py"
click node_media_renderer "https://github.com/screenly/anthias/blob/master/src/anthias_viewer/gst_fbdev_player.py"
click node_webview "https://github.com/screenly/anthias/blob/master/src/anthias_webview/src/main.cpp"
click node_host_agent "https://github.com/screenly/anthias/blob/master/src/anthias_host_agent/__main__.py"
click node_hardware_ops "https://github.com/screenly/anthias/blob/master/src/anthias_server/lib/display_power.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_compose,node_balena,node_ansible toneBlue
class node_server,node_server_ui_api,node_domain_models,node_realtime,node_ingestion,node_processing,node_celery,node_redis toneAmber
class node_viewer,node_scheduling,node_playback_dispatch,node_media_renderer,node_webview toneMint
class node_display,node_host_agent,node_hardware_ops toneRose
```

## Components

### Deployment

- [Container stack](https://github.com/screenly/anthias/blob/master/docker-compose.yml.tmpl): Compose deployment · Defines the appliance service stack. · `docker-compose.yml.tmpl`
- [Balena fleet](https://github.com/screenly/anthias/blob/master/balena.yml): Fleet deployment · `balena.yml`
- [Native provisioning](https://github.com/screenly/anthias/blob/master/ansible/site.yml): Ansible playbook · `ansible/site.yml`

### Control plane

- [Django server](https://github.com/screenly/anthias/blob/master/src/anthias_server/manage.py): Control-plane process · Owns management, APIs, and application state. · `src/anthias_server/manage.py`
- [Management UI and v2 API](https://github.com/screenly/anthias/blob/master/src/anthias_server/api/urls/v2.py): Django endpoints · `src/anthias_server/api/urls/v2.py`
- [Assets and schedules](https://github.com/screenly/anthias/blob/master/src/anthias_server/app/models.py): Persistent domain models · `src/anthias_server/app/models.py`
- [ASGI realtime routing](https://github.com/screenly/anthias/blob/master/src/anthias_server/django_project/asgi.py): Realtime endpoint · `src/anthias_server/django_project/asgi.py`
- [Asset ingestion](https://github.com/screenly/anthias/blob/master/src/anthias_server/lib/integrations/ingest.py): Import pipeline · Imports uploads and external signage content. · `src/anthias_server/lib/integrations/ingest.py`
- [Media processing](https://github.com/screenly/anthias/blob/master/src/anthias_server/processing.py): Asset processing · `src/anthias_server/processing.py`
- [Deferred tasks](https://github.com/screenly/anthias/blob/master/src/anthias_server/celery_tasks.py): Celery workers · `src/anthias_server/celery_tasks.py`
- [Redis](https://github.com/screenly/anthias/blob/master/docker/Dockerfile.redis.j2): Task infrastructure · `docker/Dockerfile.redis.j2`

### Playback

- [Display viewer](https://github.com/screenly/anthias/blob/master/src/anthias_viewer/__main__.py): Playback process · Turns server state into display output. · `src/anthias_viewer/__main__.py`
- [Schedule selection](https://github.com/screenly/anthias/blob/master/src/anthias_viewer/scheduling.py): Viewer policy · `src/anthias_viewer/scheduling.py`
- [Playback dispatch](https://github.com/screenly/anthias/blob/master/src/anthias_viewer/playback.py): Renderer selection · `src/anthias_viewer/playback.py`
- [GStreamer framebuffer](https://github.com/screenly/anthias/blob/master/src/anthias_viewer/gst_fbdev_player.py): Media renderer · `src/anthias_viewer/gst_fbdev_player.py`
- [Qt WebView](https://github.com/screenly/anthias/blob/master/src/anthias_webview/src/main.cpp): Web renderer · `src/anthias_webview/src/main.cpp`

### Device operations

- **Attached display**: Hardware output
- [Host agent](https://github.com/screenly/anthias/blob/master/src/anthias_host_agent/__main__.py): Device agent process · Inspects host and network characteristics. · `src/anthias_host_agent/__main__.py`
- [Display and health control](https://github.com/screenly/anthias/blob/master/src/anthias_server/lib/display_power.py): Hardware integration · Controls display power and monitors device health. · `src/anthias_server/lib/display_power.py`

## Connections

- Container stack → Django server: runs
- Container stack → Display viewer: runs
- Container stack → Redis: runs
- Balena fleet → Container stack: deploys stack
- Native provisioning → Host agent: provisions service
- Django server → Management UI and v2 API: serves
- Django server → Assets and schedules: owns
- Django server → ASGI realtime routing: exposes
- Management UI and v2 API → Asset ingestion: accepts assets
- Asset ingestion → Media processing: prepares media
- Media processing → Assets and schedules: stores asset state
- Django server → Deferred tasks: queues deferred work
- Deferred tasks → Redis: uses
- Assets and schedules → Display viewer: provides asset state
- Display viewer → Schedule selection: applies
- Schedule selection → Playback dispatch: selects asset
- Playback dispatch → GStreamer framebuffer: media content
- Playback dispatch → Qt WebView: web content
- GStreamer framebuffer → Attached display: framebuffer output
- Qt WebView → Attached display: rendered output
- Host agent → Django server: reports host state
- Django server → Display and health control: requests device control
- Display and health control → Attached display: CEC and power control
