LikeC4 Skill

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)