# rmountjoy92/dashmachine architecture

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

- Interactive diagram: https://gitdiagram.com/rmountjoy92/dashmachine
- Repository: https://github.com/rmountjoy92/dashmachine

## Overview

##### Project Type and Purpose
- This is a full-stack, single-container web application (“DashMachine”) built on the Flask framework (Python 3) that serves a customizable bookmark dashboard with support for various external service integrations (e.g., Plex, Sonarr, weather).
- It exposes both HTML-based UI endpoints and a REST API, persists data in a SQLite database via SQLAlchemy, and is packaged for Docker or direct Python deployment.

##### High-Level File Structure & Architectural Patterns
- dashmachine/
- __init__.py – application factory, Flask app setup
- main/, user_system/, settings_system/, error_pages/, rest_api/ – Blueprints implementing MVC-style separation:
– models.py (SQLAlchemy models), forms.py (WTForms), routes.py (view controllers), utils.py (shared helpers)
- platform/ – “service adapter” modules for external integrations (e.g., ping, Docker, Tautulli)
- templates/ – Jinja2 templates organized per-blueprint (main, user, settings, error_pages)
- static/ – CSS/JS/images assets served by Flask’s static route
- site.db & migrations/ – SQLite DB and Alembic migrations
- read_config.py & settings utils – load/validate .ini configuration
- run.py / wsgi.py – entry points for development server or WSGI containers
- Dockerfile / .dockerignore – containerization definitions
- template_apps/ – prefilled .ini templates for third-party apps

##### README Insights
- Tech stack: Flask, SQLAlchemy/SQLite, Jinja2, Materialize CSS, jQuery
- Runtime: Docker or Python virtualenv
- Config: Uses a config.ini under user_data, reloaded on restart or explicit “save”
- REST API: Exposed under /api via rest_api Blueprint

##### Main Components & Their Interactions
A. Browser / Client
- Sends HTTP(S) requests for UI pages or AJAX calls to REST API
- Fetches static assets directly from Flask’s static endpoint
B. Flask Application (monolith)
- Application Factory initializes Flask app, registers Blueprints:
- main – home, dashboard
- user_system – auth, user management
- settings_system – app settings, config editor
- rest_api – JSON endpoints for external automation
- error_pages – custom error handlers (403, 404, 500)
- Middleware: read_config loads config.ini into app context; error handlers catch exceptions
C. Database (SQLite + Alembic)
- SQLAlchemy ORM accessed via each Blueprint’s models.py
- Alembic manages schema migrations in migrations/
D. Platform Adapters (External Service Integrations)
- Each module under platform/ implements a common interface for status checks, REST calls, parsing, etc.
- Blueprints call platform.* functions to aggregate remote service data for display
E. Storage (user_data folder)
F. Docker Container / Host Environment
- Exposes port 5000 (and optional CONTEXT_PATH)
- Mounts host volume to /dashmachine/dashmachine/user_data

##### Architectural Patterns & Design Principles
- Blueprint-based modularization for separation of concerns
- MVC pattern: models (ORM), controllers (routes), views (Jinja templates)
- Adapter pattern for external services under platform/
- Configuration-as-code via .ini, reloaded dynamically
- Single monolith container; can be scaled horizontally by multiple instances behind a reverse proxy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Host Layer
    subgraph "Docker Host / Reverse Proxy"
        direction TB
        HOST_PORT("Port 5000 ↔ Container"):::external
        VOLUME("Volume Mount ↔ /dashmachine/user_data"):::storage
    end

    %% Container Layer
    subgraph "DashMachine Container"
        direction TB
        %% Flask Application
        subgraph "Flask Application" 
            direction TB
            APP_FACTORY["Application Factory"]:::backend
            CONFIG_LOADER["Config Loader"]:::config
            subgraph "Blueprints (MVC)"
                direction TB
                MAIN_BP["main Blueprint"]:::backend
                USER_BP["user_system Blueprint"]:::backend
                SETTINGS_BP["settings_system Blueprint"]:::backend
                REST_BP["rest_api Blueprint"]:::backend
                ERROR_BP["error_pages Blueprint"]:::backend
            end
            PLATFORM["Platform Adapters"]:::backend
            TEMPLATES["Jinja2 Templates"]:::frontend
            STATIC["Static Assets"]:::frontend
        end

        %% Data Layer
        subgraph "Data & Migrations"
            direction TB
            DB["SQLite Database"]:::database
            MIGRATIONS["Alembic Migrations"]:::database
        end

        %% File Storage
        USER_DATA["user_data Folder"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PLEX["Plex"]:::external
        SONARR["Sonarr"]:::external
        WEATHER["Weather API"]:::external
        DOCKER_DAEMON["Docker Daemon"]:::external
        PING["Ping Service"]:::external
    end

    %% Deployment Files
    RUNPY["run.py"]:::config
    WSGI["wsgi.py"]:::config
    DOCKERF["Dockerfile"]:::config
    IGNORE[".dockerignore"]:::config
    TEMPLATE_APPS["template_apps/"]:::config
    INTERNAL_UTILS["dashmachine/paths.py"]:::config

    %% Relationships
    HOST_PORT -->|"exposes"| APP_FACTORY
    VOLUME -->|"mounts config & DB"| USER_DATA
    APP_FACTORY -->|"registers"| MAIN_BP
    APP_FACTORY -->|"registers"| USER_BP
    APP_FACTORY -->|"registers"| SETTINGS_BP
    APP_FACTORY -->|"registers"| REST_BP
    APP_FACTORY -->|"registers"| ERROR_BP
    MAIN_BP -->|"uses ORM"| DB
    USER_BP -->|"uses ORM"| DB
    SETTINGS_BP -->|"uses ORM"| DB
    REST_BP -->|"uses ORM"| DB
    ERROR_BP -->|"handles errors"| APP_FACTORY
    MAIN_BP -->|"calls"| PLATFORM
    USER_BP -->|"calls"| PLATFORM
    SETTINGS_BP -->|"calls"| PLATFORM
    REST_BP -->|"calls"| PLATFORM
    MAIN_BP -->|"renders"| TEMPLATES
    USER_BP -->|"renders"| TEMPLATES
    SETTINGS_BP -->|"renders"| TEMPLATES
    ERROR_BP -->|"renders"| TEMPLATES
    TEMPLATES -->|"serves static"| STATIC
    APP_FACTORY -->|"loads"| CONFIG_LOADER
    CONFIG_LOADER -.->|"reads/writes"| USER_DATA
    DB ..->|"schema migrations"| MIGRATIONS
    PLATFORM -->|"queries"| PLEX
    PLATFORM -->|"queries"| SONARR
    PLATFORM -->|"queries"| WEATHER
    PLATFORM -->|"queries"| DOCKER_DAEMON
    PLATFORM -->|"queries"| PING
    RUNPY -->|"entry point"| APP_FACTORY
    WSGI -->|"entry point"| APP_FACTORY
    DOCKERF -->|"builds image"| APP_FACTORY
    IGNORE -->|"patterns"| DOCKERF
    TEMPLATE_APPS -->|"provides .ini"| CONFIG_LOADER
    INTERNAL_UTILS -->|"shared paths"| APP_FACTORY

    %% Click Events
    click APP_FACTORY "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/__init__.py"
    click MAIN_BP "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/main/routes.py"
    click USER_BP "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/user_system/routes.py"
    click SETTINGS_BP "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/settings_system/routes.py"
    click REST_BP "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/rest_api/resources.py"
    click ERROR_BP "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/error_pages/routes.py"
    click PLATFORM "https://github.com/rmountjoy92/dashmachine/tree/master/dashmachine/platform/"
    click TEMPLATES "https://github.com/rmountjoy92/dashmachine/tree/master/dashmachine/templates/"
    click STATIC "https://github.com/rmountjoy92/dashmachine/tree/master/dashmachine/static/"
    click DB "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/site.db"
    click MIGRATIONS "https://github.com/rmountjoy92/dashmachine/tree/master/migrations/"
    click CONFIG_LOADER "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/main/read_config.py"
    click RUNPY "https://github.com/rmountjoy92/dashmachine/blob/master/run.py"
    click WSGI "https://github.com/rmountjoy92/dashmachine/blob/master/wsgi.py"
    click DOCKERF "https://github.com/rmountjoy92/dashmachine/tree/master/Dockerfile"
    click IGNORE "https://github.com/rmountjoy92/dashmachine/blob/master/.dockerignore"
    click TEMPLATE_APPS "https://github.com/rmountjoy92/dashmachine/tree/master/template_apps/"
    click INTERNAL_UTILS "https://github.com/rmountjoy92/dashmachine/blob/master/dashmachine/paths.py"

    %% Styles
    classDef backend fill:#BFDBFE,stroke:#1E3A8A,color:#1E3A8A,stroke-width:1px;
    classDef frontend fill:#DCFCE7,stroke:#166534,color:#166534,stroke-width:1px;
    classDef database fill:#FEF3C7,stroke:#92400E,color:#92400E,stroke-width:1px;
    classDef external fill:#FEE2E2,stroke:#991B1B,color:#991B1B,stroke-width:1px;
    classDef storage fill:#F3F4F6,stroke:#374151,color:#374151,stroke-width:1px;
    classDef config fill:#E0E7FF,stroke:#3730A3,color:#3730A3,stroke-width:1px;
```
