The Problem: Lost in the GitHub Jungle
I was trying to contribute to an open-source project—a massive Next.js monorepo with thousands of files. I spent 3 days just trying to figure out:
Where is the main entry point?
Why does this utility file import from 7 different places?
What the hell is this lib/legacy/utils-deprecated/old_v2 folder even for?
I tried:
Eraser.ai → Hit paywall after 3 tries.
VS Code dependency graphs → Useless for large repos.
Manual Mermaid diagrams → Took hours, then the code changed.
I needed a tool that:
✅ Visualized any GitHub repo in one click
✅ Showed file dependencies clearly
✅ Let me export diagrams (PNG, PDF, Mermaid)
✅ Was free & open-source (no paywalls)
So I decided to build it myself.
The 1-Month Struggle: How This Tool Came to Life
Week 1: "This Should Be Easy, Right?" (Spoiler: It Wasn’t)
Step 1: Fetching GitHub Repo Data
First Attempt: Used GitHub’s REST API.
Problem: Rate limits (60 requests/hour).
Solution: Switched to GitHub GraphQL API (more efficient).
Second Attempt: Recursively fetching directories.
Problem: Nested folders made it messy.
Solution: Tree traversal algorithm to map all files.
Step 2: Building the Visualizer
First Idea: Use D3.js for graphs.
Problem: Too complex for my needs.
Final Choice: React Flow (perfect for interactive node-based UI).
Challenge: Making it zoomable, pannable, and responsive.
Solution: Custom viewport controls + auto-layout.
Week 2: "Why Is Everything Breaking?"
Step 3: Dependency Mapping
Goal: Show which files import which.
Problem: Parsing imports from raw code.
Solution: Used regex (for simple cases) + Babel AST parsing (for complex JS/TS).
Step 4: Mermaid Diagram Generation
Dream Feature: One-click Mermaid export.
Struggle: Mermaid syntax is whitespace-sensitive.
Breakthrough: Built a custom converter from React Flow → Mermaid.
Step 5: File Previews & Syntax Highlighting
Problem: Displaying code nicely.
Solution: Used Monaco Editor (same as VS Code).
Week 3: "I Hate PDF Export Now"
Step 6: Exporting Diagrams
PNG Export: Easy with html2canvas.
PDF Export: A nightmare.
Tried jsPDF → Ugly, broken layouts.
Tried Puppeteer → Overkill.
Final Solution: html2canvas + PDF stitching.
Step 7: Performance Optimizations
Problem: Large repos (10k+ files) crashed the browser.
Fix: Virtualized rendering (only load visible nodes).
Week 4: "It’s Alive… Mostly"
Final Touches
Dark/Light Mode → Because devs love options.
File Type Colors → JS = yellow, CSS = blue, etc.
Error Handling → When GitHub API fails, show useful errors.
The Launch
Deployed on Netlify → Instant live demo.
The Final Product: What It Does Now
Repo Visualization
Drag, zoom, pan like Google Maps for code.
Dependency Graph
See what imports what.
Mermaid Export
PDF/PNG Export
For presentations & documentation.
Live: https://sourcecodeatlas.netlify.app/
Lessons Learned (So You Don’t Suffer Like I Did)
Start small → MVP first, polish later.
GraphQL > REST for GitHub API.
React Flow is amazing for node-based UIs.
PDF export will always suck—accept it.
Top comments (0)