How rmountjoy92/dashmachine works
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