Skip to content

feat: add human-friendly architecture dashboard#551

Open
kluacisco888 wants to merge 5 commits intosafishamsi:v4from
kluacisco888:feat/dashboard
Open

feat: add human-friendly architecture dashboard#551
kluacisco888 wants to merge 5 commits intosafishamsi:v4from
kluacisco888:feat/dashboard

Conversation

@kluacisco888
Copy link
Copy Markdown

Summary

  • Adds dashboard.py that generates a single-page HTML architecture overview from graph.json
  • Merges fine-grained Leiden communities into 5-10 macro-modules using hierarchical clustering + directory-aware grouping
  • Renders an interactive D3 force graph (clickable nodes), module cards, and PageRank-based reading order

Motivation

The current outputs (GRAPH_REPORT.md, graph.html) are optimized for AI consumption. For human team members — especially during onboarding — a 453-line report and a 1953-node force graph are overwhelming. This dashboard provides a simplified, human-first view of the same data.

What's included

New: graphify/dashboard.py (~500 lines)

  • merge_communities() — groups fine-grained communities into 5-10 macro-modules by cross-community edge density + directory structure
  • _macro_metadata() — extracts node count, file count, key files, top nodes, inter-module dependencies
  • _infer_module_name() — auto-names modules from directory structure and node labels
  • build_description_prompt() — generates a prompt for the host LLM to produce one-line business descriptions
  • _reading_order() — PageRank-based recommended reading order for new team members
  • generate_dashboard() — public API, accepts optional names and descriptions overrides
  • Single-file HTML output with D3.js force graph, dark theme matching graph.html

Modified: graphify/__main__.py

  • New graphify dashboard CLI command with --graph and --output flags

Modified: graphify/skill.md

  • New Step 6c: auto-generates dashboard during /graphify pipeline

Usage

graphify dashboard
graphify dashboard --graph path/to/graph.json --output path/to/dashboard.html
from graphify.dashboard import generate_dashboard
result = generate_dashboard("graphify-out/graph.json",
    names={0: "Auth Module", 1: "Data Pipeline"},
    descriptions={0: "Handles user authentication", 1: "ETL pipeline"},
    project_name="My Project")

Design decisions

  • No new dependencies — uses only NetworkX (already required) and D3.js (CDN)
  • Generic — works on any project's graph.json, no domain-specific logic
  • LLM-optional — auto-infers names from paths/labels, LLM descriptions are an enhancement
  • Dark theme — matches existing graph.html aesthetic

@kluacisco888 kluacisco888 force-pushed the feat/dashboard branch 3 times, most recently from ea6da92 to afe053a Compare April 25, 2026 12:20
Add dashboard.py that generates a single-page HTML architecture overview
from graph.json, designed for human team members and onboarding.

- Merges fine-grained Leiden communities into 5-10 macro-modules
- Auto-detects architectural layers (frontend/backend/engine/data/tools/tests)
- Renders Mermaid.js flowchart with layered subgraphs and directional arrows
- Module cards with key files, top nodes, and cross-module dependencies
- PageRank-based recommended reading order for new team members
- LLM-optional: auto-infers names, accepts override names and descriptions
- CLI: graphify dashboard [--graph path] [--output path]
- Skill: auto-generates in Step 6c of /graphify pipeline
- No new dependencies (Mermaid.js via CDN)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants