puml2c4

PlantUML C4 to LikeC4 transpiler — convert your existing PlantUML C4 diagrams to interactive LikeC4 visualizations.

Installation

npm install -g puml2c4

Usage

Live Mode (Watch & Serve)

Watch a directory of PlantUML files and automatically transpile to LikeC4:

puml2c4 live diagrams/

This outputs .c4 files to .likec4/ directory. Run likec4 serve .likec4/ in a separate terminal to view.

One-shot Convert

Convert PlantUML files once:

puml2c4 convert diagrams/ -o output/architecture.c4

Supported PlantUML C4 Elements

Elements

• Persons: Person, Person_Ext
• Systems: System, System_Ext, SystemDb, SystemDb_Ext, SystemQueue, SystemQueue_Ext
• Containers: Container, ContainerDb, ContainerQueue
• Components: Component, ComponentDb, ComponentQueue

Boundaries

• System_Boundary, Container_Boundary, Enterprise_Boundary
• Generic Boundary(id, "label", "type")

Deployment

• Deployment_Node(id, "label", "technology") - Infrastructure nodes
• Node(id, "label", "technology") - Alias for Deployment_Node
• Nested deployment nodes supported

Relationships

• Rel(from, to, "label", "technology") - Standard relationship
• Rel_U, Rel_D, Rel_L, Rel_R - Directional hints
• BiRel(a, b, "label") - Bidirectional relationship

Element Properties

All elements support optional named parameters:

• $tags="tag1+tag2" - Tags for categorization (emitted as #tag1, #tag2)
• $link="https://..." - External documentation link
• $sprite="icon" - Icon reference

Example:

Container(api, "API", "Go", "REST API", $tags="critical+monitored", $link="https://docs.example.com")

Example

Input (context.puml):

@startuml
!include C4_Context.puml

title System Context

Person(user, "User", "A customer")
System(app, "Application", "Main system")
System_Ext(email, "Email Service")

Rel(user, app, "Uses", "HTTPS")
Rel(app, email, "Sends notifications", "SMTP")
@enduml

Output (.likec4/context.c4):

specification {
  element actor {
    notation "Person/User"
    style { shape person }
  }
  element system {
    notation "Software System"
  }
  element external {
    notation "External System"
    style { color muted; border dashed }
  }
  // ... additional element kinds
}

model {
  user = actor "User" {
    description "A customer"
  }
  app = system "Application" {
    description "Main system"
  }
  email = external "Email Service"

  user -> app "Uses" {technology "HTTPS"}
  app -> email "Sends notifications" {technology "SMTP"}
}

views {
  view system_context {
    title "System Context"
    include user, app, email
    autoLayout TopBottom
  }
}

Why?

• Preserve your PlantUML investment — no need to rewrite existing C4 diagrams
• Interactive visualization — get LikeC4's navigation, zoom, and drill-down
• Incremental adoption — keep using PlantUML syntax while gaining modern tooling

License

MIT