"Architecture as code" Introducing karasu: a text-based system architecture modeling language

TL;DR

Karasu is a text‑based language for modeling system architecture across logical, physical, and organizational dimensions.
It helps describe services, domains, deployment artifacts, and development teams in a single .krs file.
Features include progressive disclosure of information and collaboration between humans and AI.
Inspired by the C4 Model and Mermaid, Karasu provides examples and a visualizer app.
Resources: live app at karasu.pages.dev, documentation at kompiro.github.io/karasu, and source code on GitHub.

Motivation

As system development progresses, the number of related services and middleware components tends to grow. Especially when joining a new system development project, having a grasp of the overall architecture makes the code dramatically easier to understand.

In my experience, I want to understand the following:

Logical dimension

System structure
- Who are the intended users of the service? Is integration with AI considered?
- Are there clients that connect to the service, such as mobile apps or MCP?
- What kinds of middleware does the service use?
- What external services does the service depend on?
Service structure
- What domains does the service handle?
Domain structure
- What resources does each domain handle?
- What use cases exist for handling those resources?
- In each use case, how are resources read and written?

Physical dimension

In what form are the clients, services, jobs, and middleware deployed as artifacts?

Organizational dimension

Which teams or members develop and maintain each service/domain?
- In particular, I want to identify key teams and key people.

To describe these three axes in text, I built the language karasu and the visualization tool karasu app.

Features

Describe structure across three dimensions (logical / physical / organizational)
- You can describe services, domains, the artifacts deployed from them, and the development teams/members in a single .krs file.
- You can discuss Conway’s Law and an inverse Conway strategy in the same “table”.
Progressive disclosure of information
- Because human cognition is limited, the tool is designed to restrict how much information you see at once.
- You can drill down to the details only when you need them.
- This is not an “at a glance” bird’s-eye view that squeezes everything into one diagram.
A DSL that humans and AI can collaborate on
- .krs is designed to be easy for humans to understand, which also makes it easy for AI to parse.
- Humans can edit .krs generated by AI, and AI can refine models drawn by hand.
Logical and physical, linked by realizes
- Business structure (services, domains, use cases) and deployment structure (artifacts, jobs, runtimes) live in separate diagrams.
- A deployment unit declares realizes <Service> to point back to what it implements — physical → logical, never the reverse.
- Because the direction is one-way, a single logical service can map to many deployment units without the model collapsing into a 1:1 mirror.

karasu takes inspiration from the C4 Model, Structurizr, and Mermaid, but stakes out a different position on three points: continuous drill-down instead of a fixed set of levels, a third axis for organizational structure, and a text format built for human–AI co-authorship.

system Shop {
  label "Online Shop"

  user Customer [human]      { role "Buyer" }
  service Storefront {
    domain Order {
      usecase PlaceOrder { label "Accept an order" }
    }
  }
  service Payment [external] { label "Payment" }

  Customer   -> Storefront "Place an order"
  Storefront -> Payment    "Charge the card"
}

// Logical: drill down into a service


// Physical: a deployment unit realizes the logical service
deploy "production" {
  oci "api" {
    runtime  "Node.js 20"
    realizes Storefront
  }
}

// Organizational: who owns what
organization Acme {
  team Commerce {
    owns Storefront
    member Alice { slack "@alice" }
  }
}

Examples

How to use

You can try karasu app right away at: https://karasu.pages.dev

Basic usage is documented here: https://kompiro.github.io/karasu

Closing

Development happens at: https://github.com/kompiro/karasu

Feedback is very welcome.