02 · The Graphify Knowledge Graph

This document explains the interactive knowledge graph generated by the Graphify extension, and how to use it to explore and maintain DigiServer v2.

1. What Was Generated

Running Graphify: Build Knowledge Graph on the project root produced graphify-out/:

Artifact	Description
`graph.html`	Interactive visualizer — zoom/pan/filter nodes, click to jump to source
`graph.json`	Raw graph data (nodes, links, communities, heat)
`GRAPH_REPORT.md`	God nodes, surprising connections, community list, knowledge gaps
`COMPASS.md`	Token-optimized architecture summary (god nodes, layers)
`DOMAINS.md`	Community ID → domain table
`intelligence.json`	AI-detected intelligence (god nodes, surprising links)
`graph.compact.txt`	Compact graph dump, ideal for LLM context
`wiki/`	Markdown articles per community + per god-node, with Mermaid diagrams

Graph statistics:

631 nodes · 1162 edges · 41 communities
Extraction: 56% EXTRACTED · 44% INFERRED (avg confidence 0.62)
Node types:  313 FUNCTION · 300 FILE · 18 CLASS
Link types:  311 uses · 290 calls · 275 rationale_for · 243 contains · 39 method · 4 inherits

2. Opening the Visualizer

In VS Code, click the Graphify activity-bar icon (sidebar).
Click Build Knowledge Graph (or right-click any folder → Graphify: Build Knowledge Graph).
Once built, click Open Interactive Visualizer — or open graphify-out/graph.html directly in a browser.

⚠️ The visualizer opens best inside the VS Code webview (activity bar). Opening graph.html via file:// may show a minor console error but still renders the graph data (nodes/edges/communities listed in the sidebar).

View modes: Deep Dive · Full Detail · Heatmap · Simulation (component-removal impact).

3. God Nodes — The Core Abstractions

These are the most-connected nodes (graph centrality). They are the architectural "load-bearing" abstractions:

Rank	Node	Degree	File	Why it matters
1	`log_action()`	116	`app/utils/logger.py`	Every important action across all blueprints logs here
2	`PlayerEdit`	99	`app/models/player_edit.py`	Central record of on-player media edits
3	`PlayerUser`	74	`app/models/player_user.py`	Maps player edit user codes to names
4	`Playlist`	33	`app/models/playlist.py`	Core content organization + version sync
5	`CaddyConfigGenerator`	31	`app/utils/caddy_manager.py`	HTTPS Caddyfile generation/reload
6	`HTTPSConfig`	30	`app/models/https_config.py`	Persisted HTTPS settings
7	`Content`	24	`app/models/content.py`	Media model used by everything
8	`User`	19	`app/models/user.py`	Human accounts (admin/user/viewer)
9	`create_app()`	13	`app/app.py`	Application factory
10	`models/__init__.py`	13	`app/models/__init__.py`	Package export hub

4. Heatmap — Hottest Code

heat (0–1) reflects how central/complex a node is in the graph. The hottest functions drive most of the system's behaviour:

Heat	Function	File
0.620	`receive_edited_media()`	`app/blueprints/api.py`
0.614	`deploy_player_to_host()`	`app/utils/ssh_deploy.py`
0.592	`add_player()`	`app/blueprints/players.py`
0.537	`upload_media()`	`app/blueprints/content.py`
0.429	`manage_player()`	`app/blueprints/players.py`
0.425	`receive_player_feedback()`	`app/blueprints/api.py`
0.407	`update_https_config()`	`app/blueprints/admin.py`
0.376	`process_file_in_background()`	`app/blueprints/content.py`
0.365	`CaddyConfigGenerator`	`app/utils/caddy_manager.py`
0.354	`get_playlist_by_quickconnect()`	`app/blueprints/api.py`

5. Communities (Clusters)

Graphify groups related code into communities. See 01-architecture.md §3 for the full mapping. The largest:

C0 · Auth & logging (90 nodes) — login/logout/register + audit logging + legacy groups
C1 · Admin & HTTPS (80 nodes) — admin panel, Caddy generation, editing users
C2 · Playlists & content (68 nodes) — the modern content/playlist workflow
C3 · Player API & edits (62 nodes) — player-facing REST + edited-media pipeline
C4 · Application core (55 nodes) — create_app, config, user, middleware
C5 · Content/player models (54 nodes) — Content, Player, feedback, dashboard

Each community has a wiki article with a Mermaid class diagram, key concepts, source files, and an audit trail (extracted vs inferred edges). Example: graphify-out/wiki/Community_4.md.

6. Surprising Connections (AI-detected)

Graphify flags links that are non-obvious. Examples from GRAPH_REPORT.md:

reset_user_password() → log_action() — admin password resets are audited
upload_header_logo() → log_action() — logo changes are audited
delete_editing_user() → log_action() — editing-user deletion is audited
delete_playlist() → log_action() — playlist deletion is audited
Main playlist management page uses PlayerEdit — the content UI surfaces edit counts

Pattern: virtually every destructive/admin action flows through log_action(), which is why it is the #1 god node.

7. Known Gaps in the Graph

178 isolated nodes (≤1 connection) — mostly standalone migration scripts and model helper methods.
Thin communities 13–40 — single-file migrations, isolated utility functions, and archived old_code_documentation/ scripts. These are not "broken" — they are intentionally decoupled.
The graph does not index templates or static assets (Python AST extraction only).

8. Querying the Graph (CLI)

The anytechie-graphify engine (installed in .venv) ships a CLI for graph-aware questions:

# Shortest path between two nodes
python -m graphify path "Content" "Playlist"

# Explain a node and its neighbours
python -m graphify explain "deploy_player_to_host()"

# BFS traversal to answer a question (no LLM)
python -m graphify query "how is a playlist synced to a player?"

# Grounded chat over the graph (requires an LLM API key)
python -m graphify ask "what happens when a player uploads edited media?"

9. Keeping the Graph Fresh

After code changes: Graphify: Build Knowledge Graph again (or run python -m graphify update <path>).
Git hooks: python -m graphify hook install auto-rebuilds on post-commit/post-checkout.
The graph is stored in graphify-out/ (not committed to git by default).

Next: 03 · Data Model

6.7 KiB Raw Blame History Unescape Escape