Repo-Verse: Your Codebase as a Solar System

A file tree is an honest representation of a project and a terrible picture of one. It shows every name and no proportion. You cannot see from a tree that one folder holds two-thirds of the code, that a single utility file has quietly grown to four thousand lines, or that the test directory is a thin ring of tiny files orbiting far from everything else.

Repo-Verse draws the proportion. Point it at a project folder and it reads the directory on your own machine, measures every file, and builds a 3D solar system: the root as a central star, folders as gas giants with their children in orbit, and each file as a planet whose size, colour, distance and rings come from its actual metadata.

The mapping is arithmetic, not decoration

Nothing here is arbitrary styling. Each visual property is a function of something real about the file:

| File attribute | Celestial property | |---|---| | Size in bytes | Planet radius — `clamp(1 + log10(bytes + 1) × 0.5, 0.3, 5)` | | Directory depth | Orbital distance from the core | | Extension | Colour and planet archetype | | Line count | Rolled up into folder mass | | Estimated complexity | Rings around the planet | | Last modified | Recency shown in the info panel |

The logarithmic size curve matters more than it sounds. Linear scaling means a single 2 MB asset makes every source file an invisible speck; a log curve keeps a 40 KB module clearly larger than a 2 KB one while still letting the genuinely huge files dominate.

Extensions pick the archetype, so language shows up as texture and colour: JavaScript burns star-yellow with banded surfaces, Python is a cool blue ice world, Rust is hot orange rock, Go is an ocean, Java is volcanic, Markdown is forest green, JSON is faceted crystal, CSS is a pink nebula. The textures are drawn procedurally onto small canvases at load time — there is no texture pack to download.

Reading a folder without uploading it

Source code is the one thing most developers genuinely cannot paste into a random online tool. It is usually someone's intellectual property, and it routinely contains API keys, connection strings and internal hostnames. Any visualiser that requires an upload is unusable at work for exactly that reason.

Repo-Verse never uploads, because it does not have anywhere to upload to. `window.showDirectoryPicker()` hands the page a permission-gated handle to the directory you chose, and the tool walks it recursively in the tab: reading sizes and modification times for everything, and reading contents only for text files under half a megabyte in order to count lines, estimate branching complexity, and pick up `import` and `require` statements for the dependency graph.

Three ingestion routes exist, in descending order of capability:

• Open folder (File System Access API, Chrome and Edge) — full read plus write-back saving, and access to `.git`.
• Choose folder (the older `webkitdirectory` input) — reads everything, but edits download as a copy rather than saving in place.
• Archive — a `.zip` unpacked client-side with JSZip, useful for a repo someone sent you.

Folders like `node_modules`, `.git`, `dist`, `build`, `target`, `__pycache__` and `.venv` are skipped by default, and that ignore list is an editable text box, not a hard-coded rule.

Making a twenty-thousand-file repo hold 60fps

Naively rendering one sphere per file falls apart around a few thousand draw calls. Repo-Verse ranks nodes by depth and size, gives the top ~1,200 real geometry, and turns everything else into a single coloured point cloud — an asteroid belt of small files, positioned by the same orbital formula. Nothing is silently dropped: the HUD tells you how many files became belt dust, and they are still in the file tree, the metrics and the exports.

Beyond that, geometry is shared across bodies at three levels of detail, textures are cached per colour-and-archetype pair rather than per file, and orbit rings are drawn only for the first two depth levels, because past that they are noise.

Clicking a planet opens the file

Selecting a body shows its path, size, line count, depth, complexity, language, planet type and modification date. Double-clicking focuses the camera on it and opens it in an embedded Monaco editor — the same editor core that VS Code uses — in a draggable glass panel over the scene.

If the project came in through the File System Access API, that editor is writable. Press Ctrl+S, the browser asks for read-write permission the first time, and the file is written back to disk through `createWritable()`. No round trip, no temporary copy on a server. If the project came from an archive or the fallback picker, the editor stays read-only and saving downloads the edited file instead — which is the honest behaviour, since there is no handle to write through.

Markdown and HTML files also get a preview toggle, with HTML rendered inside a fully sandboxed iframe.

Watching the repository evolve

If the folder contains a `.git` directory, Repo-Verse reads the commit log with isomorphic-git and puts a scrubber along the bottom of the scene. Drag it and planets appear and disappear as files enter and leave the tree; press play and the repository builds itself in front of you, commit by commit.

Making that work needed a small adapter: isomorphic-git expects a Node-style `fs.promises` API, and the browser offers directory handles. Repo-Verse implements the read half of that interface — `readFile`, `readdir`, `stat`, `lstat` — on top of the File System Access API, and deliberately implements the write half as functions that throw. The repository is opened read-only by construction, not by policy. Your history cannot be altered by a visualiser that has no code path to alter it.

Five ways to look at the same project

• Solar system — the default; one project as a planetary system.
• Galaxy — every loaded project at once, for comparing two codebases side by side.
• Graph — a force-directed 3D layout of files linked by their internal imports. Package imports are excluded on purpose, so what you see is your own coupling rather than your dependency tree.
• Timeline — the git time-warp described above.
• Stats — a dashboard with summary cards, a language donut, an extension bar chart and a size treemap, all drawn on plain canvases.

Everything exports: a PNG screenshot or a 2× render, an eight-second WebM orbit recorded from the canvas with MediaRecorder, a `.repo-verse` JSON dump of the whole tree and its metrics, a per-file CSV, and a Markdown report you can drop straight into a wiki page.

What it tells you about your own code

Load a project you know well. The things that jump out are rarely the things you would have predicted: the config folder that is somehow the third-largest system, the one component file that has become a gas giant, the module ringed with complexity markers that everyone has been avoiding, the corner of the graph where four files import each other in a knot.

None of that is new information — it was all in the directory listing. It just was not visible until size, depth and coupling were drawn as distance, mass and light.