karasu — A Text-Based DSL for Describing a System's Logical, Physical, and Organizational Structure in One Language

Summary

• karasu (鴉, “crow”) is an architecture modeling tool that describes a system’s logical, physical, and organizational structure in a single text language (.krs).
• It draws on the C4 Model, Structurizr, and Mermaid, and takes its own position on three points: a three-facet structure, drill-down (progressive disclosure), and co-editing by humans and AI.
• Try it in your browser → https://karasu.pages.dev/
• Docs → https://kompiro.github.io/karasu/ / Source → https://github.com/kompiro/karasu
• It is a personal learning project, maintained on a best-effort basis. The .krs / .krs.style language specification is published as v1.0 (stable).

Why I built it

As a system grows, its architecture no longer fits in anyone’s head. People who join the team take a long time to work out which service does what, where it is deployed, and who is responsible for it. Diagrams go stale soon after they are drawn, and code and documentation drift apart.

Most existing modeling approaches are good at describing logical structure (how services and domains relate), but they cannot handle physical structure (where things are deployed) or organizational structure (who owns what) in the same vocabulary. The result is spread across separate tools and separate diagrams, and they stop agreeing with each other.

I designed karasu so that all three facets can be described in one .krs language. Two ideas were the starting point. People can only take in so much information at once, so I wanted to express structure in stages. And if you want to discuss the Inverse Conway Maneuver, you need the logical structure and the organizational structure on the same table.

The logical facet — what exists and how it connects

The logical view expresses a system’s internal structure in stages.

• system: users, clients, services, and shared infrastructure (database / queue / storage)
• service: the structure of the domains inside it
• domain: its usecases and the resources they touch

system Shop {
  label "Online Shop"

  user Customer [human] {
    label "Customer"
    role "Buyer"
  }

  service Storefront {
    label "Storefront"
    domain Order {
      label "Ordering"
      usecase PlaceOrder { label "Place an order" }
    }
  }
  service Payment [external] { label "Payment" }

  Customer   -> Storefront "places orders"
  Storefront -> Payment    "charges the card"
}

The point is not to cram everything onto one page. The top level shows only the relationships between services, and when you need more, you drill down from service to domain to usecase. This is a deliberate design choice to keep cognitive load down. karasu calls it scoped glance + drill-down (progressive disclosure).

The screenshots below were rendered from the Japanese-labeled version of this model.

→ Drill down into the Storefront service.

→ Drill down into the Ordering domain.

The physical facet — where it is deployed

A deploy block describes which physical artifact a logical service runs as. Artifacts have kinds such as oci (container), jar, lambda, and job, and realizes ties them to logical nodes.

deploy Production {
  label "Production"
  oci api {
    label "api"
    runtime  "Node.js 20"
    realizes Storefront
  }
}

Describing logical and physical structure separately, and bridging them explicitly with realizes, is the core idea of karasu. A service and the place it runs are different concerns, and they evolve separately.

The organizational facet — who owns it

An organization block describes teams (team), members (member), and the services and domains each team owns (owns). Contact details such as Slack or GitHub handles can be attached as attributes.

organization Acme {
  team Commerce {
    owns Storefront
    member Alice { slack "@alice" }
  }
}

This lets you discuss “who is responsible for this service?” and “in Inverse Conway terms, do team boundaries line up with service boundaries?” in the same language as the logical structure.

Features

A DSL that humans and AI edit together

.krs is not an intermediate representation designed for AI. It is a standalone tool that humans read and write, and that is what makes it work in both directions: humans can hand-edit the .krs an AI generated, and an AI can refine a model a human wrote. Because it is text, diffs and pull requests come naturally.

scoped glance + drill-down

Instead of an “at a glance” bird’s-eye view that packs everything onto one page, karasu limits how much is shown at once and lets you descend to the place where you need detail. Both the language and the renderer support this.

Versioning commitments

• .krs / .krs.style language specification — v1.0 (stable). Backward compatibility is a commitment; any breaking change would be v2.
• packages/core TypeScript API — v0.x (no stability guarantee). The programmatic API may change between minor releases.

Example — all three facets in one file

Here is a minimal example that describes the logical, physical, and organizational facets in a single .krs file.

system Shop {
  label "Online Shop"

  user Customer [human] {
    label "Customer"
    role "Buyer"
  }

  service Storefront {
    label "Storefront"
    domain Order {
      label "Ordering"
      usecase PlaceOrder { label "Place an order" }
    }
  }
  service Payment [external] { label "Payment" }

  Customer   -> Storefront "places orders"
  Storefront -> Payment    "charges the card"
}

deploy Production {
  label "Production"
  oci api {
    label "api"
    runtime  "Node.js 20"
    realizes Storefront
  }
}

organization Acme {
  label "Acme"
  team Commerce {
    label "Commerce Team"
    owns Storefront
    member Alice {
      label "Alice"
      slack "@alice"
    }
  }
}

This one file produces three views: logical, physical, and organizational (the diagrams in each section above). You can see the rendered model here (Japanese labels).

Getting started

• Try it in your browser: paste .krs into https://karasu.pages.dev/
• Docs / syntax reference: https://kompiro.github.io/karasu/

About this project

karasu is a personal learning project. One of its goals is to learn in the open about developing with Claude Code, and it is maintained on a best-effort basis. Issues and pull requests are welcome. Even so, I have fixed the language specification at v1.0.

I’m looking forward to your feedback. If anything catches your attention, please tell me in GitHub Discussions.

• 🐦 Try it: https://karasu.pages.dev/
• 📖 Docs: https://kompiro.github.io/karasu/
• 💻 Source: https://github.com/kompiro/karasu

Bonus

The links below show .krs models generated from various OSS repositories, after giving Claude (or a similar model) karasu’s syntax.md as a file.

• Dify
• Supabase
• Kubernetes
• Bitwarden
• n8n