How GraphHub was built

Every developer has opened an unfamiliar repo and spent the first hour clicking through folders trying to build a mental model of the structure. GitHub's file tree forces you to navigate linearly. Search requires you to already know what you're looking for. Neither gives you the shape of the codebase.

GraphHub solves this by treating a repository as a graph problem. Folders, files, functions, and classes become nodes; imports and containment relationships become edges. The result is a living map you can explore rather than a hierarchy you navigate.

The constraint we set ourselves: no setup, no tokens, no configuration. Paste a URL — or just swap github.com for graphhub.dev — and the graph appears within seconds.

The entire pipeline — from GitHub API to rendered graph — is triggered by a single GET to /api/graph/:owner/:repo. The response is a serialised graph that the client can simulate and render without further API calls.

Three things keep this fast on repeat visits. The server cache is keyed by SHA, so it's safe to hold for 24 hours — the graph only changes when the repo changes. The HTTP response carries Cache-Control: s-maxage=3600, stale-while-revalidate=86400, so CDN and browser caches serve it without hitting the origin. And the client stores the graph in localStoragefor 30 minutes, so navigating back to a repo you've already visited is instantaneous — zero network, zero loading state.

The graph renders to a <canvas> element, not SVG or DOM nodes. At 500+ nodes, DOM-based graph libraries start dropping frames because the browser is reconciling thousands of elements per tick. A canvas is a pixel buffer — drawing 2,000 circles and lines per frame takes roughly 2ms, well within the 16ms frame budget for 60fps.

The tradeoff is real: no native hover states, no CSS transitions, no devtools inspection of individual nodes. We compensate with a d3-quadtree for O(log n) hit-testing, manual highlight state tracked in refs, and keyboard navigation with tabIndex=0 on the canvas element.

The render loop is a standard requestAnimationFrame tick. It reads node positions from the D3 simulation's mutable node array, runs the quadtree update, draws edges then nodes then labels (painter's algorithm), and schedules the next frame only if the simulation is still active. When the simulation cools (alpha < 0.001), the loop stops entirely. Interaction events (hover, select, drag, zoom) call requestRedraw() which re-enters the loop for exactly one frame — the canvas only repaints when something changes.

D3's force simulation runs in-process on the client. The physics are tuned per node type to produce a visual hierarchy that matches the code structure:

Folders carry a strong negative charge so they push each other to opposite ends of the canvas. Files are attracted to their parent folders via containsedges but repel each other enough to remain distinct. Functions and classes are lightly repelled — they cluster within their file's gravity well.

A custom cluster force pulls file nodes toward the centroid of their cluster on every tick, reinforcing the grouping without hard constraints. Node dragging pins a node's fx/fy coordinates and reheats the simulation; releasing unpins and lets it settle.

The parsing pipeline extracts structure from source files without executing them or requiring a language server. For each file, a language-specific parser reads the raw text and produces a ParsedFile containing imports, functions, classes, and exports.

We parse JavaScript, TypeScript, Python, and Go with reasonable accuracy across common patterns. The parser intentionally handles the 90% case well rather than attempting perfect coverage — edge cases like deeply dynamic imports or metaprogramming produce no nodes rather than wrong ones.

Import resolution is the most complex part. A relative import like ../../utils/parse needs to resolve to an actual file path in the tree. We do this without a file system by normalising the path relative to the importing file, then checking whether a matching path exists in the tree (with and without extension). External imports (packages, not relative paths) get their own node type rather than resolving.

The GitHub public API allows 60 unauthenticated requests per hour. Fetching a large repo can burn through this quickly. We handle it in two ways: the server cache means most requests never touch GitHub at all, and getFileContentsBatch sends files in parallel batches of 10, detecting 429 responses and surfacing a typed rate_limited error with a retryAfter timestamp rather than silently returning a partial graph.

Pure #000000 backgrounds feel harsh on a developer tool used for hours at a time. We use #0c0c0e (dark) and #fafaf9 (light) — fractionally warm grays that read like paper. The text and background values carry a very slight warm tint so they sit in the same colour temperature, preventing the eye-strain that comes from pure cool-on-warm contrast.

All colours are defined as CSS custom properties on :root and overridden on .dark. This means theme switching is one classList.toggle and a 200ms CSS transition — no JavaScript recalculation, no class name juggling per component. The graph canvas reads colour values at draw time via getComputedStyle, so it automatically inherits the active theme.

An inline <script> in the document head reads localStorage and sets .dark before first paint, preventing the flash of wrong theme that most dark-mode implementations suffer from.

Each node type has a fixed colour chosen for three properties simultaneously: distinguishability from other node types, readability against both the light and dark backgrounds, and coherence with the warm neutral palette.

These were the four decisions with the highest impact. Each one was a genuine fork in the road with real costs on both sides.

Scope discipline is part of engineering. These features were considered and deliberately left out of v1: