Just as a mountain trail is marked by cairns, software architecture is understood through a series of views, each revealing a different part of the landscape.
Cairn is an Elkjs (Eclipse Layout Kernel) based diagram-as-code tool specialised in these three software architecture views : logical, application and infrastructure, with the aim to follow the requirements of the methodology. This tool comes with a CLI and a browser playground, both providing template initializing for each type of diagram, validation, live previous, and export to SVG and PNG format.
Ongoing development - Pre-releases are available. Stable version will be release when all opened issues are resolved.
A large majority of the diagrams (logical, application, infrastructure view) in existing Software Architecture Documents I've worked are made with graphical diagramming softwares such as Drawio and the like. However, modifying diagrams manually in a GUI despite providing more control on the display, take time and migrating to diagram as code has proven complicated since most diagrams are rich and it's hard to preserve the same level of information with other solutions like C4.
Furthermore, complexe software architecture with many flows and component generated with existing diagram-as-code tools end up very large or with overlapping flow labels making them unreadable and therefore not possible to integrate in a techical architecture document that requires specifically a logical view, application, physical & infrastructure view and Cairn is made specially to answer this need by provided the following features :
| Features | Description |
|---|---|
| Readability through overlap-checked layout. | Label space is reserved during layout; overlaps are measured every build and shipped at 0, with a CI gate. Each flow stays a distinct arrow with its own label. Labels can also be numbered, with the full labels displayed in the legend. |
| Configurable dispositions | slide and page dispositions available to suit different presentation requirements |
| Spacial optimization | Cairn aims to optimize space as much as possible (Still working on improving this functionnality) |
| Typed diagrams with validation. | Each view defines its element kinds and rules; cairn validate reports syntax, schema, and completeness issues as source-located, coded diagnostics, with a JSON mode for CI. |
| Infrastructure flow matrix. | cairn matrix exports the flow matrix as CSV, Markdown, or SVG. Columns split protocol from port, annotate each endpoint with its network zone, and localise via style { lang: fr }. |
| Enterprise-view extras. | Business objects on flows, an auto-generated legend, and a numbered-flow table via flow-text: numbered. |
| French or English output. | style { lang: fr } localizes band titles, legend, and matrix headers while keeping keywords English for portable sources (open to adding other languages if you find this usefull) |
| In-built themes and customizable colours | Whether using the default or a chosen in-built theme, element colours can be overriden for all elements of a given kind in the style block |
Cairn is not a replacement for general diagram tools; for flowcharts, sequence, or ER diagrams, Mermaid or D2 remain the better fit. For C4-level software-structure modeling, dedicated C4 tools like Structurizr or LikeC4 (c4model.com) are a mature choice.
As a result here's a comparaison of the same diagram done with D2 (ELK Layout) vs Cairn (tuned ELK Layout) :
| D2 (ELK Layout) | Cairn (ELK) |
 |
 |
| Link to D2 playground | Diagram in Cairn playground |
| I encountered overlapping issues for which I couldn't find a workaround | The overlapping issues have been addressed. A caveat remains: the long-distance arrow can affect readability (still working on improvements) |
- While Cairn ensures 0 label overlap, flows on large diagrams still take a longer than neccessary route to the target element - issue #26 created to adress this
- At the moment Cairn doesn't give the user the possibility to control positioning - issue #8 created to adress this
Either use the cli or the playground.
Every image below is rendered by cairn CLI from a .cairn source in examples/ — plain SVG, zero label overlaps.
The example diagrams have been generated with AI and some of them purposely large to showcase how such diagrams are rendered with Cairn to handle overlap.
Colours are resolved at three levels — most specific wins. From lowest to highest priority:
- Theme defaults — per-kind colours defined by the selected theme (fill, stroke, text for each element kind).
- Diagram-level per-kind overrides — override colours for all elements of a given kind in the
styleblock:style { fill actor-group: #eef4fb stroke actor-group: #7a9cc4 dashed text block: #222233 background: #fffdf5 # canvas background } - Inline per-element styles — override colour for a single element:
block API "API gateway" { style { fill: #e8f5e9 stroke: #2e7d32 text: #1b5e20 } }
Flows can also be coloured inline:
COM_CTR -> OBS : "Alerts…" { label: above stroke: dashed #a33 text: #a33 }
See examples/colors-custom.cairn for a full example:
Same diagram different disposition :
This example has a large number of flows on purpose in order to showcase how it renders. But in such a case, it's best to consider breaking the diagram into two diagrams : one more general one more zoomed in.
Cairn comes with a collection of built-in themes. Choose the one that best fits your presentation or documentation style:
Classic |
Classic Dark |
Light |
Dark |
Contrast |
Nord |
Sand |
Slate |
Solarized |
Prebuilt, self-contained binaries are published on every v* tag (no runtime needed). Pick your platform:
# macOS / Linux — curl installer
curl -fsSL https://raw.githubusercontent.com/R0kshan/cairn/main/packaging/install.sh | sh
# macOS / Linux — Homebrew
brew install R0kshan/tap/cairn
# Windows — Scoop
scoop bucket add cairn https://github.com/R0kshan/scoop-bucket
scoop install cairnFrom source (no release needed — requires Node ≥ 22.6):
git clone https://github.com/R0kshan/cairn && cd cairn
npm install
npm run cairn -- --help # or: node bin/cairn.js --helpOnce installed, the command is cairn. From a clone, run npm run cairn -- <command>.
cairn new -L my-system.cairn # -L logical · -A application · -I infrastructureThe chosen view is written into the file header (diagram logical …); every other command reads it from there.
cairn validate my-system.cairn # --format json for CI/agents · --strict to fail on warningsProblems are reported as source-located, coded diagnostics with a suggested fix:
error[E0210]: functional block outside any system (`ORPHAN`)
--> my-system.cairn:8:7
|
8 | block ORPHAN "Floating block"
| ^^^^^^
help: move this `block` inside a `layer`, `system` or `external`
cairn build my-system.cairn -o my-system.svg # -o optional; defaults to the same name, .svgOn validation errors nothing is written and the exit code is 1; warnings are printed but do not block.
cairn matrix my-infra.cairn --format csv # csv (default) | md | svg · -o to set the pathcairn watch my-system.cairnRebuilds the SVG on save. On a compile error the SVG becomes an error panel (codes, lines, help), so an open preview never shows a stale diagram. Watch observes only the file it was launched on — run one per file. Pair it with an editor that auto-refreshes an open SVG.
cairn explain E0240E0240 — The infrastructure view requires every flow to carry its protocol (and port if
relevant): the flow matrix is the primary output of this view. Add `(HTTPS/443)` after the label.
cairn version # or --version / -vReleased binaries (the ones from Homebrew, Scoop, or the GitHub Releases page) print the exact tag they were built from. Running from a clone via npm run cairn prints package.json's version instead.
DIAGNOSTICS.md— every diagnostic code and its meaning.DSL_SPEC.md— the DSL syntax.ARCHITECTURE.md— how the pipeline fits together, for contributors.CONTRIBUTING.md— how to open a PR, and the gates it must pass.documentation/— architecture, invariants, DSL and internals.