VibeX: the architecture diagram you never have to draw

ERDs, C4 models, API catalogues and state machines generated from the schema that actually ships - plus documentation that fails CI when it drifts. One standalone HTML file, no server, zero outbound requests. Somebody asks where the order state actually lives. You open the Confluence page. It was last edited in 2023, by someone who left in 2024, and it describes four tables that are now six. So you do the honest thing and read the schema. Twenty minutes later you have the answer, and you don't write it down, because writing it down is how you get another Confluence page that's wrong in 2027. I got tired of that loop. vibeX is what came out: point it at a schema you already have and it renders the map - as a single HTML file you can email, commit, or open with the cable pulled out of the wall. npx @vibex/vibex demo out && open out/dashboard.html That renders a complete example system before you point it at anything of your own. Four diagrams, from files you already have hree importers do it in one pass - OpenAPI 2/3, GraphQL SDL (own parser), Prisma. No schema to import? It reads controllers, entities, resolvers and migrations and writes the spec itself. The spec is the artifact worth keeping. It's JSON, it validates against a schema, and you edit it like a human: rename a group, drop the health check, write a real description on the thing nobody understands. The HTML is disposable - re-render it whenever. vibex import prisma schema.prisma db.erd.json vibex validate db.erd.json # errors name the field; warnings never block vibex render db.erd.json # → db.erd.html It's a viewer, not a picture A PNG of a 40-table schema is a wall. Every diagram ships as one self-contained file that you can actually interrogate: pan, zoom and fit; / to search any table, route or state by name; click a node for its columns, params and relationships; deep links that address one node in one diagram (#node=orders ); and a jump-to-source link on every node that opens the exact file and line on GitHub or GitLab. One folder in, one dashboard out vibex dashboard docs/index.html specs/ --title "Relay" --repo . Every spec in the folder becomes a panel, grouped by what it is, with a totals strip across the top and entity↔endpoint cross-links underneath - click an endpoint, see which tables it touches. The demo system above is 9 diagrams, 96 nodes, 77 connections and 30 cross-links, and it is still one HTML file. Email it. No account, no seat, no expiry. The part that isn't a diagram Diagrams can't drift, because they're derived. Prose drifts, always. So documentation here isn't a page - the unit is a claim: one sentence with its source attached. A claim is derived from a spec, anchored to a file by a content hash that ignores whitespace, or asserted by a named person with a date and an expiry. And a claim may never declare how trustworthy it is - the build computes that, and prints one of verified, stated, needs re-reading, out of date or unverifiable. vibex docs system.docs.json specs/ --repo . --check # exit 1 on drift On the demo system that's 153 claims in 70-90 ms, Node's own startup included. It's that fast because there is no model in the verification path - just fs , crypto and git . Reformat a file and nothing moves, because the hash ignores whitespace. Change the line the claim was pinned to and the claim flags itself and the build goes red. Straight about the limit: this catches staleness, not initial error. If the first draft misreads your code, the hash still matches, CI stays green, and a wrong claim can sit there verified indefinitely. Reading the spec once, at authoring time, is the only thing that establishes truth. The honest version of the pitch is: you get a reviewable first draft in one pass, and after you've read it once, arithmetic keeps it honest. An AI wrote the sentence once. Arithmetic checks it forever. The way you actually use it Everything above is a CLI, and I'd rather you never touched it. vibeX is a Claude Code / Cursor skill first - SKILL.md ships inside the package, so it's a global install and one symlink: npm i -g @vibex/vibex ln -s "$(npm root -g)/@vibex/vibex" ~/.claude/skills/vibex > show me the data model wrote db.erd.json · db.erd.html > what happens after a request is approved? wrote request.lifecycle.json · request.lifecycle.html You didn't pick a diagram type or learn a flag. The diagrams are the output; not having to think about producing them is the product. It never leaves your network The generated HTML makes zero outbound requests. No CDN, no web fonts, no analytics, no telemetry. PNG export renders through an in-memory blob. Unplug the network and it still pans, zooms, searches and exports. That isn't minimalism for its own sake. An architecture diagram is a reconnaissance map of your system - every table, every internal route, every auth boundary - and it's exactly the thing you can't paste into someone else's SaaS. There's no server, no vendor and no DPA, because there's nowhere for it to go. Where it stands MIT, Node 18+, zero required dependencies (one optional - yaml , and only if your OpenAPI file is YAML rather than JSON). vibex changelog builds release notes from git history and, with --specs , says which parts of the documented system each commit touched. Every claim and node carries a report link that opens an issue naming exactly what the reader was looking at, so corrections arrive with coordinates instead of "the auth docs seem wrong". What's not there yet: a GitHub Action that regenerates on every pull request, and anything clever about very large monorepos. VibeX - if you try it on a real codebase, I want to hear where it fell over. Top comments (0)