Archagram for VS Code

Write your architecture as text. Keep the diagram.

archagram.com · Try it in your browser, no account · Docs and notation reference

Archagram is an architecture workspace: an isometric canvas your stakeholders can actually read, with future-state targets, sequences, business processes and slide decks over one model. .ysk is its notation, a text projection of that same model, so structure can live beside your code, go through review, and be generated by automation or an AI agent.

This extension is the editor half of that loop. Open a .ysk file and you get real language tooling: coloring, live diagnostics, completion that knows your component ids, go to definition, and rename across the file.

What it looks like

title: Ordering

boundary edge "Edge" #3b6ea5 {
  storefront [browser] "Storefront"
  orders-api [web-api] "Orders API"
}

orders-db [database] "Orders DB"

storefront -> orders-api : places order
orders-api -> orders-db : reads/writes (animated)

Paste that into archagram.com and it is a diagram. Drag things around, and the text still says the same thing: notation carries structure, never geometry, so applying an edited file keeps every position you placed by hand.

What you get

In .ysk files

• Coloring and folding from the generated grammar, so keywords, ids, icons, colors and strings all read distinctly.
• Live diagnostics while you type. Parse errors are the same ones that block Apply in the app. Warnings catch the mistakes that quietly change your model: an id that is only ever referenced and never declared (a typo becomes a new component otherwise), or one id redeclared with a different label or icon, both with did-you-mean hints.
• Completion for keywords in context, and for every component id declared anywhere in the file however deeply nested, with ids from the drill-in level under your cursor ranked first. Icon ids complete inside [ ], boundary references and @ process bindings complete too.
• Go to definition on any reference: components, boundaries, process pools, lanes and elements, sequence participants, target-added components including split and merge outputs, plan component: links, and the ADR scope: target. @doc.md and @assets/... open the underlying file.
• Hover for an id's label, its container, and its metadata.
• Rename (F2) across the whole file: declarations, edges, boundary members, bindings, target ops and plan links, leaving free text and file paths alone.
• Outline and breadcrumbs through document symbols.
• Archagram: Open Grammar Reference in the Command Palette for the canonical, generated syntax reference.

In .archagram bundles

Schema validation and field hovers, so a hand-edited or generated bundle fails in your editor instead of at load.

If a .archagram bundle sits in the workspace, its component and icon ids join completion in your .ysk files.

Getting started

1. Install this extension.
2. Open archagram.com/play and build something, or start from the sample. Nothing is uploaded and no account is needed.
3. Export the notation, open the .ysk in VS Code, and edit it here.
4. Paste it back, or apply it to a project, and your layout survives.

New to the notation? The full reference is a worked walkthrough of every construct: boundaries, drill-in levels, targets, sequences, processes, decision records and decks.

Good to know

Archagram is visual first. Notation is the structural view for people who prefer text, for automation, and for AI pipelines. It deliberately does not store canvas geometry, so text and mouse can both be authoritative about the thing each is best at. .archagram is the lossless project bundle: validate it here, but author it in the app.

This extension does not yet include a live diagram preview or an apply-to-cloud-project command.

Feedback

Ideas and problems are welcome on the public wishlist, or write to support@archagram.com.