ArchStudio 1.0.0

ArchStudio 1.0.0

Draw the architecture once. Send the document.

The first stable release. A self-hosted studio for architecture documentation: organise many
architectures in folders, build each one by dragging components onto layers, and export a
self-contained HTML file anyone can open — or print the same architecture as a numbered design
document.

npm install
npm run dev          # http://localhost:3000

That is the whole setup. No database server, no accounts, no cloud. A SQLite file appears at
data/studio.db on first run, seeded with one example architecture so the editor has something
to open.

---

What ships in 1.0

The studio

Workspace. Every architecture is a project. Projects live in nested folders you create; drag
a project card onto a folder in the sidebar to move it. Search across all of them.

Editor. Layers are rows; drag components between them, drag a component onto another to
reorder, drag the dot under a card onto another card to create a dependency. The inspector on the
right edits whatever is selected. Nothing has a Save button — edits persist 700 ms after you stop
typing.

Dependencies that say how, not just who. A dependency takes a protocol, a note, and one of
three kinds — synchronous, asynchronous, batch. The kind is drawn rather than written: a solid
line waits for its answer, a dashed one is queued, a dotted one is scheduled. It is the stroke and
not the colour, because colour already means scope and a dash survives a monochrome print. All of
it is optional; an edge nobody annotated draws exactly as it always did.

History. Every save older than five minutes since the last one writes a snapshot. The History
panel lists them and, for each, what changed since it — components added and removed, renames,
moves between layers, edges gained and lost. Name a version ("sent to the client") and it is kept
for good; the 30-snapshot cap only prunes automatic ones. Restoring writes a Before restore
snapshot first, so a restore is itself undoable.

Preview. The preview tab is not a re-implementation. It renders, in an iframe, byte-for-byte
the file you get when you click Export. One renderer, no drift between what you see and what you
ship.

Export. A single self-contained HTML file (235–240 KB, no external requests) you can email,
attach to a ticket, commit, or host anywhere. "No external requests" includes the typefaces:
Archivo and Space Mono are inlined as base64, which is why the file looks like the studio on a
machine that has never heard of either. Raw JSON and a standalone architecture.js data file
export too.

Import. Accepts JSON or a window.ARCHITECTURE = {…} data file. Paste it or pick the file.

The diagram at scale

Past about two dozen components the diagram reorganises itself. Each layer splits into one column
per scope instead of one long wrapping row, and cards drop to their icon and name so twice as many
fit — both switchable from the toolbar, both settable up front with ui.architecture.cluster and
ui.architecture.compact.

The sheet also gains a scale. Fit finds the largest size at which the whole thing is on screen
at once, Ctrl (or ⌘) and the wheel zooms, dragging the paper pans it, and the last button takes
the diagram full screen — with its toolbar, because a full screen you cannot filter or zoom is a
poster. Zooming out reflows rather than shrinking away from the frame, so a smaller scale means
more components per row and not just smaller type. Filtering by scope removes emptied columns
rather than fading them, so the drawing actually gets shorter when you narrow it. Printing ignores
all of it and lays the diagram out whole, at 1:1.

Six templates, five deployment targets

"New project" opens two steps: pick a starting point, then name it and aim it at a deployment
target.

Template	Components	What it answers
Serverless MVP	15	"We launch in six weeks, we are two, we do not want servers"
Multi-tenant B2B SaaS	18	"Several customer companies on one platform, isolated"
RAG — questions over documents	17	"Answer questions about our own corpus"
Event-driven processing	16	"Streams, queues, decoupling, replay"
Modular monolith	14	"One deployable application, well partitioned inside"
Multi-service architecture	19	"Several teams, several services, each with its own data"

Each carries components, dependencies, flows and three to four written sections — the comparison
of tenancy isolation models, the delivery-guarantee table, the "when to leave serverless"
thresholds. That editorial content is the point; the boxes are the easy part.

Six templates, not thirty. A template describes an abstract architecture, and every
component carries a per-target correspondence table. The target — vendor-neutral, AWS, Google
Cloud, Azure or self-hosted — is resolved once, at creation: "Message queue" becomes Amazon SQS,
Cloud Pub/Sub, Azure Service Bus, or RabbitMQ / NATS JetStream. The id never changes, so
dependencies stay valid. Resolution filters components a target has no equivalent for, rewires
dependencies straight through the gap (and says so, on the component that lost a hop), drops flow
steps that no longer point anywhere, and generates a Deployment tab listing the whole mapping.

A template is a starting point, not a recommendation, and the app says so three times — in the
creation dialog, in each template's Not this one when list, and in meta.principle at the top
of the generated document. The document keeps no link back to the template: no inheritance, no
"update from template" that could overwrite someone's work.

Both languages ship. npm test instantiates 6 templates × 5 targets × 2 languages = 60 documents
and checks their invariants against a snapshot digest, so silent drift is caught rather than
discovered.

Flow patterns

Flows walk a reader through the architecture one step at a time, and 1.0 adds a catalogue of the
eight that recur everywhere: auth/login, checkout, inbound webhook, async job, file upload, RAG
query, CI/CD, incident response.

A flow step points at a component by id, and ids are local to a document — so a reusable flow
cannot carry its bindings. It carries a description of the component each step is looking for, and
the binding is decided again at insertion time against whatever the target document actually
contains. A scorer weighs each step's hints against your components, proposes a binding, and shows
you the result before anything is written. Every hint in the catalogue is checked against the demo
project and the six architecture templates by its test suite, which is the only reason to trust
any of them.

Flows you write yourself can be saved to a personal library and dropped into another project
the same way. Entries are normalised on read, so a shape change ages an old entry out rather than
breaking the picker.

The printable design document

The viewer is tabbed and interactive; a design document is linear and numbered. Document in
the editor opens the same JSON rendered for paper — a cover, a table of contents, numbered
chapters, and the diagram as a figure. Print it and choose "Save as PDF". No dependency to
install and no headless browser on the server: the one prerequisite is a browser that can print.

The plan follows the Architecture Design Document structure — Introduction, Application
architecture, Organisation architecture, DevOps & delivery, Cost estimation, Appendices. A section
says where it belongs through one optional field, doc.chapter. The slot decides order, not the
printed number: numbering is recomputed from the final position, so deleting a chapter renumbers
the rest and an empty part disappears instead of leaving a hole.

The ADD preset adds the thirteen written chapters an ADD is expected to carry — scope, data,
scalability, tenancy, RPO/RTO, observability, resource segmentation, IAM, networking, cost
management, governance, delivery, cost estimate. Empty, structured, bilingual and vendor-neutral.
Applying it twice adds nothing. They arrive off the tab bar, so the interactive viewer is exactly
as it was.

One design, two media: the print stylesheet is the viewer's stylesheet transposed, not a second
look. Anything in document.css that reads as a new visual idea is a bug.

Reading documents (opt-in, off until you configure a model)

Hand ArchStudio a design document, an RFC or an onboarding guide as PDF or Markdown and it drafts
the diagram the document describes: scopes, layers, components, dependencies, and the role and
responsibilities of each. The same reading runs against a project that already exists —
Enrich — where it can only add: new components, missing dependencies, and text in the fields
you left empty. Nothing you have written is ever overwritten, and applying leaves a named version
in History to go back to.

Nothing is written until you have read what came back. The review screen states what the model had
to assume, what it could not answer, and what had to be repaired before the document could open —
a dependency on a component it never defined, an icon that does not exist. Treat all of it as a
draft: it is one reading of one document, and the dependencies especially deserve a second pair of
eyes.

This is the one feature that leaves your machine, so it is yours to point:

Provider	Endpoint	PDFs	Token count before a run
Anthropic	built in	yes	exact
Google Gemini	built in	yes	exact
OpenAI	built in	text only	estimated
NVIDIA NIM	built in	text only	estimated
OpenAI-compatible	yours	text only	estimated

The last row is the interesting one: anything that speaks `/v1/chat/c...