Using the karasu App

English（this file） · 日本語

karasu ships a graphical app that turns your .krs files into live, navigable diagrams. There are two ways to reach it:

karasu serve — a local, preview-only server that watches the .krs files in a directory and re-renders them in your browser every time you save. You keep editing in your own editor; the preview follows along.
The in-browser playground at https://karasu.kompiro.dev/ — the full experience with a built-in editor, file tree, and live preview, running entirely in your browser. Nothing is installed and nothing leaves your machine.

Both share the same preview pane, so the Preview pane section below applies to either way of working.

`karasu serve` — preview your real files

Run serve from a directory that contains one or more .krs files:

# from a directory with .krs files
npx --yes karasu@latest serve

# or point it at a directory and pick a port
npx --yes karasu@latest serve ./architecture --port 4000

karasu serve
  Directory : /path/to/architecture
  Preview   : http://localhost:3000

Watching for .krs file changes...

Open the printed URL (default http://localhost:3000). The page resolves which file to show from the URL path:

URL	File shown
`/`	`index.krs` (or the only `.krs` file if there is just one)
`/payment`	`payment.krs`
`/org`	`org.krs`

serve is preview-only — it does not embed an editor. The workflow is a tight loop:

Edit a .krs file in your usual editor (or the VS Code extension).
Save.
The server detects the change and pushes it to the browser, which re-renders the diagram automatically. No manual refresh.

If a file has syntax errors the last good diagram stays on screen with an “outdated” banner until you fix them — see Diagnostics.

The app’s supported entry file is index.krs. Keep your top-level model there so / resolves to it.

The in-browser playground

If you just want to try karasu, open https://karasu.kompiro.dev/. It is the same app with the editor enabled:

A Monaco editor with .krs syntax highlighting (light and dark themes).
A file tree for creating, renaming, and deleting .krs and .krs.style files — all stored locally in your browser (OPFS), so your work persists between visits and never touches a server.
The same live preview pane described below, updating as you type.

The playground opens index.krs by default. See The editor for the editing features.

The preview pane

The preview pane is the heart of the app and is identical in serve and the playground.

Diagram views

A model is shown through four views, selectable from the view tab bar or with a keyboard shortcut:

View	Shortcut	Shows
System	`Ctrl/Cmd+1`	Service and system architecture
Deploy	`Ctrl/Cmd+2`	Deployment topology (physical structure)
Org	`Ctrl/Cmd+3`	Teams and roles (organizational structure)
CRUD	`Ctrl/Cmd+4`	Usecase × resource read/write matrix

The three dimensions behind System / Deploy / Org are explained in Core Concepts.

Navigating a diagram

Zoom — scroll the mouse wheel over the diagram.
Pan — click and drag.
Drill down — click a node that has children to descend into it; a breadcrumb tracks your depth.
Node details — click a leaf node (or its info button) to open a side panel with the node’s id, description, tags, and related connections.
Cross-view navigation — jump between related views, e.g. from a service in System to where it runs in Deploy, or to the team that owns it in Org.

Diagnostics

Parse errors, warnings, and informational messages appear in a banner above the diagram. While errors exist, the diagram keeps showing the last successfully parsed version with an “⚠ Diagram is outdated — fix errors to update” notice, so a typo never blanks your screen.

The preview’s two control surfaces

The preview’s controls sit on two surfaces, split by what they do: a control that changes the drawn diagram sits in the drill-path row directly above the diagram; a control that takes the diagram elsewhere lives in the toolbar along the top. Keeping both families in the toolbar made it wrap to a second row at ordinary window widths.

Drill-path row — what changes the diagram

Group by (System view, when the model has an organization block) — choose Team to wrap each owning team’s services in a collapsible boundary frame. Each frame has a ⊖/⊕ toggle.
Facets (System view, when the model declares or references a facet) — pick one or more facets to highlight. Members get a coloured ring, everything else dims, and the legend gains a colour key. The menu stays open so you can pick several. An element in more than one selected facet gets one ring per facet, always in the same order, so two cards can be compared at a glance. The overlay is orthogonal to Group by — team or boundary banding stays readable at the same time — and it survives drill-down, collapse and export. The selection lives in the viewer: nothing is written to your .krs, and clearing it returns the diagram to exactly its unmodified appearance. At the bottom of the same menu, Membership overview answers the other question — which elements are in facet X — in one panel, with each facet’s description, policy links and member list. That list is derived from the facets properties on every compile, so it is never something you maintain. Clicking a facet’s name there toggles its highlight, the same as the menu.
Collapse all / Expand all (System view) — whenever the view has anything collapsible — team boundary frames or the external / infra layer bands — this button folds or unfolds all of them at once, reaching the compact overview (“collapse by default, open what you need”). It appears even when you are not grouping, as long as there are external / infra bands to fold. In a single, un-grouped system its Expand all direction also expands every service in place at once (each service’s domains shown in a boundary frame) — the bulk complement to Collapse all. Because the toggle is all-or-nothing, a model that has external / infra bands (they start open) reads “Collapse all” first, so you reach the fully-expanded state with Collapse all → Expand all; a model with no bands expands in one click. Opening many services deliberately trips the overload hint; Collapse all is the one-click way back to the overview.
Entities (System view, while drilled into a domain that has entities) — swap the usecase view for the domain’s entity view.
Tree View (Org view) — swap the org grid for its tree rendering.
Dependencies (Org view, when the model declares an organization) — swap the org grid for the derived team-dependency graph: which teams depend on which, joined from owns and the logical edges. Nothing in .krs declares these; karasu team-dependencies prints the same derivation as a table. A solid arrow is a sync dependency and a dashed one async; a muted arrow is a pair where one team sits inside the other in the org tree. The footer says how many endpoints resolved to no team, so a sparse graph reads as an incomplete owns rather than as a loosely-coupled org. A second footer line counts nodes owned across a containment boundary — a node one team owns living inside a node another owns. That is a containment fact rather than a call, so it is not drawn as an arrow here (a logical edge may cross the same boundary, independently); karasu team-dependencies lists them in full.
Show All Layers — render every drill-down level stacked together.

On a narrow window these wrap below the drill path rather than squeezing it.

Export — save the current view as SVG. The split-button menu also exports the drill-down tree, a single SVG bundling all views, draw.io (mxGraph XML) for further manual editing, and Open All Views, which opens that same all-views bundle in a new tab instead of downloading it.
Share — copy a link that carries the model in the URL.
Docs — the built-in tag/annotation Reference, in a pop-out window you can keep beside the diagram, and the published documentation site. The Reference answers what you can write; every tab links on to the guides and the notation cookbook (when you would reach for a form) and the Examples gallery (how it renders), including inside the pop-out.
Focus (Ctrl/Cmd+Shift+F) — expand the preview to full width.

The editor (playground)

When the editor is available (the playground, not serve), authoring .krs is assisted by:

Syntax highlighting for .krs and .krs.style, in light and dark themes that follow your system preference.
Format (Shift+Alt+F, or the ⌥ Format button) to tidy a .krs file. For .krs.style files a ✨ Tidy button merges duplicate rules instead.
A live preview that re-renders as you type — no save required.
A collapsible sidebar (Ctrl/Cmd+B) that switches between a Files tree (Ctrl/Cmd+Shift+E) and an Outline of the current model (Ctrl/Cmd+Shift+O). Selecting an outline node highlights it in the diagram.

The edit pane also has Chat and Settings tabs. Chat is an optional AI assistant for drafting and editing .krs; it requires you to store an API key in Settings first.

Settings holds the preferences that outlive a single diagram: Language, Theme, Display, and the Chat API key.

Display → Node display picks how nodes are drawn:

Shape cards (default) — variable-width cards sized to their content.
Icon cards (deprecated) — every node drawn at a fixed size with its kind’s icon, so the layout stays dense and stable however long the labels are. This mode is deprecated and will be removed in a future major version; which release removes it is not decided yet. Move to shape cards with an external SVG icon (shape: url()): in shape mode such an icon now paints the card frame you declare and keeps its aspect ratio, so switching costs you neither the frame nor the drawing (see docs/spec/style.md § shape property).

Because Display lives in the edit pane, it is not available under karasu serve, which renders the preview on its own. Language and Theme are reached the same way, as is the Chat API key, and share that limitation.

Keyboard shortcuts

Shortcut	Action
`Ctrl/Cmd+Shift+P`	Open the command palette — search and run any command
`Ctrl/Cmd+1` … `Ctrl/Cmd+4`	Switch to System / Deploy / Org / CRUD view
`Ctrl/Cmd+Shift+F`	Toggle preview focus (full width)
`Ctrl/Cmd+B`	Toggle the sidebar (playground)
`Ctrl/Cmd+Shift+E`	Show the Files tree (playground)
`Ctrl/Cmd+Shift+O`	Show the Outline (playground)
`Shift+Alt+F`	Format the current `.krs` file (playground)