Introducing karasu: a text-based system architecture modeling language

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 is inspired by the C4 Model and Mermaid.

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

• Dify
• Supabase
• Kubernetes

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.