Before diving into specific architectural layouts like C4 models or sequence timelines, it is essential to understand the foundational rules that govern the PlantUML Playbook. PlantUML relies on a clean, highly intuitive text notation system. Once you understand how the engine opens documents, names structural components, and routes connection lines, writing any complex system layout becomes completely natural.
This quick primer covers the global structural syntax mechanics that apply across almost every PlantUML diagram type inside the VPasCode workspace.
1. The Mandatory Document Wrappers
Every single block of PlantUML code must begin and end with explicit framework tags. These tags tell the VPasCode parser to spin up the correct rendering engine in your preview canvas:
@startuml— This exact line must be placed at the absolute top of your script. Nothing else should precede it.@enduml— This exact line must be placed at the absolute bottom of your script, marking the conclusion of your diagram data block.
Any code written outside of these two markers will be safely ignored by the compiler, or it may trigger a syntax validation warning in your workspace diagnostic panel.
2. Declaring Elements: IDs vs. Display Labels
When modeling a software system, you will create various structural elements like components, databases, actors, or microservices. In PlantUML, you can declare an element explicitly by defining its type, an internal shorthand ID, and a user-friendly display name wrapped in quotation marks:
component microservice_id as "Payment Processing API"
database db_id as "User Transaction SQL"Why this is a best practice: Using a short, clean internal ID (like microservice_id) makes drawing relationship lines much faster later on. If you ever need to change the customer-facing label from “Payment Processing API” to “Global Checkout Service”, you only have to edit it in one single line of code, rather than updating dozens of lines across your script.
3. Mastering Relationship Arrows and Directional Routing
Connections between system nodes are drawn using combinations of dashes (-) and arrow brackets (>). The length of your dashes and the inclusion of directional keywords give you implicit control over how the automated layout engine scales your diagram:
- Basic Connections:
A --> Bdraws a standard directed arrow pointing from element A straight to element B. - Dotted Dependency Lines: Substituting dashes with periods creates a dotted line, which is the industry standard for indicating asynchronous dependencies or network calls:
A ..> B. - Forcing Layout Orientation: While the layout engine spaces boxes out automatically, you can explicitly steer the orientation by inserting a direction keyword directly inside the arrow string:
A -up-> B(Forces B to render above A)A -down-> B(Forces B to render below A)A -left-> B(Forces B to render to the left of A)A -right-> B(Forces B to render to the right of A)
4. Adding Context Inline: Labels and Code Comments
Clear documentation relies heavily on putting appropriate context around your visual lines and text scripts:
Labeling Connection Lines
You can add explanatory text straight to any connection line by appending a colon (:) right after your relationship mapping:
client_id --> api_id : "HTTPS POST /v1/checkout"Writing Code Comments
If you want to leave an administrative note, design credit, or architectural explanation inside your script file without rendering a visual box on the canvas, use a single quote character ('). This tells the engine to skip parsing that line entirely:
' TODO: We need to update this boundary box once the DevOps migration finishes
[Legacy Monolith] --> [New Microservice]Now that you are familiar with the global syntax wrappers, component declarations, and directional arrow parameters of PlantUML, you are perfectly equipped to start building advanced system shapes. Proceed to the next page to unlock our collection of Architecture & High-Level Design Diagrams!