Loko

GitHub →

Loko compiles a C4 model architecture from HCL. You describe the architecture once, in *.loko.hcl files. Diagrams, markdown, a browsable site, graph queries, a machine-readable export, and an MCP server for AI assistants are all projections of the compiled result.

Why a compiler

When an architecture lives in several places — diagram files, wiki pages, frontmatter — they drift apart, and nothing says which one is right. Loko has one authored artefact, the HCL, and every reference in it is checked at compile time. A broken relationship is an error with a position:

Error: Unresolvable reference
  on arch.loko.hcl:28:19:
  28 |     target      = container.ordrs_db
                         ^^^^^^^^^^^^^^^^^^
  No element "container.ordrs_db" is declared. Did you mean
  container.orders_db?

Because the source is plain text with stable addresses, an architecture can be reviewed in a pull request, diffed between revisions, and edited by an assistant without hand-written diagrams going stale.

Core concepts

Two planes. The logical plane is environment-agnostic C4: person, system, container, component, external. The deployment plane instantiates it per environment: deployment, an optional nested node tree, and instance blocks carrying attributes and bindings to real infrastructure such as Terraform addresses.

Relationships nest inside their source. A uses "orders" block inside container "api" has the stable address container.api.uses.orders. kind = "async" or "trigger" changes how it is drawn, never what depends on what.

References are typed and resolved at compile time. container.db is a reference, not a string. A typo is an error with a source range and usually a suggestion.

Views are generated, and you can declare more. Every system and container with children gets a diagram automatically. A view block selects elements by reference or tag for a focused picture.

Prose lives beside the model. docs = "./docs/api.md" attaches markdown to an element; it appears on the element’s site page.

Output is byte-stable. The same source always produces identical bytes, on any machine, in any file-system order, so a committed export is reviewable in a diff.

The compiler is stateless. No lock file, no state file, no database. Git is the history.

License

Loko is licensed under the Business Source License 1.1.