Repo-Viz — Repository Visualization

Dependencies: gitnexus (codebase analysis), d2 (diagram rendering), npx/Playwright (hero images) All installed: gitnexus at ~/.npm-global/bin/gitnexus, d2 at ~/.local/bin/d2

When to Use

• Creating architecture diagrams for READMEs
• Generating hero images for blog posts / social cards
• Visualizing module dependencies and call chains
• Quick visual overview of unfamiliar codebases

Pipeline

Step 1: Analyze the repo

cd /path/to/repo
gitnexus analyze

Step 2a: Technical Diagram (D2)

# Create a .d2 file from analysis, then render
d2 --theme 200 --pad 60 --scale 3 input.d2 output.png

# Common themes: 200 (dark), 0 (default), 300 (terminal)
# Layouts: dagre (default), elk, tala
d2 --layout elk --theme 300 diagram.d2 diagram.svg

Step 2b: Hero Image (HTML → Playwright)

# Create an HTML/CSS hero card, then screenshot
npx playwright screenshot --full-page --viewport-size="1200,630" hero.html output.png

D2 Quick Reference

# Shapes
server: API Server { shape: rectangle }
db: Database { shape: cylinder }
queue: Task Queue { shape: queue }

# Connections
server -> db: queries
server -> queue: enqueue
queue -> worker: process

# Styling
server.style.fill: "#4A90D9"
server.style.stroke: "#2C5F9E"

Tips

• Use gitnexus get_clusters output to identify key module boundaries
• D2 supports nested containers for architectural layers
• For social cards, use 1200×630 viewport (OG image standard)
• Playwright can render any HTML, not just D2 — use for custom hero images

When NOT to Use

• Repos with < ~5 meaningful modules — a diagram adds no value over reading the file tree
• Generating diagrams for a repo you haven't analyzed with gitnexus first — blind D2 files produce inaccurate architecture
• Quick one-liner README updates — overhead of the full pipeline isn't worth it

Pitfalls

• D2 not on PATH — d2 installs to ~/.local/bin/; if the shell doesn't include it, all render commands silently fail. Fix: export PATH="$HOME/.local/bin:$PATH" or use the full path
• Playwright Chromium not installed — npx playwright screenshot fails with "Executable doesn't exist" until you run npx playwright install chromium; this is a one-time setup step that's easy to forget in a fresh environment
• gitnexus analyze on a huge monorepo — can take several minutes and produce thousands of nodes; scope it with --depth or --include flags to avoid unreadable diagrams
• D2 syntax errors silently produce blank output — always check the exit code; a zero-byte PNG means the .d2 source is invalid, not that rendering succeeded
• OG image viewport mismatch — Playwright's --viewport-size flag uses WIDTHxHEIGHT (no comma); passing 1200,630 instead of 1200x630 silently uses the default 1280×720 and crops your card wrong

Verification

# Confirm tools are reachable
which d2 && d2 --version
which gitnexus || ls ~/.npm-global/bin/gitnexus
npx playwright --version

# Confirm Chromium is installed for Playwright
npx playwright install --dry-run chromium 2>&1 | grep -i "already installed\|chromium"

# Smoke-test D2 render (should produce a non-empty PNG)
echo 'a -> b' | d2 - /tmp/test-d2.png && ls -lh /tmp/test-d2.png

• Open the output PNG/SVG and verify it's not blank or corrupt before embedding in a README