digiserver-v2/docs/README.md

DigiServer v2 — Project Documentation

Comprehensive technical documentation generated with Graphify — an interactive knowledge-graph engine for AI-assisted coding.

Version: 2.0.0 · Build date: 2025-11-12 · Generated: 2026-08-16

DigiServer v2 is a digital signage management server built with Flask. It manages media content (images, videos, PDFs, presentations), organizes it into playlists, assigns players (physical signage displays), and remotely deploys and monitors those players over SSH — including HTTPS/SSL provisioning via Caddy and an on-player photo-editing pipeline.

---

🗂 Documentation Index

Document	Purpose
01-architecture.md	System overview, layers, component map, architecture diagrams
02-knowledge-graph.md	Graphify graph: 41 communities, god nodes, and how to use the visualizer
03-data-model.md	Database schema: all 10 tables, relationships, ER diagrams
04-application-core.md	App factory, config, extensions, middleware, CLI, templates
05-blueprints-api.md	All 7 blueprints + full REST API reference
06-utils-services.md	Background tasks, SSH deploy, Caddy manager, player build, SSO, uploads
07-deployment.md	Docker, Caddy, deployment pipeline, HTTPS setup, verify script
08-workflows.md	End-to-end flows: upload, playlists, player edits, deployment, sync
09-legacy-and-migrations.md	Migration scripts, deprecated/archived components

Auto-generated Graphify artifacts (regenerate anytime — see 02-knowledge-graph.md):

graphify-out/
├── graph.html          ← Interactive visualizer (open in browser)
├── graph.json          ← Raw graph data (631 nodes / 1162 edges)
├── GRAPH_REPORT.md     ← God nodes, communities, knowledge gaps
├── COMPASS.md          ← Token-optimized architecture summary
├── DOMAINS.md          ← Community → domain mapping
├── intelligence.json   ← AI-detected insights (god nodes, surprises)
├── graph.compact.txt   ← Compact graph dump for LLM context
└── wiki/               ← Per-community + per-god-node Markdown articles
    ├── index.md
    ├── Community_0.md … Community_40.md
    ├── CaddyConfigGenerator.md, Content.md, HTTPSConfig.md,
    ├── PlayerEdit.md, PlayerUser.md, Playlist.md, User.md,
    ├── log_action().md, create_app().md …

---

⚡ Quick Facts

Metric	Value
Framework	Flask 3.1 + SQLAlchemy 2.0 (SQLite) + Gunicorn
Application type	Digital signage content/playlist/player management
Graph size	631 nodes · 1162 edges · 41 communities
Blueprints	7 active (main, auth, admin, players, content, playlist, api)
Database tables	9 (user, player, player_edit, player_feedback, player_user, content, playlist, server_log, https_config)
Reverse proxy	Caddy 2 (automatic HTTPS / Let's Encrypt)
Deployment	Docker Compose (app + Caddy) + remote SSH player provisioning
Key externals	LibreOffice, Poppler (pdf2image), FFmpeg, sshpass/rsync

---

🔑 Core Abstractions (Graphify "God Nodes")

Detected automatically from graph centrality:

1. log_action() — 116 edges · DB-backed audit logging (app/utils/logger.py)
2. PlayerEdit — 99 edges · on-player edit records (app/models/player_edit.py)
3. PlayerUser — 74 edges · player edit user mapping (app/models/player_user.py)
4. Playlist — 33 edges · playlist + versioning (app/models/playlist.py)
5. CaddyConfigGenerator — 31 edges · HTTPS Caddyfile generation (app/utils/caddy_manager.py)
6. HTTPSConfig — 30 edges · HTTPS settings model (app/models/https_config.py)
7. Content — 24 edges · media content model (app/models/content.py)
8. User — 19 edges · admin/user/viewer accounts (app/models/user.py)
9. create_app() — 13 edges · application factory (app/app.py)
10. app/models/__init__.py — 13 edges · models package export

---

🧭 Quick Navigation

The 7 Active Blueprints

Blueprint	Prefix	Responsibility
main	/	Dashboard + health check
auth	/	Login / logout / register / change password
admin	/admin	Users, HTTPS config, player build, logos, logs, leftovers
players	/players	Player CRUD, manage, edited media, deployment status
content	/content	Media library, uploads, playlist management (modern)
playlist	/playlist	Legacy per-player playlist routes (redirects)
api	/api	Player-facing REST API (auth, playlists, feedback, edits, deploy)

Data Model at a Glance

erDiagram
    user ||--o{ server_log : ""
    player ||--o{ player_feedback : "cascade"
    player ||--o{ player_edit : "cascade"
    player }o--o| playlist : "assigned"
    content ||--o{ player_edit : "cascade"
    content ||--o{ player_feedback : ""
    playlist ||--o{ content : "playlist_content (M2M)"
    player_user ||--o{ player_edit : "user_code"
    https_config ||--|| https_config : "single row config"

Proceed to 01-architecture.md for the full system overview and diagrams.