root-at-skic
7a2b661afe
A folder with main.archify at its top is a model, a set of diagrams that belong together. Opening main.archify shows the model page: the model's name and description, its own overview diagram when the file has one, the diagrams grouped by folder (click to open), and the registry with where each element is used. The page is built by traversing the folder tree and refreshes when files change. *.archify-registry files define shared elements once; diagrams draw them with `ref: <id>` plus position and may override label, sublabel and tag. References are resolved before Archify runs, so Archify is unchanged. Hover, go-to-definition and completion on ref; unknown names, forbidden overrides, duplicate ids and broken registries in Problems; registry edits re-render open diagrams. `diagram:` links on elements and components open the linked diagram on double-click. New command Archify | Open Model, a Model template for New Diagram…, editor schemas for the new keys and for registries, docs/model.md and examples/online-shop. Single diagrams behave exactly as before.
195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
# Archify Diagram Viewer
|
||
|
||
Create and view [Archify](https://github.com/tt-a1i/archify) diagrams inside VS Code. You write a diagram as a **`.archify` file in YAML**; clicking it opens the interactive diagram, and the diagram follows your edits as you type.
|
||
|
||
|
||
|
||
This is an unofficial extension. It bundles the Archify renderer (MIT, © tt-a1i) and runs it on VS Code's own Node runtime, so nothing else needs to be installed.
|
||
|
||
Free and open source. If it saves you time, you can [buy me a coffee](https://buymeacoffee.com/root.at.skic) ☕
|
||
|
||
## Supported files
|
||
|
||
| File | Format | What the extension does |
|
||
|---|---|---|
|
||
| **`name.archify`** | **YAML** (the main format) | Opens as the interactive diagram. Show Source, live updates, validation, completion, templates. |
|
||
| `name.architecture.json`, `name.workflow.json`, `name.sequence.json`, `name.dataflow.json`, `name.lifecycle.json` | JSON (Archify's own CLI format) | Opens as text, with a preview beside it and validation. For files produced by the Archify CLI or AI agents. |
|
||
| Rendered Archify `.html` | HTML | Read-only viewer instead of a browser. |
|
||
|
||
New diagrams should be `.archify` files; everything below describes them unless it says otherwise.
|
||
|
||
## Quick start
|
||
|
||
The fastest start: right-click a folder in the Explorer and choose **Archify | New Diagram…** (also in *File → New File…* and the Command Palette). Pick a kind of diagram (Architecture, Workflow, Sequence, Data Flow, Lifecycle or Everyday Plan), give it a name, and a small working `.archify` file is created and opened. Change its YAML to fit your case.
|
||
|
||
To write one by hand:
|
||
|
||
1. Create a file ending in `.archify`, for example `hello.archify`:
|
||
|
||
```yaml
|
||
schema_version: 1
|
||
diagram_type: architecture
|
||
meta:
|
||
title: Hello Archify
|
||
output: hello.html
|
||
components:
|
||
- { id: browser, type: frontend, label: Browser, pos: [40, 120], size: [140, 60] }
|
||
- { id: api, type: backend, label: API, pos: [260, 120], size: [140, 60] }
|
||
- { id: db, type: database, label: PostgreSQL, pos: [480, 120], size: [140, 60] }
|
||
connections:
|
||
- { from: browser, to: api, label: HTTPS }
|
||
- { from: api, to: db, label: SQL }
|
||
```
|
||
|
||
2. Click it in the Explorer: the diagram opens.
|
||
3. To edit, use **Show Source** in the editor title. The YAML opens beside the diagram, which re-renders as you type.
|
||
|
||
The same file is in [examples/hello.archify](examples/hello.archify).
|
||
|
||
## The `.archify` format
|
||
|
||
A `.archify` file is an Archify diagram written in **YAML**. Its fields are those of Archify's diagram schema; the extension converts the YAML for the renderer, so you never handle JSON yourself. `diagram_type` selects the kind of diagram: `architecture`, `workflow`, `sequence`, `dataflow` or `lifecycle`.
|
||
|
||
- **Opening:** the **Archify Diagram** editor is the default for `.archify`. Use *Reopen Editor With… → Text Editor* to edit the YAML full-screen.
|
||
- **Completion:** with the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) (`redhat.vscode-yaml`) installed, `.archify` files get completion and hover from Archify's schemas. The schema follows `diagram_type`.
|
||
|
||
`.archify` files from extension version 0.2.0 were written in JSON. They still open, because JSON is valid YAML, but new files should use YAML.
|
||
|
||
## Archify's JSON files
|
||
|
||
The Archify CLI and the AI agents that use it write diagrams as JSON, named `name.architecture.json`, `name.workflow.json` and so on. The extension supports these too: they open as text with a preview button in the editor title (<kbd>Cmd/Ctrl+K V</kbd> to the side, <kbd>Cmd/Ctrl+Shift+V</kbd> in place), get validation in Problems, and get schema completion from VS Code's built-in JSON support. Any other `.json` file that declares an Archify `diagram_type` previews the same way.
|
||
|
||
## Features
|
||
|
||
- **New diagram from a template**: *Archify | New Diagram…* creates a starter `.archify` file for any of the five diagram kinds, or an everyday plan, in the chosen folder.
|
||
- **Diagram editor**: `.archify` files open as the rendered diagram. **Show Source** opens the YAML beside it, and edits re-render live.
|
||
- **Live updates**: the diagram re-renders as you edit, and keeps the focus and route you selected (`#focus=…`, `#route=…`).
|
||
- **HTML viewer**: right-click a rendered `.html` file and choose **Archify | Open in HTML Viewer**, or use *Reopen Editor With… → Archify HTML Viewer*. For Archify HTML already open as text, a button appears in the editor title. The viewer reloads when the file changes on disk.
|
||
- **Problems**: YAML syntax errors, plus `archify validate`'s schema, layout and evidence problems, appear at the matching line of the `.archify` file.
|
||
- **Brand logos**: after `brand:` the editor suggests Archify's built-in brand IDs (PostgreSQL, Redis, Kafka, Docker, …). Typing an alias or product name finds them too, so `kafka` offers `apache-kafka`. An unknown brand is reported on its own line.
|
||
- **Schema help**: completion and hover from Archify's own schemas, through the YAML extension for `.archify` files.
|
||
- **Source links**: in source-backed diagrams, clicking a source reference opens that file and line range in the editor. If the file is not in the workspace, the web link opens instead.
|
||
- **Export**: the diagram's own Export menu (PNG, SVG, share card, …) saves through a VS Code save dialog.
|
||
- **Commands**: *Archify | New Diagram…*, *Archify | Render to HTML File…*, *Archify | Open in Browser*, *Archify | Refresh Preview*, *Archify | Show Source*.
|
||
|
||
## 3D view
|
||
|
||
Every diagram can also be seen in 3D. The **2D | 3D** switch next to **Export** in the diagram's toolbar shows which view you are in; click it to flip.
|
||
|
||
|
||
|
||
The 3D view is built from the diagram Archify draws, so it looks the same: each node becomes a raised block whose top is the node as Archify draws it, relationships become pipes along Archify's routes with their colours, dashes and arrowheads, and the canvas, frames, lanes and legend form the floor. It works for all five diagram kinds, in every theme and style (Classic, Signal Flow, Blueprint, Editorial).
|
||
|
||
While 3D is on, three controls join the bottom-right dock next to **PATH** and **LENS**:
|
||
|
||
- **STACK** lifts nodes into levels by kind: clients and external systems on top, security below them, services in the middle, data on the floor. Click again for the flat layout.
|
||
- **TOP** looks straight down, like 2D.
|
||
- **RESET** (the middle of the zoom stepper, or <kbd>0</kbd>) flies back to the whole diagram, wherever you have moved to.
|
||
|
||
Moving around:
|
||
|
||
- Drag to turn, right-drag to move. On a trackpad, scroll with two fingers to move in any direction and pinch to zoom; a mouse wheel zooms. The dock's **−** and **+** and the <kbd>-</kbd> and <kbd>+</kbd> keys work too, beyond the 2D limits.
|
||
- Click a block to focus it, as in 2D: the Semantic Passport opens and unrelated parts fade. Hover a block to see its one-hop trace. Double-click a block to fly to it, or empty space to show everything.
|
||
|
||
Animation follows 2D exactly, because the 3D view reads Archify's own animations as they play: the trace (relationships drawing in, nodes pulsing) when the diagram opens or 3D is chosen, the hover trace, and the flows from the Semantic Passport, Path and Lens. *Live* off, or reduced motion, keeps it still.
|
||
|
||
**Export → 3D view** saves the current 3D view as a PNG. Each open diagram remembers whether it was in 3D, its camera and its levels; set `archify.defaultView` to `3d` to open diagrams in 3D.
|
||
|
||
The 3D view draws only when something moves, so an idle diagram costs no GPU time.
|
||
|
||
## Models
|
||
|
||
A single `.archify` file is one diagram. A folder with a **`main.archify`** at its top is a **model**: a set of diagrams that belong together, of any kind, with shared elements defined once. Diagrams inside a model still open, render and export on their own.
|
||
|
||
```
|
||
online-shop/
|
||
main.archify id, name, description; optionally an overview diagram
|
||
registry/
|
||
people.archify-registry shared elements: one name for one thing
|
||
systems.archify-registry
|
||
containers.archify-registry
|
||
0100-context/online-shop.archify
|
||
0200-containers/online-shop.archify
|
||
0300-components/api.archify
|
||
```
|
||
|
||
- **The model page.** Click `main.archify` and you get the model's page: its name and description, the overview diagram if the file has one, the diagrams of the model grouped by folder (click one to open it), and the registry with "used in N diagrams".
|
||
- **Shared elements.** A registry file defines an element once (`type`, `label`, `sublabel`, `brand`, `description`, …). A diagram draws it with `ref: api` plus `pos` and `size`; it may override `label`, `sublabel` and `tag`, and may still define unshared elements inline. Hover a `ref` for the description, F12 jumps to the registry, completion after `ref:` lists the elements, unknown names appear in Problems.
|
||
- **Links.** A registry element (or a component) with `diagram: 0300-components/api.archify` points at the diagram that explains it: double-click the node in the 2D view to open it.
|
||
- **Commands.** *Archify | Open Model* opens the model page of the current file; *Archify | New Diagram… → Model* creates a `main.archify` from the folder name.
|
||
|
||
Formats in detail: [docs/model.md](docs/model.md). A full example: [examples/online-shop](examples/online-shop).
|
||
|
||
## Source evidence
|
||
|
||
A diagram that declares `meta.repository` and `sources` is verified against a local Git checkout whose `origin` and pinned commit match. The extension uses the Git top-level directory of the diagram file, or `archify.repoRoot` when set.
|
||
|
||
When verification fails, the default (`archify.sourceEvidence: "fallback"`) still shows the diagram without source links, explains why in a notice, and reports the reason as a warning. Set it to `"strict"` to treat this as an error, as the Archify CLI does. *Archify | Render to HTML File…* always verifies strictly and asks before rendering without source links.
|
||
|
||
## Settings
|
||
|
||
| Setting | Default | Description |
|
||
|---|---|---|
|
||
| `archify.theme` | `vscode` | `vscode` follows the color theme; `dark` or `light` force one; `diagram` keeps the diagram's own choice. |
|
||
| `archify.defaultView` | `2d` | `3d` opens diagrams in the 3D view. Each open diagram remembers its own choice. |
|
||
| `archify.preview.liveUpdate` | `true` | Re-render while typing; when off, re-render on save. |
|
||
| `archify.preview.debounceMs` | `400` | Delay before re-rendering after an edit. |
|
||
| `archify.validation.enabled` | `true` | Report validation results in Problems. |
|
||
| `archify.quality` | `""` | Force the `standard` or `showcase` quality profile. |
|
||
| `archify.sourceEvidence` | `fallback` | `fallback` or `strict` handling of unverifiable source evidence. |
|
||
| `archify.repoRoot` | `""` | Checkout used to verify source evidence. |
|
||
| `archify.nodePath` | `""` | Node.js 18+ executable to use instead of VS Code's runtime. |
|
||
|
||
## Security
|
||
|
||
Diagrams run in a webview with a strict content security policy. Only the page's own inline scripts and the extension's bundled 3D viewer run (via a per-render nonce), there is no network access for scripts or fetches, and links open through VS Code.
|
||
|
||
## Development
|
||
|
||
```bash
|
||
npm install
|
||
npm run build # bundle to dist/
|
||
npm test # unit tests + renderer tests (Node)
|
||
npm run test:integration # runs the suite inside VS Code
|
||
npm run package # build archify-vscode-ext-<version>.vsix
|
||
```
|
||
|
||
Press <kbd>F5</kbd> to launch an Extension Development Host with the test fixtures.
|
||
|
||
### Code layout
|
||
|
||
| Folder | What it holds |
|
||
|---|---|
|
||
| `src/extension.ts` | Activation: creates the views and registers everything |
|
||
| `src/commands/` | Command handlers, grouped by job, and the editor context keys |
|
||
| `src/views/` | The diagram view (editor for `.archify`, side preview for JSON) and the HTML viewer |
|
||
| `src/webview/` | The page the views show: CSP, the bridge script, messages from the page |
|
||
| `src/archify/` | Running the bundled Archify CLI: render, validate, runtime settings |
|
||
| `src/sources/` | Reading diagram files: type detection, YAML/JSON, source evidence |
|
||
| `src/language/` | Editor help: Problems, brand completion, templates |
|
||
| `src/util/` | Logging, settings, file reading |
|
||
| `src/viewer3d/` | The 3D view; runs inside the Archify page and is bundled to `dist/viewer3d.js` with three.js |
|
||
|
||
### Updating the bundled renderer
|
||
|
||
`vendor/archify/` and `schemas/` are generated from an Archify checkout:
|
||
|
||
```bash
|
||
node scripts/sync-archify.mjs /path/to/archify # default: ../../ws-storm/archify
|
||
npm test
|
||
```
|
||
|
||
`vendor/archify.json` records the upstream version and commit.
|
||
|
||
## Support
|
||
|
||
Archify Diagram Viewer is built and maintained in my spare time. If it helps you, a coffee keeps the releases coming:
|
||
|
||
[](https://buymeacoffee.com/root.at.skic)
|
||
|
||
Bug reports and ideas are welcome in the [repository issues](https://gitea.lego-cloud.eu/vscode-extensions/archify-vscode-ext/issues).
|
||
|
||
## License
|
||
|
||
MIT. See [LICENSE](LICENSE). The bundled renderer is MIT-licensed by tt-a1i; see `vendor/archify/LICENSE` and `vendor/archify/THIRD_PARTY_NOTICES.md`.
|