Skip to content

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.

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

Terminal window
# 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 and .krs.style 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
/services/order services/order.krs

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

  1. Edit a .krs file in your usual editor (or the VS Code extension): the open file, any file it imports, or a .krs.style sheet it @imports.
  2. Save.
  3. 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.

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.

On your first visit the playground opens with a Welcome dialog that offers three places to start:

  • Design a service split: opens the service-split sample as a new project and starts a five-step guided tour: the current architecture, the teams that own it (Org view), the planned architecture compared with the current one (diff mode), the state in between (@migration_target, @planned), and how to share the result. The tour is a small panel at the bottom left; Skip tour ends it at any step, and Continue to editor ends it on the last one. A step that asks you to do something (drill in, turn on the team dependencies, share or export) shows a ✓ once you have done it; you still move on with Next when you are ready. If an online shop is far from your work, step 1 offers to walk the same guide on a payroll system (the payroll-split sample), and the way back. Switching uses a copy that still matches the sample, and otherwise opens a new one.
  • Understand an existing system: starts a four-step guided tour of the Getting Started project: the whole system, how it runs (Deploy view), who owns what (Org view), and how to share what you found. It uses a Getting Started that still matches the sample, and otherwise opens a new copy, so your edits stay as they are.
  • Track architecture evolution: opens the service-split sample as a new project and starts a four-step guided tour: the migration compared with today (diff mode), the migration marks in the model (@migration_target, @planned, @deprecated), the target compared with the migration (what is left), and how to share where it stands.

All three tours work the same way. Samples from Welcome never touch anything you already have. Welcome does not appear when you open the app through a link to a specific place (a gallery example or a #krs-… permalink), or once you have chosen something. Run Show Welcome… from the command palette (Ctrl/Cmd+Shift+P) to open it again. Restart Guided Tour… in the same palette walks the last guide you started again from step 1, in the project it used before, with any edits you made there. If that project is gone, the guide opens the way its Welcome entry does (or the way switching does, for the payroll guide); if you never took a tour, it starts Design a service split.

Reloading the page during the tour, or opening the app again from its address bar, comes back to the step you were on in the tour’s project. A link that opens a specific place (a gallery example, a permalink, another project) does not bring the tour back; Restart Guided Tour… does.

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

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.

  • 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.
  • Jump to the definition — Cmd/Ctrl+click a node to move the editor to the line that defines it, opening the file it is defined in if that is another one. Drillable nodes jump too instead of drilling. The detail panel’s ↗ Jump to editor does the same.
  • Edge in focus — click an edge to open a second canvas over the preview with its two nodes and every edge between them, labels in full. A dense diagram shortens long labels and leaves off the ones that would overlap; this is where they are read.
  • Node in focus — hover a node to fade the edges it does not touch, then press ⇄ Relations on its corner to open it with every node it connects to: what depends on it on one side, what it depends on on the other. Click a node or an edge inside to move there, or drag to move the view (a press on text selects it instead); ← Back returns, Esc closes. Without a mouse: on a touch screen, tap a node’s ⓘ and press ⇄ Relations in its panel; from the keyboard, select the node in the Outline and run Show Relations of Highlighted Node from the command palette (Ctrl/Cmd+Shift+P). Inside, Tab moves between the nodes and edges, and Enter or Space opens the one in focus.
  • 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.

Clicking a database in the System view drills into a simple ER view: the store’s table leaves and the relations between them. The colour of a relation says who vouches for it. The line style keeps its usual meaning: solid is sync, dashed is async. The colours below are those of the built-in style; a .krs.style sheet can change them.

Colour (dark / light theme) Tag Meaning
Slate grey, the default edge colour (#94A3B8 / #64748B) none Recorded in the .krs as a table → table edge, written by hand or emitted by translate --from db from a declared foreign key. Confirmed.
Sky blue (#38BDF8 / #0369A1) [projected] Not in the .krs. Drawn from an entity relation whose two entities both map to tables in this store. The entity layer asserts it; nothing recorded it against the store.
Warm grey (#A8A29E / #78716C) [inferred] Written by translate --from db from a naming convention (a <stem>_id or <stem>_code column with no declared foreign key). Delete the tag once you have confirmed the relation.
  • When a recorded edge and a projected one join the same two tables, only the recorded one is drawn.
  • The diagram legend does not list these colours: they come from the built-in style, not from a legend block in your model.
  • The view is not a complete ER diagram of the store. Recorded edges always appear, but an entity relation is projected only when both of its entities map to a table in this store. See Store-scoped ER view for what is left out, and Automatic tags on edges for every tag the renderer assigns.

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 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

Section titled “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.

Toolbar — what takes the diagram elsewhere

Section titled “Toolbar — what takes the diagram elsewhere”
  • 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. In karasu serve the link points at the public app (https://karasu.kompiro.dev) instead of your local server, so whoever you send it to can open it without running karasu.
  • 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.

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.

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)

© 2026 Hiroki Kondo · Licensed underApache-2.0

Built with Cloudflare