Software MRI

Inspiration

Every developer has opened an unfamiliar codebase and felt lost in the first ten minutes — where's the real entry point, which files are actually load-bearing, what's quietly rotting. Tools like GitHub show you what changed, and linters show you style violations, but nothing shows you the shape of a codebase the way an MRI shows the shape of a body — structure, complexity, and decay, all at once, at a glance. Software MRI is that instrument: point it at a repo, and it produces a real diagnostic scan instead of a wall of metrics nobody reads.

What it does

Software MRI takes a public GitHub repo URL and runs it through a real static-analysis pipeline — no AI, no guessing — producing:

• A 3D structural scan — every module rendered as a node on a rotatable sphere, sized by scope and colored by health, with real dependency edges (including circular dependencies, called out explicitly).
• A complexity layer — the same modules recolored by cyclomatic complexity, so risk hotspots are visible without reading a single line of code.
• A debt layer — dead code, unused exports, and unreachable branches surfaced as a ranked, explorable list.
• A computed diagnosis — a plain-language readout generated deterministically from the actual analysis output, telling you exactly where risk concentrates and what to prioritize. Click any node to zoom in, expand to fullscreen to explore a large repo in detail, and export the full analysis for your team.

How I built it

The frontend is React + Three.js (via 3d-force-graph) for the 3D scan, with GSAP driving every state transition — the scan sweep, the reveal sequence, the camera zoom into a selected node — so the whole experience feels like one continuous instrument rather than a dashboard with tabs.

The backend clones the target repo, then runs it through a real analysis pipeline: dependency-cruiser for the import graph and circular-dependency detection, escomplex for cyclomatic complexity, and ts-prune for dead code and unused exports. Every number and every sentence in the diagnosis readout is computed deterministically from that analysis — there is no LLM call anywhere at runtime.

How I used GPT-5.6 and Codex: [Fill in with specifics once built — judges score this directly. Name real moments, e.g.: "Codex scaffolded the dependency-cruiser integration and caught an edge case where indirect cycles through barrel files were being missed." / "Codex generated the GSAP Flip-transition timeline for the scan-bar-to-layer-toggle animation." / "Codex wrote the deterministic diagnosis-readout template engine and helped me cover edge cases like a fully clean repo with zero findings." Vague claims like "I used Codex a lot" will score worse than 2-3 concrete examples — and as a solo builder, this section is also your best way to show judges how much ground Codex let you cover alone.]

Challenges I ran into

My biggest challenge was visual, not technical: my first pass at the dependency graph was a 2D force-directed layout, and past a few dozen real nodes it collapsed into an unreadable "hairball" of crossing edges — it looked like a network diagram but didn't actually communicate anything. Rather than polish something that was fundamentally the wrong shape, I rebuilt the visualization from scratch as a rotatable 3D sphere with clustered, low-opacity edges that only light up on interaction — a much bigger change late in the build than I'd planned for, but the readability difference was worth the rework.

The second challenge was staying honest under pressure to look "AI-powered." It would have been faster to fake the diagnosis text with an LLM call, but that would have violated the whole premise of the product — so I had to build a real deterministic template engine that reads the actual analysis output (which folder has the most circular dependencies, which files exceed the complexity threshold) and composes a genuinely specific sentence from it, with enough branching logic to sound earned across very different repo shapes instead of generic.

Finally, building this solo meant simply scoping to a working end-to-end pipeline in the time available — cutting stretch features (like churn-vs-complexity hot-zone detection) the moment the deadline got close, so I always had something fully real and demoable rather than several half-finished layers.

Accomplishments that I'm proud of

I'm proud that Software MRI contains zero runtime AI calls yet still feels intelligent — every insight on screen, from the health score to the diagnosis sentence, is computed directly from real static analysis (dependency-cruiser, escomplex, ts-prune), not generated. Proving that "feels smart" and "actually AI-powered" don't have to be the same thing was the core bet of this project, and I think the final product makes that case.

I'm also proud of the pivot itself: recognizing mid-build that my original 2D graph wasn't working, and rebuilding it as a legible 3D diagnostic sphere instead of settling for a cosmetic fix, under real time pressure, as a team of one.

What I learned

I learned that a visualization has to earn its complexity — a force-directed graph looks impressive in a demo GIF but falls apart the moment you throw real, dense data at it, and no amount of color or glow polish fixes a layout that's fundamentally the wrong shape for the data. I also learned a lot about using Codex as a genuine engineering partner rather than a code-completion tool: the fastest progress came from giving it a precise, opinionated specification (down to exact color tokens and animation timing) rather than an open-ended prompt, and letting it own well-scoped chunks — like the dependency-graph integration or the GSAP transition timeline — end to end. Building solo, that partnership is what made the scope achievable at all.

What's next for Software MRI

• Private repo support with GitHub OAuth
• Churn-vs-complexity "hot zone" detection — cross-referencing git history with complexity to flag files that are both hard to understand and frequently changed, the combination most correlated with real production incidents
• Historical scan comparison, to track whether a codebase's health is improving or degrading over time
• CI integration — run the scan on every PR and flag when a change increases structural risk

Built With

• codex
• dependency-cruiser
• escomplex
• gpt5.6
• gsap
• node.js
• react
• simple-git
• three-js
• ts-prune
• typescript