Editor's architecture and codebase explanation

[selvaprakash]

hey, I found this project from github trending. Thought it's a great work.
I'm working on revibe.codes - a platform to understand any codebase using architecture diagram, user journey and guided code navigation. This is what I got. Please check if it makes sense. It would be great if you can add this link to the README file. You could add architecture diagram as well as it would give better info to other devs.

[Aymericr]

Thanks for taking the time to run Pascal through revibe and for sharing the output.

I read through the generated map. It gets the broad shape right — the package split, that scene state is centralized, that rendering is React Three Fiber over a WebGPU renderer. Where it is less reliable is the parts that actually matter for contributing: the derived-system boundaries, and which store owns what. A couple of examples so this is concrete rather than a vague objection:

• Scene data lives in useScene (@pascal-app/core) while view and interaction state lives in useViewer (@pascal-app/viewer). That split is the single most load-bearing convention in the codebase and the diagram does not distinguish them.
• The node plugin registry is what makes node types extensible; walls, fences, cabinets and so on are registered plugins in @pascal-app/nodes, not hardcoded branches. A reader working from the diagram would not know to add a node type there.

On adding the link to the README: I would rather not. Not a knock on the tool — it is that a generated snapshot drifts silently from the code, and a README link implies we are keeping it accurate. When someone hits a stale diagram from an official pointer, that costs us more than the diagram saved. Our own architecture docs are versioned with the source in wiki/architecture/, so they move when the code moves.

You are very welcome to keep the link in this discussion, which is exactly what Show and tell is for, and anyone searching will find it. If you want to contribute something durable to the README, a PR improving wiki/architecture/ with a hand-checked diagram would be genuinely valuable and we would review it.

[selvaprakash]

Thanks Aymeric, for taking time to review the output and provide your feedback.
I'll check the problems you pointed out. I agree that README should have the latest version of the architecture always. The tool has the capability to watch for every commit and update the diagram if required. But I wouldn't do now as the current version itself has the gaps you've mentioned. I'll check the wiki/architecture/ and come back with better hand-checked diagrams.

[Aymericr]

That's a good call on holding the commit-watching until the gaps are closed — a diagram that auto-updates while being wrong about the store boundaries would propagate the error faster than it fixes it.

Since you're going to hand-check, start at wiki/architecture/README.md. It's an index of ~19 pages with a one-line scope for each, plus a suggested reading order, so it'll orient you faster than crawling the tree. The pages most relevant to the gaps I mentioned:

• node-definitions.md — the registry-driven composition model for node kinds (geometry / renderer / system). This is the one I'd read first; it's what makes "add a node type" a plugin registration instead of a code branch.
• viewer-isolation.md — why @pascal-app/viewer stays editor-agnostic and is driven from outside via props/children. This is the boundary the generated map collapsed.
• interaction-scope.md — the authoritative interaction state machine, called "the spine" internally. If you want one page that explains how a click becomes a scene change, it's this one.
• layers.md — Three.js layer ownership. There's a constraint in here no static analysis could infer: editor overlay and hit-area meshes must sit on EDITOR_LAYER, because putting them on the scene layer corrupts the multi-render-target pass and makes solid geometry render see-through. That class of invariant only ever surfaces as a bug report.

One correction to my own earlier comment while I'm here: I described the node model from memory as geometry / renderer / tool. The third checkbox is system, per node-definitions.md. Worth having right if you're diagramming it.

A framing suggestion, offered as a would-be consumer rather than a critic: the highest-value output for a newcomer probably isn't the whole-system diagram — it's "where do I add a thing of type X". Node kinds, tools, and panels each have a canonical registration point, and a reader who finds those three has enough for most first contributions. A correct partial map is both easier to produce and more useful than a complete one.

Happy to look at a revised version if you post it here. And to be clear on the README: my hesitation was about the maintenance contract, not the quality of the work — if you land something hand-checked that stays accurate, I'm open to revisiting where it gets linked from.