From datum-platform
Covers creating C4 architecture diagrams using PlantUML. Use when documenting system architecture, component relationships, or container layouts for technical documentation.
npx claudepluginhub datum-cloud/claude-code-plugins --plugin datum-platformThis skill uses the workspace's default tool permissions.
This skill covers creating C4 model architecture diagrams using the PlantUML C4 plugin.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
This skill covers creating C4 model architecture diagrams using the PlantUML C4 plugin.
The C4 model provides four levels of abstraction for documenting software architecture:
| Level | Name | Purpose |
|---|---|---|
| 1 | Context | System in its environment with users and external systems |
| 2 | Container | High-level technology choices and responsibilities |
| 3 | Component | Components within a container |
| 4 | Code | Class/entity level (rarely needed) |
Include the C4 library at the start of your diagram:
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
' Your diagram here
@enduml
Available includes based on diagram level:
| Include | Use For |
|---|---|
C4_Context.puml | Level 1 - System Context diagrams |
C4_Container.puml | Level 2 - Container diagrams |
C4_Component.puml | Level 3 - Component diagrams |
C4_Dynamic.puml | Sequence-style interaction diagrams |
C4_Deployment.puml | Infrastructure and deployment diagrams |
| File | Purpose |
|---|---|
scripts/generate-diagrams.sh | Generate PNGs from .puml files using Docker |
context-diagrams.md | System context diagram patterns |
container-diagrams.md | Container diagram patterns |
component-diagrams.md | Component diagram patterns |
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
Person(user, "Platform User", "A user of the Datum Cloud platform")
Person_Ext(external, "External User", "External system user")
System(platform, "Datum Cloud Platform", "Multi-tenant Kubernetes platform")
System_Ext(github, "GitHub", "Source code repository")
Rel(user, platform, "Uses", "HTTPS")
Rel(platform, github, "Pulls code from", "HTTPS")
@enduml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
Person(user, "Platform User")
System_Boundary(platform, "Datum Cloud Platform") {
Container(api, "API Server", "Go", "Handles API requests")
Container(controller, "Controller", "Go", "Reconciles resources")
ContainerDb(db, "Database", "PostgreSQL", "Stores platform data")
}
Rel(user, api, "Uses", "HTTPS")
Rel(api, db, "Reads/Writes", "SQL")
Rel(controller, api, "Watches", "Kubernetes API")
@enduml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml
Container_Boundary(api, "API Server") {
Component(handler, "Request Handler", "Go", "Processes HTTP requests")
Component(storage, "Storage Backend", "Go", "Manages persistence")
Component(auth, "Auth Middleware", "Go", "Validates tokens")
}
Rel(handler, auth, "Uses")
Rel(handler, storage, "Uses")
@enduml
| Macro | Description |
|---|---|
Person(alias, label, description) | Internal user |
Person_Ext(alias, label, description) | External user |
| Macro | Description |
|---|---|
System(alias, label, description) | Internal system |
System_Ext(alias, label, description) | External system |
System_Boundary(alias, label) | Grouping boundary |
| Macro | Description |
|---|---|
Container(alias, label, technology, description) | Generic container |
ContainerDb(alias, label, technology, description) | Database container |
ContainerQueue(alias, label, technology, description) | Message queue |
Container_Boundary(alias, label) | Container grouping |
| Macro | Description |
|---|---|
Component(alias, label, technology, description) | Generic component |
ComponentDb(alias, label, technology, description) | Database component |
ComponentQueue(alias, label, technology, description) | Queue component |
| Macro | Description |
|---|---|
Rel(from, to, label) | Basic relationship |
Rel(from, to, label, technology) | Relationship with tech |
Rel_D(from, to, label) | Downward relationship |
Rel_U(from, to, label) | Upward relationship |
Rel_L(from, to, label) | Leftward relationship |
Rel_R(from, to, label) | Rightward relationship |
Control diagram layout with directional relationships and layout hints:
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
LAYOUT_WITH_LEGEND()
LAYOUT_LEFT_RIGHT()
' Elements will flow left to right
Container(a, "Service A", "Go", "First service")
Container(b, "Service B", "Go", "Second service")
Container(c, "Service C", "Go", "Third service")
Rel_R(a, b, "Calls")
Rel_R(b, c, "Calls")
@enduml
Layout macros:
| Macro | Effect |
|---|---|
LAYOUT_TOP_DOWN() | Vertical layout (default) |
LAYOUT_LEFT_RIGHT() | Horizontal layout |
LAYOUT_WITH_LEGEND() | Add legend to diagram |
LAYOUT_AS_SKETCH() | Hand-drawn style |
Customize colors and appearance:
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
' Custom colors
AddElementTag("critical", $bgColor="#ff0000", $fontColor="#ffffff")
AddElementTag("deprecated", $bgColor="#888888")
Container(api, "API Server", "Go", "Critical service", $tags="critical")
Container(legacy, "Legacy Service", "Java", "Being replaced", $tags="deprecated")
@enduml
Important: GitHub does not render PlantUML or C4 diagrams directly. You must:
.puml source filesPlace diagram sources and generated images in docs/architecture/:
docs/
└── architecture/
├── context.puml # Level 1 source
├── context.png # Generated image
├── containers.puml # Level 2 source
├── containers.png # Generated image
└── components/
├── api-server.puml # Level 3 source
├── api-server.png # Generated image
└── controller.puml
└── controller.png
Use the provided script to generate PNG images from PlantUML sources. The script uses Docker, so no local PlantUML installation is required.
# Generate PNGs for all .puml files in docs/architecture (default)
./skills/c4-diagrams/scripts/generate-diagrams.sh
# Generate PNGs for a custom directory
./skills/c4-diagrams/scripts/generate-diagrams.sh docs/diagrams
# Or use Docker directly
docker run --rm -v "$(pwd)/docs/architecture:/data" plantuml/plantuml -tpng "/data/*.puml"
Always regenerate PNGs when updating .puml files. Commit both the source and generated images.
Reference the generated PNG in your markdown documentation:
## System Context
The following diagram shows the system context for Datum Cloud Platform.

## Container View

Use relative paths from the markdown file to the PNG. Always include alt text describing the diagram.
@startuml C4_Context
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
LAYOUT_WITH_LEGEND()
title Datum Cloud Platform - System Context
Person(admin, "Platform Admin", "Manages platform configuration")
Person(developer, "Developer", "Deploys and manages workloads")
System(platform, "Datum Cloud Platform", "Multi-tenant Kubernetes platform for edge workloads")
System_Ext(github, "GitHub", "Source code and CI/CD")
System_Ext(cloud, "Cloud Providers", "GCP, AWS infrastructure")
System_Ext(monitoring, "Monitoring", "Observability stack")
Rel(admin, platform, "Configures", "CLI/API")
Rel(developer, platform, "Deploys to", "kubectl/API")
Rel(platform, github, "Pulls from", "HTTPS")
Rel(platform, cloud, "Provisions on", "Cloud APIs")
Rel(platform, monitoring, "Exports to", "OTLP")
@enduml
LAYOUT_WITH_LEGEND() for clarity