updates to digiserver app server
This commit is contained in:
@@ -0,0 +1,148 @@
|
||||
# 02 · The Graphify Knowledge Graph
|
||||
|
||||
This document explains the **interactive knowledge graph** generated by the [Graphify](https://marketplace.visualstudio.com/items?itemName=anytechiestudio.graphify-vscode) 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
|
||||
|
||||
1. In VS Code, click the **Graphify** activity-bar icon (sidebar).
|
||||
2. Click **Build Knowledge Graph** (or right-click any folder → *Graphify: Build Knowledge Graph*).
|
||||
3. 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](01-architecture.md#3-component-map-files--communities) 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:
|
||||
|
||||
```bash
|
||||
# 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](03-data-model.md)
|
||||
Reference in New Issue
Block a user