docs(readme): add build-order and binary-anatomy diagrams#124
Open
mix irving (mixmix) wants to merge 5 commits intomainfrom
Open
docs(readme): add build-order and binary-anatomy diagrams#124mix irving (mixmix) wants to merge 5 commits intomainfrom
mix irving (mixmix) wants to merge 5 commits intomainfrom
Conversation
Two SVG diagrams introduce engineers to the monorepo at a glance: build-tiers.svg shows how native libraries (curl + LIEF) flow up through stubs and the binary suite into the custom Node.js binary, and binary-anatomy.svg shows how a compressed on-disk stub decompresses into the runtime + SEA blob + VFS section in memory. Uses the Socket purple-to-pink brand gradient.
Match the surrounding prose, which puts native libraries at the bottom and the custom Node.js binary at the top. Arrows now point upward, gradient runs pink-at-top to purple-at-bottom so each tier keeps its identity color (T4 pink, T1 purple).
The whole shipped binary IS the SEA — make that explicit in the right-hand box label. Mark the compressed launcher as optional (produced by binpress) since the default node-smol-builder build is the raw runtime. Clarify the stub's role (zstd decompressor; libcurl + mbedTLS is for optional update checks, not for the decompression itself). Note that the SEA blob and VFS section are siblings injected side-by-side by binject.
The arrows in the previous version mixed two semantics: the bottom two (curl/lief into stubs) were real code dependencies, but the upper arrows (stubs into binsuite, binsuite into node-smol) were not — node-smol doesn't depend on the binary suite, and binject / binflate don't depend on stubs. The four-tier model is a publish dispatch order (cache cascade for releases), not a strict dependency DAG. Drop the arrows entirely; let the visual stacking carry the meaning, and have the subtitle state exactly what the stacking represents. Every visual element now has one consistent meaning.
Two changes pitched at engineers new to binary manipulation: 1. Rewrite the binary-anatomy diagram as a CONSTRUCTION view — shows binject's action explicitly (inputs on the left, the merged SEA on the right) with a clear visual language: solid borders for real files on disk, dashed borders for virtual files embedded inside the binary. The VFS section now lists concrete example files so it's obvious what 'embedded files' means in practice. 2. Add a new lifecycle diagram showing what actually happens at run time — stub decompresses, runtime boots and reads the SEA blob + VFS, app produces output. Action-labeled arrows between three stages (on disk · in memory · output).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two SVG diagrams introduce engineers to the monorepo at a glance:
build-tiers.svg shows how native libraries (curl + LIEF) flow up
through stubs and the binary suite into the custom Node.js binary,
and binary-anatomy.svg shows how a compressed on-disk stub
decompresses into the runtime + SEA blob + VFS section in memory.
Uses the Socket purple-to-pink brand gradient.