# pablosambuco/caststatusserver architecture

> Architecture diagram of the GitHub repository pablosambuco/caststatusserver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pablosambuco/caststatusserver
- Repository: https://github.com/pablosambuco/caststatusserver

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page style web application running on a Raspberry Pi (or any Linux system) as a systemd service.
- It discovers and controls Chromecast devices on the local network, exposing status and basic controls via a web UI and WebSocket channel.

##### File Structure
Top-level components:
- caststatusserver.py  – Main entrypoint, initializes the web server (bottle/werkzeug) and WebSocket handlers (gevent-websocket).
- web.py              – Defines HTTP routes (login, status pages) and API endpoints.
- static/             – Client assets (HTML, CSS, JS). JavaScript (main.js) opens a WebSocket and issues AJAX calls.
- views/              – Template files (login.tpl).
- service/            – systemd unit file for auto-starting the server.
- install_service.sh  – Installation script for the service.
- interface.cfg, port.cfg – Configuration files (network interface, listening port).
- requirements.txt / Pipfile – Python dependencies: Bottle (or Werkzeug), gevent, gevent-websocket, pychromecast.

##### README for Additional Insights
- Confirms use of pychromecast to discover/control devices.
- Uses gevent-based WebSocket for live updates.
- Runs as a systemd service on Raspberry Pi.

##### Main Components and Relationships
A. Client Browser
- Loads HTML/CSS from “static/html/index.html”
- Runs JavaScript (static/js/main.js).
B. HTTP Server (caststatusserver.py + web.py)
- Serves static files & templates.
- Exposes RESTful endpoints for login/status.
- Manages WebSocket connections for real-time updates.
C. Chromecast Controller Module
- Uses pychromecast to scan LAN, retrieve status, send play/pause commands.
- Runs within the same Python process under gevent’s event loop.
D. Configuration Store
- interface.cfg, port.cfg read at startup.
E. System Service
- systemd unit (service/caststatusserver.service) invokes install_service.sh.
F. External Network
- Local network including multiple Chromecast devices.

Data flows:
1. Browser → HTTP GET → Server → static/html or template view.
2. Browser → AJAX/REST → Server → Chromecast module → LAN → devices → Server → JSON response → Browser.
3. Browser ↔ WebSocket → Server → Chromecast module (push updates) → Browser UI.

##### Architectural Patterns & Design Principles
- Monolithic, event-driven architecture: all components live in one process.
- Asynchronous I/O via gevent for nonblocking Chromecast calls and WebSockets.
- Clear separation: Static assets vs. dynamic Python code vs. system service.
- Minimal external dependencies: Bottle or Werkzeug for HTTP, gevent for concurrency, pychromecast for device control.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client-side
    subgraph "Client-side"
        direction TB
        Browser["Browser UI"]:::frontend
        HTML["index.html"]:::frontend
        MainJS["main.js"]:::frontend
        CSS1["estilo.css"]:::frontend
        CSS2["login.css"]:::frontend
        Images["images/"]:::frontend
    end

    %% Server-side
    subgraph "Server-side"
        direction TB
        HTTP["caststatusserver.py"]:::backend
        WebPY["web.py"]:::backend
        Template["login.tpl"]:::backend
    end

    %% Device Control
    subgraph "Chromecast Controller Module"
        direction TB
        Requirements["requirements.txt/Pipfile"]:::device
        DeviceLogic["caststatusserver.py"]:::device
    end

    %% Configuration Store
    subgraph "Configuration Store"
        direction TB
        IFcfg["interface.cfg"]:::config
        Portcfg["port.cfg"]:::config
    end

    %% System Service
    subgraph "System Service"
        direction TB
        ServiceUnit["caststatusserver.service"]:::service
        Installer["install_service.sh"]:::service
    end

    %% Documentation & Metadata
    Docs["README.md / doc/doc.md / .deepsource.toml / Doxyfile / Makefile"]:::docs

    %% External Network
    Network["Local Network & Chromecast Devices"]:::external

    %% Data Flows
    Browser -->|"HTTP GET"| HTTP
    HTTP -->|"serves index.html"| HTML
    HTTP -->|"serves CSS/JS"| CSS1
    HTTP -->|"serves CSS/JS"| CSS2
    HTTP -->|"serves JS"| MainJS
    HTTP -->|"serves images"| Images

    Browser -->|"REST (AJAX)"| HTTP
    HTTP -->|"calls pychromecast"| DeviceLogic
    DeviceLogic -->|"mDNS/HTTPS"| Network
    Network -->|"status responses"| DeviceLogic
    DeviceLogic -->|"JSON response"| HTTP
    HTTP -->|"JSON response"| Browser

    Browser <-->|"WebSocket"| HTTP
    HTTP -->|"push updates"| Browser

    %% Startup Flow
    ServiceUnit -->|"systemd start"| HTTP
    HTTP -->|"reads configs"| IFcfg
    HTTP -->|"reads configs"| Portcfg

    %% Click Events
    click HTML "https://github.com/pablosambuco/caststatusserver/blob/main/static/html/index.html"
    click MainJS "https://github.com/pablosambuco/caststatusserver/blob/main/static/js/main.js"
    click CSS1 "https://github.com/pablosambuco/caststatusserver/blob/main/static/css/estilo.css"
    click CSS2 "https://github.com/pablosambuco/caststatusserver/blob/main/static/css/login.css"
    click Images "https://github.com/pablosambuco/caststatusserver/tree/main/static/images/"
    click HTTP "https://github.com/pablosambuco/caststatusserver/blob/main/caststatusserver.py"
    click WebPY "https://github.com/pablosambuco/caststatusserver/blob/main/web.py"
    click Template "https://github.com/pablosambuco/caststatusserver/blob/main/views/login.tpl"
    click DeviceLogic "https://github.com/pablosambuco/caststatusserver/blob/main/caststatusserver.py"
    click Requirements "https://github.com/pablosambuco/caststatusserver/blob/main/requirements.txt"
    click IFcfg "https://github.com/pablosambuco/caststatusserver/blob/main/interface.cfg"
    click Portcfg "https://github.com/pablosambuco/caststatusserver/blob/main/port.cfg"
    click ServiceUnit "https://github.com/pablosambuco/caststatusserver/blob/main/service/caststatusserver.service"
    click Installer "https://github.com/pablosambuco/caststatusserver/blob/main/install_service.sh"
    click Docs "https://github.com/pablosambuco/caststatusserver/blob/main/README.md"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef device fill:#fff3cd,stroke:#856404,color:#856404
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef service fill:#f1f1f1,stroke:#666666,color:#333333
    classDef docs fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
