# openatx/atxserver2 architecture

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

- Interactive diagram: https://gitdiagram.com/openatx/atxserver2
- Repository: https://github.com/openatx/atxserver2

## Overview

##### Main Components
a. Frontend (Client)
- Web browser or any HTTP client
- Loads HTML templates (templates/*.html) and static assets (static/javascripts, static/images)
b. Backend Web Server (Monolith)
- Entry point: main.py → starts a Tornado HTTP server
- Web layer: web/entry.py, web/urls.py, web/views/…
- Utilities: web/utils.py, web/libs/jsondate.py
- Settings & version: web/settings.py, web/__version__.py, web/version.py
- Database access: web/database.py (RethinkDB driver)
c. Persistence
- RethinkDB cluster (configured via environment variables or settings.py)
d. Authentication Providers (External Services)
- OpenID
- GitHub OAuth
e. Device Providers (Sidecar Services / Microservices)
- atxserver2‑android‑provider (Docker container)
- atxserver2‑ios‑provider (similar)
- Optional scripts/dummies for testing (scripts/fake_*.py, scripts/dummyslave.py)
f. Deployment & Orchestration
- Dockerfile + docker-compose.yml
- Procfile for Heroku-like platforms
- Shell scripts: wait-for-db.sh, wait_for_rethinkdb.py

##### Relationships & Data Flows
- Browser → Tornado Server: HTTP(S) requests for pages, AJAX, REST API calls
- Tornado Server → RethinkDB: CRUD queries (async)
- Tornado Server → Auth Providers: outbound OAuth/OpenID requests
- Device Providers ↔ Tornado Server:
- Providers register themselves or poll for tasks via RESTful endpoints (defined in web/views/provider.py)
- Providers stream device snapshots or input events back to server (multipart_streamer.py)
- Browser → Device Providers (indirect): via server‑mediated websockets or long polling to view/control device screens
- Admin API & CLI examples invoked via API.md

##### Architectural Patterns
- MVC‑style separation:
- Views: web/views/*
- Templates: templates/*.html
- Static assets: static/*
- Async I/O: Tornado’s non‑blocking handlers (async/await)
- Micro‑service / side‑car pattern: external device providers decoupled from core server
- Configuration via environment variables & settings.py
- Containerization for reproducible builds (Docker/Docker‑compose)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend (Client)"
        Browser["Web Browser"]:::client
        Templates["HTML Templates"]:::client
        StaticJS["Static JS"]:::client
        StaticImg["Static Images"]:::client
        StaticVendor["Static Vendor"]:::client
    end

    %% Core Server
    subgraph "Core Server (Tornado)" 
        Main["main.py"]:::backend
        Entry["web/entry.py"]:::backend
        Urls["web/urls.py"]:::backend
        subgraph "Views"
            Base["base.py"]:::backend
            AuthGH["github.py"]:::backend
            AuthOID["openid.py"]:::backend
            DeviceAPI["device.py"]:::backend
            ProviderView["provider.py"]:::backend
            Streamer["multipart_streamer.py"]:::backend
            GroupView["group.py"]:::backend
            UserView["user.py"]:::backend
            Upload["upload.py"]:::backend
            Login["login.py"]:::backend
        end
        Utils["web/utils.py"]:::backend
        JSONDate["web/libs/jsondate.py"]:::backend
        Settings["web/settings.py"]:::backend
        Version["web/version.py"]:::backend
        VerLabel["web/__version__.py"]:::backend
        DB["web/database.py"]:::backend
    end

    %% Persistence
    DBServer["RethinkDB\n(28015)"]:::db

    %% External Auth
    subgraph "Auth Providers"
        AuthExtGH["GitHub OAuth"]:::external
        AuthExtOID["OpenID"]:::external
    end

    %% Device Providers
    subgraph "Device Providers"
        AndroidProv["Android Provider"]:::provider
        iOSProv["iOS Provider"]:::provider
        FakeAnd["fake_android_provider.py"]:::provider
        FakeiOSscript["fake_ios_provider.py"]:::provider
        FakeApple["fake_apple_provider.py"]:::provider
        DummySlave["dummyslave.py"]:::provider
        AndroidExample["android_test.py"]:::provider
        CorsTest["cors-test.html"]:::provider
    end

    %% Deployment
    subgraph "Deployment & Orchestration"
        Dockerfile["Dockerfile"]:::deployment
        Compose["docker-compose.yml"]:::deployment
        Procfile["Procfile"]:::deployment
        WaitDBsh["wait-for-db.sh"]:::deployment
        WaitRethink["wait_for_rethinkdb.py"]:::deployment
    end

    %% Data Flows
    Browser -->|"HTTP(S) requests (4000)"| Main
    Main -->|"serves templates"| Templates
    Main -->|"serves static assets"| StaticJS
    Main --> StaticImg
    Main --> StaticVendor
    Main -->|"loads entrypoint"| Entry
    Entry -->|"routes defined"| Urls
    Urls -->|"dispatches to handlers"| Base
    Urls --> AuthGH
    Urls --> AuthOID
    Urls --> DeviceAPI
    Urls --> ProviderView
    Urls --> Streamer
    Urls --> GroupView
    Urls --> UserView
    Urls --> Upload
    Urls --> Login
    Base --> Utils
    Base --> JSONDate
    Base --> Settings
    Base --> Version
    Base --> VerLabel
    DeviceAPI --> DB
    ProviderView --> DB
    Streamer --> DB
    GroupView --> DB
    UserView --> DB
    Upload --> DB
    Login --> DB
    DB --> DBServer
    Main -->|"OAuth token exchange"| AuthExtGH
    Main -->|"OAuth token exchange"| AuthExtOID
    AndroidProv -->|"register & heartbeat"| Main
    iOSProv -->|"register & heartbeat"| Main
    FakeAnd --> Main
    FakeiOSscript --> Main
    FakeApple --> Main
    DummySlave --> Main
    AndroidProv -->|"screen/control stream"| Main
    Main -->|"websocket/long-poll"| Browser
    AndroidExample -->|"API usage"| Main
    CorsTest --> Main

    %% Click Events
    click Templates "https://github.com/openatx/atxserver2/tree/master/templates/"
    click StaticJS "https://github.com/openatx/atxserver2/tree/master/static/javascripts/"
    click StaticImg "https://github.com/openatx/atxserver2/tree/master/static/images/"
    click StaticVendor "https://github.com/openatx/atxserver2/tree/master/static/vendor/"
    click Main "https://github.com/openatx/atxserver2/blob/master/main.py"
    click Entry "https://github.com/openatx/atxserver2/blob/master/web/entry.py"
    click Urls "https://github.com/openatx/atxserver2/blob/master/web/urls.py"
    click Base "https://github.com/openatx/atxserver2/blob/master/web/views/base.py"
    click AuthGH "https://github.com/openatx/atxserver2/blob/master/web/views/auth/github.py"
    click AuthOID "https://github.com/openatx/atxserver2/blob/master/web/views/auth/openid.py"
    click DeviceAPI "https://github.com/openatx/atxserver2/blob/master/web/views/device.py"
    click ProviderView "https://github.com/openatx/atxserver2/blob/master/web/views/provider.py"
    click Streamer "https://github.com/openatx/atxserver2/blob/master/web/views/multipart_streamer.py"
    click GroupView "https://github.com/openatx/atxserver2/blob/master/web/views/group.py"
    click UserView "https://github.com/openatx/atxserver2/blob/master/web/views/user.py"
    click Upload "https://github.com/openatx/atxserver2/blob/master/web/views/upload.py"
    click Login "https://github.com/openatx/atxserver2/blob/master/web/views/login.py"
    click Utils "https://github.com/openatx/atxserver2/blob/master/web/utils.py"
    click JSONDate "https://github.com/openatx/atxserver2/blob/master/web/libs/jsondate.py"
    click Settings "https://github.com/openatx/atxserver2/blob/master/web/settings.py"
    click Version "https://github.com/openatx/atxserver2/blob/master/web/version.py"
    click VerLabel "https://github.com/openatx/atxserver2/blob/master/web/__version__.py"
    click DB "https://github.com/openatx/atxserver2/blob/master/web/database.py"
    click FakeAnd "https://github.com/openatx/atxserver2/blob/master/scripts/fake_android_provider.py"
    click FakeiOSscript "https://github.com/openatx/atxserver2/blob/master/scripts/fake_ios_provider.py"
    click FakeApple "https://github.com/openatx/atxserver2/blob/master/scripts/fake_apple_provider.py"
    click DummySlave "https://github.com/openatx/atxserver2/blob/master/scripts/dummyslave.py"
    click AndroidExample "https://github.com/openatx/atxserver2/blob/master/examples/android_test.py"
    click CorsTest "https://github.com/openatx/atxserver2/blob/master/examples/cors-test.html"
    click Dockerfile "https://github.com/openatx/atxserver2/tree/master/Dockerfile"
    click Compose "https://github.com/openatx/atxserver2/blob/master/docker-compose.yml"
    click Procfile "https://github.com/openatx/atxserver2/tree/master/Procfile"
    click WaitDBsh "https://github.com/openatx/atxserver2/blob/master/scripts/wait-for-db.sh"
    click WaitRethink "https://github.com/openatx/atxserver2/blob/master/scripts/wait_for_rethinkdb.py"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E3F2FD,stroke:#1E88E5,color:#1E88E5
    classDef db fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#E8F5E9,stroke:#43A047,color:#2E7D32
    classDef provider fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A
    classDef deployment fill:#ECEFF1,stroke:#546E7A,color:#37474F
```
