Likec4

LikeC4 Skill

LikeC4 is a DSL for describing and visualising software architecture. It is inspired by the C4 model and Structurizr DSL, but lets you define your own notation, element kinds, and any number of nesting levels.

Source files use .c4 or .likec4 extensions. All files in a project are merged into one model.

Agent Workflow

When a user asks you to diagram a system, follow this sequence:

1. Understand scope — Ask (or infer from context): what system, what audience, what level of detail?
2. Pick the right view type(s) — Use the table below to match intent → view type.
3. Read the reference file for the chosen view type before writing DSL.
4. Scaffold the model — specification → model → views (in that order in the file).
5. Iterate — Offer to drill down, add deployment, or generate additional views.

View Type Selection Guide

Always read the relevant reference file(s) before generating DSL. Multiple reference files may apply — for example, a context diagram that also shows network zones needs both context.md AND trust-boundary.md.

DSL Skeleton

Every LikeC4 project has three top-level blocks. Scaffold them in this order:

// 1. Define your notation
specification {
  element actor
  element system
  element container
  element component
  element database
  relationship async
  tag deprecated
  tag external
}

// 2. Define the model (elements + relationships)
model {
  actor customer 'Customer' 'End user of the platform'

  system mySystem 'My System' {
    container api    'API Gateway'  { technology 'REST/HTTP' }
    container webapp 'Web App'      { technology 'React'     }
    database  db     'Primary DB'   { technology 'PostgreSQL' }

    api -> db     'reads/writes'
    webapp -> api 'calls'
  }

  customer -> mySystem.webapp 'uses'
}

// 3. Define views
views {
  view index {
    title 'System Landscape'
    include *
  }
}

Core DSL Rules (memorise these)

• Names: alphanumeric + hyphens/underscores, cannot start with digit, no dots.
• References: use dot-notation — mySystem.api. Inside a scoped view (view of X) you can use short names.
• Tags must come first inside an element block, before any other properties.
• Properties order inside element: #tags, title, description, technology, links, metadata, then child elements.
• Relationships: source -> target 'label' or source -[kind]-> target 'label'
• All files merge into one model — split large models into spec.c4, model.c4, views.c4.
• index view is the default landing view; always define one.

Styling Quickref

specification {
  element database {
    style {
      shape cylinder
      color amber
    }
  }
  element actor {
    style {
      shape person
      color green
    }
  }
}

// Per-element override in the model:
model {
  database legacyDB 'Legacy DB' {
    style { color red }
  }
}

// Per-view style overrides:
views {
  view myView {
    include *
    style customer {
      color green
      shape person
    }
    style *.external {
      color gray
      opacity 40%
    }
  }
}

Available shapes: rectangle (default), cylinder, queue, ellipse, person, storage, browser, mobile, component

⚠️ hexagon is not a valid shape — use component for transformer/processor-style elements instead.

Built-in colors: primary, secondary, muted, slate, red, green, amber, blue, indigo, sky

⚠️ teal is not a valid built-in color — use secondary or sky instead.

Built-in icon sets: aws:, azure:, gcp:, tech: — e.g. icon aws:simple-storage-service

⚠️ Icon names must exactly match the library. Common mistakes:

• azure:active-directory does NOT exist — use azure:entra-id-protection or azure:entra-managed-identities
• Always verify icon names by checking node_modules/@likec4/icons/<prefix>/ or the LikeC4 icon browser

File Layout Convention

For any non-trivial project, split files like this:

architecture/
├── spec.c4          # specification block — element kinds, relationship kinds, tags, colors
├── model.c4         # model block — elements and relationships
├── views.c4         # views block — all view definitions
└── deployment.c4    # deployment block — infra nodes and deployment views (if needed)

Validating the Diagram

After generating or editing .c4 / .likec4 files, always validate the model before presenting it to the user:

likec4 validate [path]

• [path] is the directory containing your .c4 files (defaults to current directory if omitted).
• A clean run prints no errors and exits with code 0.
• Fix all reported errors before proceeding. Common issues: missing element references, duplicate IDs, syntax errors, undefined relationship kinds.
• Run validate after every non-trivial edit, not just at the end.

Example:

likec4 validate ./architecture

Previewing the Diagram

To let the user interactively preview the rendered diagram in a browser:

likec4 start [path]          # aliases: serve, dev

• Starts a local dev server with hot-reload — changes to .c4 files are reflected instantly.
• [path] is the directory containing your .c4 files (defaults to current directory).
• Opens at http://localhost:5173 by default (port may vary — check the terminal output).
• Tell the user to open that URL in their browser to navigate and inspect all views.

For a production-quality static preview (no hot-reload):

likec4 build [path]          # build the static site
likec4 preview [path]        # serve the built site locally

Use likec4 start during iterative development; use build + preview to verify the final output before sharing.

Reference Files

Read these before generating DSL for the corresponding diagram type:

• references/context.md — System Context view (C4 Level 1)
• references/container.md — Container / Service Map view (C4 Level 2)
• references/component.md — Component internals view (C4 Level 3)
• references/deployment.md — Deployment / infrastructure view
• references/dynamic.md — Dynamic / sequence / flow views
• references/trust-boundary.md — Trust / network boundary zones AND connection detail (protocols, ports, hostnames, service accounts, per-view levels)