# DigiServer v2 — Project Documentation

> **Comprehensive technical documentation generated with [Graphify](https://marketplace.visualstudio.com/items?itemName=anytechiestudio.graphify-vscode)** — 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**](01-architecture.md) | System overview, layers, component map, architecture diagrams |
| [**02-knowledge-graph.md**](02-knowledge-graph.md) | Graphify graph: 41 communities, god nodes, and how to use the visualizer |
| [**03-data-model.md**](03-data-model.md) | Database schema: all 10 tables, relationships, ER diagrams |
| [**04-application-core.md**](04-application-core.md) | App factory, config, extensions, middleware, CLI, templates |
| [**05-blueprints-api.md**](05-blueprints-api.md) | All 7 blueprints + full REST API reference |
| [**06-utils-services.md**](06-utils-services.md) | Background tasks, SSH deploy, Caddy manager, player build, SSO, uploads |
| [**07-deployment.md**](07-deployment.md) | Docker, Caddy, deployment pipeline, HTTPS setup, verify script |
| [**08-workflows.md**](08-workflows.md) | End-to-end flows: upload, playlists, player edits, deployment, sync |
| [**09-legacy-and-migrations.md**](09-legacy-and-migrations.md) | Migration scripts, deprecated/archived components |

**Auto-generated Graphify artifacts** (regenerate anytime — see [02-knowledge-graph.md](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 | 10 (`user`, `player`, `player_edit`, `player_feedback`, `player_user`, `content`, `group`, `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

```mermaid
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)"
    content }o--o{ group : "group_content (M2M)"
    player_user ||--o{ player_edit : "user_code"
    https_config ||--|| https_config : "single row config"
```

> **Proceed to [01-architecture.md](01-architecture.md)** for the full system overview and diagrams.