VPasCode Docs

What is an Entity Relationship Diagram (ERD)? An Entity Relationship Diagram (ERD) is a structural blueprint used to design, document, and analyze relational database schemas. It outlines the specific data tables (entities) within an application, the columns (attributes) nested inside those tables, and the referential integrity rules that bind them together. Written using standard Information Engineering (IE) notation, it implements clear crow’s foot notation heads to show data constraints and multi-table dependencies. With Mermaid.js, you can define your production table indexes, data types, and foreign key connections using a clean, declarative text block. The engine automatically handles sizing for multi-column layout containers and routes connection lines without letting text labels overlap. Core Syntax Guide: Elements and Constructs Building a valid, fully runnable database schema in Mermaid relies on structural entity blocks, data type mappings, index tags, and cardinality operators. 1. Declaring Entities and Table Columns You initialize an ERD canvas on line one using the erDiagram keyword. To define a table, write the entity name followed by an open curly brace, listing your column configurations sequentially on individual lines: Mermaid Edit Mermaid in VPasCode erDiagram USERS { int id string email timestamp created_at } Edit Mermaid in VPasCode 2. Marking Primary Keys, Foreign Keys, and Comments Mermaid’s ERD engine allows you to assign structural indexing tags directly after the column name and data type definition. You can also append an optional text comment to a column by wrapping it in double quotes: PK — Explicitly flags a column as the table’s Primary Key. FK — Flags a column as a Foreign Key linked to a parent table. Mermaid Edit Mermaid in VPasCode erDiagram ORDERS { int id PK int user_id FK “Links to USERS.id” string coupon_code } Edit Mermaid in VPasCode 3. Mastering Crow’s Foot Cardinality Modifiers To connect tables and enforce referential integrity rules, map their relationships using specialized line operators. The character heads form visual crow’s foot shapes that dictate data multiplicity constraints: ||–|| **Exactly One to Exactly One:** A strict, mandatory 1:1 mapping. ||–o| **Exactly One to Zero or One:** An optional 1:1 dependency. ||–|{ **Exactly One to One or Many:** A mandatory 1:N parental linkage. ||–o{ **Exactly One to Zero, One, or Many:** A standard, optional 1:N relationship. Mermaid Edit Mermaid in VPasCode erDiagram USERS ||–o{ ORDERS : “places” Edit Mermaid in VPasCode Best Practices for Relational Data Schemas Maintain Consistent Table Casing: Keep entity names predictable. Use uppercase strings (e.g., USER_ACCOUNTS) or strict lowercase snake_case (e.g., user_accounts) to match your real-world SQL infrastructure code. Always Include Data Types: Avoid declaring raw column text without types. Explicitly listing definitions like int, varchar, or boolean ensures your architecture charts serve as an accurate technical reference. Keep Relationship Labels Verbs: When linking elements, provide a brief, lowercase active verb string inside your relationship assignment (e.g., ||–o{ : “contains”) to document the business logic mapping. Real-World Mermaid.js ERD Examples Example 1: Core E-Commerce Transactional Model (Keys & Mappings) This functional blueprint models a core e-commerce database transaction loop, showing how users, orders, and payment tracking systems link together using strict crow’s foot constraints. Mermaid Edit Mermaid in VPasCode erDiagram CUSTOMERS { int id PK string email string password_hash } ORDERS { int id PK int customer_id FK decimal total_amount string status } TRANSACTION_LEDGERS { int id PK int order_id FK string reference_token string gateway } CUSTOMERS ||–o{ ORDERS : “places” ORDERS ||–|| TRANSACTION_LEDGERS : “generates” Edit Mermaid in VPasCode Syntax Breakdown: This schema maps transaction boundaries cleanly. The mapping rules dictate that a customer can place zero or many orders over time (||–o{), while an individual order record must generate exactly one matching transaction ledger entry (||–||). Example 2: Enterprise Content Management System Schema (Many-to-Many Intersection) This advanced database blueprint maps out a content management platform architecture. It details how to resolve complex many-to-many configurations by introducing an explicit bridge mapping entity. Mermaid Edit Mermaid in VPasCode erDiagram POSTS { int id PK string title string slug text body_content } CATEGORIES { int id PK string name string description } POST_CATEGORY_MAPPINGS { int post_id PK, FK int category_id PK, FK timestamp assigned_at } COMMENTS { int id PK int post_id FK string author_name text comment_body } POSTS ||–o{ POST_CATEGORY_MAPPINGS : “contains” CATEGORIES ||–o{ POST_CATEGORY_MAPPINGS : “classifies” POSTS ||–o{ COMMENTS : “attaches” Edit Mermaid in VPasCode Syntax Breakdown: To handle the many-to-many relationship between `POSTS` and `CATEGORIES`, the script introduces an intersection table (`POST_CATEGORY_MAPPINGS`). This mapping box uses composite keys acting simultaneously as primary and foreign keys (PK FK), linking the outer nodes together using standard one-to-many crow’s foot connections.

What is a Flowchart? A Flowchart is a foundational behavioral map that visualizes a step-by-step operational workflow, algorithmic procedure, or sequential business logic. By representing system actions as distinct geometric shapes and charting the control flow with directional arrows, a flowchart makes it easy for software engineers and systems architects to trace conditional execution paths, isolate single-point-of-failure blocks, and analyze system logic loops before writing actual backend code. With Mermaid.js, you don’t have to spend hours dragging boxes, micro-managing grid lines, or recalculating padding variables. The layout engine computes node coordinates dynamically from your raw declarative scripts, letting you focus entirely on your system’s underlying logic. Core Syntax Guide: Elements and Constructs To design an elegant, highly scannable flowchart in Mermaid, you must master canvas direction indicators, geometric node enclosures, link wiring variables, and structural subgraphs. 1. Setting Canvas Directions The orientation of your flowchart is determined directly on line one by the keyword pairing applied to the graph or flowchart wrapper. You can control the visual scaling direction of your layout using four primary orientation keys: flowchart TD (Top to Down / Vertical orientation) flowchart BU (Bottom to Up orientation) flowchart LR (Left to Right / Horizontal orientation) flowchart RL (Right to Left orientation) 2. Customizing Node Geometry (Shapes) By default, a plain ID declaration renders as a sharp rectangular box. To make your diagrams easier to scan, use Mermaid’s specialized enclosing brackets to inject instant visual context into different workflow steps. Every single definition block must be preceded by a directional layout token to parse correctly: Round Edges: id(Text) — Represents a general process step. Stadium/Capsule Shape: id([Text]) — Standard marker for start and stop boundary milestones. Subroutine/Predefined Process: id[[Text]] — Represents an encapsulated system routine or external class script. Cylinder/Database: id[(Text)] — Represents database persistence, caches, or data warehouses. Rhombus/Decision Diamond: id{Text} — Represents conditional switches, if/else forks, or evaluation points. Parallelogram: id[/Text/] or id[\Text\] — Renders skewed boundaries to represent explicit data Input/Output (I/O). Mermaid Edit Mermaid in VPasCode flowchart TD start_node([Start Execution]) query_db[(PostgreSQL Instance)] validate_check{Is Authorized?} Edit Mermaid in VPasCode 3. Link Wiring Rules and Inlined Labels You can adjust your connector lines to represent different structural relationships and communication styles. To keep your charts clean, inject descriptive labels directly onto your link paths: Mermaid Edit Mermaid in VPasCode flowchart TD %% Standard connector arrow with text label A –> |”JSON Payload”| B %% Dotted/Asynchronous line with text label B -.-> |”Async Event”| C %% Thick bolded line with text label C ==> |”Critical Write”| D Edit Mermaid in VPasCode 4. Modular Isolation via Subgraphs To establish clean network perimeters, group microservices, or isolate team responsibilities, group your elements inside structural subgraph wrappers. You define a subgraph by giving it an internal ID, an optional display title, and closing it with an end tag: Mermaid Edit Mermaid in VPasCode flowchart TD subgraph auth_sub[“Security Boundary”] gateway[API Gateway] –> auth_worker(Token Validator) end Edit Mermaid in VPasCode Best Practices for Clean Flowcharts Decouple Layouts Horizontally: For long, multi-step engineering pipelines, choose a flowchart LR direction. This scales much cleaner on standard widescreen landscape monitors than a long vertical layout. Isolate Complex Loops: If a workflow contains a heavy repetition loop, label the reverse connector clearly (e.g., retry –> |”Attempt Reset”| start) to prevent readers from confusing the loop with a standard forward path. Avoid Mixing Graph Types: Stick to the modern flowchart keyword over the legacy graph flag when rendering complex maps. The flowchart engine uses an updated layout algorithm that supports advanced arrow combinations and cleaner path routing. Real-World Mermaid.js Flowchart Examples Example 1: Microservice Event-Driven Ingestion Mesh (Left-to-Right Architecture) This functional blueprint models a web telemetry ingestion service. It demonstrates how to combine data inputs, decision diamonds, and cloud database shapes across a crisp horizontal canvas. Mermaid Edit Mermaid in VPasCode flowchart LR %% Define element nodes with explicit geometry shapes init([Webhook Fired]) –> input_io[/Capture HTTP Request/] input_io –> auth_check{Validate Token} auth_check –> |”Invalid Token”| err_stop([Return 401 Unauthorized]) auth_check –> |”Valid JWT”| write_queue[[Publish to Kafka Queue]] write_queue –> worker_proc(Consumer Daemon) worker_proc –> db_store[(TimescaleDB Cluster)] db_store –> term([Terminated Flow]) %% Quick custom style overrides style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px Edit Mermaid in VPasCode Syntax Breakdown: This diagram flows smoothly from left to right. The validation step uses a yellow decision diamond shape (auth_check{Validate Token}), which splits the execution path cleanly into two distinct outcomes. The data stores are instantly recognizable thanks to their custom database cylinders ([(TimescaleDB Cluster)]) and parallelogram inputs. Example 2: Enterprise Multi-Tier User Registration Engine (Vertical with Nested Subgraphs) This advanced enterprise blueprint maps out an application registration pipeline. It organizes steps vertically across three separate structural subgraphs to represent distinct architectural layers. Mermaid Edit Mermaid in VPasCode flowchart TD subgraph Client_Tier[“Presentation UI Layer”] app[Mobile App UI] web[Web SPA Frontend] end subgraph Service_Tier[“Core Gateway Router”] proxy[[Nginx Ingress Reverse Proxy]] auth_svc(Auth Service Worker) end subgraph Persistence_Tier[“Secured Data Center”] main_db[(User Accounts Primary DB)] cache_node[(Redis Session Cache)] end %% Define communication pipelines across subsystem layers app — “HTTPS Request” –> proxy web — “HTTPS Request” –> proxy proxy –> |”Route /v1/auth”| auth_svc auth_svc –> |”Verify Session”| cache_node auth_svc –> |”Commit Account”| main_db Edit Mermaid in VPasCode Syntax Breakdown: The top-to-down orientation indicator (flowchart TD) forces the layout engine to stack components cleanly from top to bottom. Bounding blocks group related components into distinct layers (Client, Service, and Persistence), giving the overall architecture an intuitive, highly structured feel.

What is a Class Diagram? A Class Diagram is a structural UML diagram that visualizes the static architecture of an object-oriented software system. As an indispensable UML diagram type, it maps out the individual classes, interfaces, and data models within your application, explicitly documenting their internal fields (attributes), operational functions (methods), and the structural relationships that bind them together. This blueprint is vital for software engineers who need to translate high-level domain designs into clean, maintainable object structures. With Mermaid.js, you can outline your data models and system services using intuitive, text-based definitions. The layout engine automatically calculates box sizes, structures standard UML data compartments, and aligns relational arrows across your canvas without any manual formatting overhead. Core Syntax Guide: Elements and Constructs To design an accurate, standards-compliant UML class diagram in Mermaid, you must master member declarations, access modifiers, and structural relationship arrows. 1. Declaring Classes and Class Compartments You can define a class using two valid formats. For a simple class, use the class keyword followed by the class name. If you want to include fields and methods immediately, use trailing curly braces to create a clear body block: Mermaid Edit Mermaid in VPasCode classDiagram class UserProfile { +String username +String email +updateEmail(newEmail) void } Edit Mermaid in VPasCode 2. Adding Visibility / Access Modifiers To document standard UML encapsulation rules, place a specific symbol directly before your attribute or method name to define its visibility level: + **Public:** Accessible from any other class. – **Private:** Accessible only within the declaring class. # **Protected:** Accessible within the class and its subclasses. ~ **Package / Internal:** Accessible within the same package boundary. Mermaid Edit Mermaid in VPasCode classDiagram class BankAccount { -double balance #String accountHolder +getBalance() double } Edit Mermaid in VPasCode 3. Mastering Relationship Arrows and Inheritance Links To show how classes interact within your UML diagram model, connect their IDs using specialized relationship strings. In Mermaid, the direction of the line matters: the arrow head points toward the parent or container class. Inheritance / Generalization (Dashed or Solid Arrow): Child –|> Parent (Represents an “is-a” relationship). Realization / Implementation: Class ..|> Interface (Represents a class fulfilling an interface contract). Composition (Solid Diamond): Child –* Parent (Represents strict ownership; if the parent dies, the child dies). Aggregation (Clear Diamond): Child –o Parent (Represents a loose collection relationship; the child can exist independently). Dependency: ClassA ..> ClassB (Represents a transient runtime reference). Mermaid Edit Mermaid in VPasCode classDiagram Car –|> Vehicle : “Inherits from” Engine –* Car : “Is part of” Edit Mermaid in VPasCode Best Practices for Clean Class Architecture Layouts Group Class Members Visually: Always group your class variables at the top of the body block and your functions at the bottom. This layout matches standard IDE class structures and makes your diagrams instantly readable. Specify Return Types: When declaring methods, append the return type to the end of the method line (e.g., +fetchData() DataSet). This gives your engineering team precise implementation context. Keep Multiplicity Clear: To indicate array counts or collection sizes, append multiplicity text strings directly to the relationship line wrapper (e.g., Customer “1” –o “many” Order). Real-World Mermaid.js Class Diagram Examples Example 1: Payment Gateway Domain Subsystem (Encapsulation & Interfaces) This functional blueprint models an online checkout domain service. It demonstrates how to use access modifiers, group class members, and implement interface relationships cleanly. Mermaid Edit Mermaid in VPasCode classDiagram class PaymentProcessor { <<interface>> +processPayment(amount) boolean +refundPayment(txnId) boolean } class StripeGateway { -String apiKey -String endpointUrl +processPayment(amount) boolean +refundPayment(txnId) boolean -logTransaction(status) void } class PayPalGateway { -String merchantId +processPayment(amount) boolean +refundPayment(txnId) boolean } StripeGateway ..|> PaymentProcessor : “Implements” PayPalGateway ..|> PaymentProcessor : “Implements” Edit Mermaid in VPasCode Syntax Breakdown: The <<interface>> tag clearly marks `PaymentProcessor` as a high-level architectural contract. The two concrete gateway implementation classes use private fields (-apiKey) for sensitive credentials, while exposing public payment routines (+processPayment) linked via the realization arrow (..|>). Example 2: Enterprise Order Processing Engine (Composition & Multiplicity) This advanced system blueprint maps a complex e-commerce order management schema, demonstrating how to document structural ownership and object counts across multiple interconnected classes. Mermaid Edit Mermaid in VPasCode classDiagram class Customer { +int customerId +String name +placeOrder() Order } class Order { +int orderId +Date dateCreated -String internalStatus +calculateTotal() double } class OrderItem { +int itemId +int quantity +double pricePerUnit } class Address { +String street +String city +String postalCode } Customer “1” –o “many” Order : “owns” OrderItem “1..*” –* “1” Order : “composes” Address “1” –> Order : “ships to” Edit Mermaid in VPasCode Syntax Breakdown: This example illustrates the difference between aggregation and composition. The solid diamond arrow (–*) shows that an `OrderItem` is tightly bound to an `Order` (if an order is deleted, its individual line items are destroyed too). Conversely, the clear diamond arrow (–o) indicates that a `Customer` owns multiple orders, but both entities can exist independently. Multiplicity strings (like “1..*”) define the relational requirements of the system.

Before diving into specific architectural layouts like complex flowcharts or sequence timelines, it is essential to understand the foundational rules that govern the Mermaid Playbook. Mermaid relies on a clean, highly intuitive text notation system. Once you understand how the engine initializes a canvas type, names structural components, and routes directional arrows, writing any complex system layout becomes completely natural. This quick primer covers the global structural syntax mechanics that apply across almost every Mermaid diagram type inside the VPasCode workspace. 1. The Mandatory Diagram Type Wrappers Every single block of Mermaid code must begin by explicitly declaring its diagram archetype on the very first line. This tells the VPasCode parser exactly which structural engine to spin up in your preview canvas: graph TD — Specifies a Flowchart layout organized from Top to Down. sequenceDiagram — Specifies a chronological runtime Timeline chart. classDiagram — Specifies a structural Object-Oriented software blueprint. Unlike other text-to-diagram engines, Mermaid does not require trailing end-tags. The parser simply reads the structural declaration on line one and compiles everything nested directly below it within your code block container. 2. Declaring Elements: IDs vs. Display Labels When modeling a software system, you will create various structural elements like components, databases, or microservices. In Mermaid, you declare an element by defining a short, internal alphanumeric ID, followed immediately by a bracket style that controls its visual shape, and a user-friendly display name: microservice_id[Payment Processing API] db_id[(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 the single line where it is declared, 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 (-), equal signs (=), and arrow brackets (>). The style of your lines gives you implicit control over how the automated layout engine scales your diagram: A –> B draws a standard directed arrow pointing from element A straight to element B. A — B draws a flat, undirected link line with no arrow head, ideal for simple associations. A -.-> B creates a dotted dependency line, which is the industry standard for indicating asynchronous dependencies or network webhooks. A ==> B creates a thick, bolded connection line, perfect for highlighting primary data processing pathways or critical infrastructure links. 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 inserting the text string between two sets of dashes, or by appending a pipe character (|Text|) right after your relationship mapping: client_id — “HTTPS POST /v1/checkout” –> api_id client_id –> |HTTPS POST /v1/checkout| api_id 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 double percent signs (%%). 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]

What is the C4 Model Diagram? The C4 Model Diagram is a hierarchical, four-level architectural framework designed to document software architecture with varying degrees of granular detail. Created by Simon Brown, C4 avoids vague boxes and lines by structuring system maps into four explicit abstraction lenses: Context (System-level scope), Container (Applications and data stores), Component (Internal modules), and Code (Class-level implementations). To implement this model effectively in text, engineers use the official C4-PlantUML standard library extension. This library replaces raw UML shapes with specialized macros that auto-inject distinct colors, shapes, and metadata fields for users, systems, and databases. With VPasCode, you can define these nested environments cleanly in code. The layout engine dynamically routes connection vectors and scales text fields without ruining your layout geometry. Core Syntax Guide: Elements and Constructs Building a valid C4 model using PlantUML relies on importing the correct library files, selecting structural macros, establishing boundaries, and using specialized relationship links. 1. Importing the C4 Standard Library Files The C4-PlantUML extension is broken up into individual files that map directly to the distinct levels of the abstraction model. To prevent performance slowdowns or compiler errors, you should only import the specific file layer your diagram targets: PlantUML Edit PlantUML in VPasCode @startuml ‘ Include the specific C4 layer file required !include <C4/C4_Context> ‘ Use C4_Container or C4_Component for deeper architectural maps Edit PlantUML in VPasCode 2. Declaring Core Actors and Systems (Context Level) At the high-level System Context tier, you model internal components, external dependencies, and human end-users. The standard library provides specific macros that accept an ID, a visual label, and an optional descriptive tag: Person(id, “Label”, “Description”) — Represents a human user profile or system actor. System(id, “Label”, “Description”) — Represents a primary internal software application or service ecosystem. System_Ext(id, “Label”, “Description”) — Represents an external system or third-party API dependency (renders in an explicit grey color palette). PlantUML Edit PlantUML in VPasCode @startuml C4_Elements !include <C4/C4_Context> Person(customer, “Banking Customer”, “A customer with a personal bank account”) System(banking_sys, “Core Banking System”, “Handles financial transactions”) System_Ext(mail_sys, “E-mail Service”, “Internal SMTP notification gateway”) Edit PlantUML in VPasCode 3. Exploding Boundaries (Container & Component Levels) When diving deeper into the Container layer, you model web apps, microservices, and databases. You can isolate these internal elements inside an explicit logical boundary box using the System_Boundary() macro wrapper: PlantUML Edit PlantUML in VPasCode !include <C4/C4_Container> System_Boundary(c1, “E-Commerce System Eco-system”) { Container(web_app, “Single-Page Application”, “React & TypeScript”, “Provides user features via web view”) ContainerDb(database, “Relational Database”, “PostgreSQL”, “Stores user profile and ledger histories”) } Edit PlantUML in VPasCode 4. Mapping Technical Relationships Instead of relying on basic dashed lines, C4 utilizes explicit communication macros format as Rel(From_ID, To_ID, “Label”, “Technology”). This keeps your architecture maps highly readable by enforcing that every connection states its purpose and underlying transport protocol (such as HTTPS, gRPC, or AMQP): PlantUML Edit PlantUML in VPasCode !include <C4/C4_Container> Person(customer, “Banking Customer”, “A customer with a personal bank account”) System(banking_sys, “Core Banking System”, “Handles financial transactions”) System_Ext(mail_sys, “E-mail Service”, “Internal SMTP notification gateway”) System_Boundary(c1, “E-Commerce System Eco-system”) { Container(web_app, “Single-Page Application”, “React & TypeScript”, “Provides user features via web view”) ContainerDb(database, “Relational Database”, “PostgreSQL”, “Stores user profile and ledger histories”) } Rel(customer, web_app, “Uses storefront features via”, “HTTPS”) Rel(web_app, database, “Reads and writes transactional data via”, “SQL/TCP”) Edit PlantUML in VPasCode Best Practices for Readable C4 Architectures Never Mix Abstraction Levels: Keep your diagrams focused on a single layer. Do not mix fine-grained internal software components into a high-level System Context map. If a system gets too complex, break it out into a separate, dedicated Container-level diagram. Explicitly Define Technologies: Always make use of the fourth parameter in your Rel() macros to state the exact technology or protocol being used (e.g., “JSON/HTTPS” or “JDBC”). This gives your team crucial implementation context at a glance. Leverage Directional Layout Overrides: If your components begin to stack up awkwardly, use directional relationship macros (like Rel_D() for down, Rel_R() for right, or Rel_L() for left) to manually clean up your architectural flow. Real-World PlantUML C4 Examples Example 1: High-Level System Context Layout (Level 1) This functional blueprint models a standard Level 1 System Context diagram, detailing how a customer interacts with an internet banking application and its external dependencies. PlantUML Edit PlantUML in VPasCode @startuml !include <C4/C4_Context> title System Context Diagram for Internet Banking System Person(customer, “Personal Banking Customer”, “A customer of the bank with personal accounts.”) System(banking_system, “Internet Banking System”, “Allows customers to view financial info and make transfers.”) System_Ext(mail_system, “E-mail Subsystem”, “The internal enterprise SendGrid corporate mail server cluster.”) Rel(customer, banking_system, “Uses online dashboard via”) Rel_R(banking_system, mail_system, “Sends alerts and verification codes using”, “SMTP”) @enduml Edit PlantUML in VPasCode Syntax Breakdown: This diagram focuses purely on high-level scope. The System_Ext macro automatically applies a grey color profile to the e-mail service, visually separating the core system from external dependencies. The Rel_R macro forces the layout engine to place the email node directly to the right of the banking system block. Example 2: Deep-Dive Microservice Container Topology (Level 2) This advanced enterprise blueprint breaks down a system into its constituent container applications and isolated data stores, showing how web traffic routes through an API gateway down to backend microservices. PlantUML Edit PlantUML in VPasCode @startuml !include <C4/C4_Container> title Container Diagram for Payment Portal Gateway Person(merchant, “Web Merchant Partner”, “Integrates platform checkout endpoints into their websites.”) System_Boundary(portal_scope, “Payment Gateway Ecosystem”) { Container(api_gateway, “API Routing Proxy”, “Nginx”, “Intercepts inbound calls, handles rate limits and balances nodes.”) Container(auth_service, “Identity Microservice”, “Go & OAuth2”, “Validates developer API tokens and scopes.”) Container(txn_service, “Transaction Ledger”, “Java Spring Boot”, “Processes payments and manages ledger accounts.”) ContainerDb(ledger_db, “Ledger Datastore”, “CockroachDB”, “Implements distributed ACID-compliant table schemas.”) } ‘ Route traffic flows cleanly across internal container targets Rel(merchant, api_gateway, “Submits payment payloads via”, “HTTPS/JSON”) Rel_D(api_gateway, auth_service, “Validates incoming tokens via”, “gRPC”) Rel_D(api_gateway, txn_service, “Forwards checkout actions to”, “gRPC”) Rel_R(txn_service, ledger_db, “Persists ledger entries via”, “SQL/TLS”) @enduml Edit PlantUML in VPasCode Syntax Breakdown: By using the System_Boundary macro wrapper, internal

What is an ArchiMate Diagram? An ArchiMate Diagram is a high-level enterprise architecture modeling visualization that tracks strategies, business processes, software applications, and physical data infrastructure across an organization. Unlike traditional UML maps that look deep into software execution routines, ArchiMate helps business analysts, solutions architects, and CTOs map how high-level corporate goals depend on underlying IT systems. While basic PlantUML contains native primitives, production-grade enterprise layouts require the official Archimate-PlantUML standard library extension. By utilizing declarative macros and standardized color bands, it allows you to maintain consistent, TOGAF-compliant models. With VPasCode, you can define your architectural blocks and relational threads entirely in text, letting the engine handle box color schemes and alignment dynamically. Core Syntax Guide: Elements and Constructs To use the official ArchiMate extension safely in PlantUML, you must include the standard library file, implement category macros correctly, handle nesting blocks, and apply explicit structural relationships. 1. Initializing the ArchiMate Standard Library To unlock the official macros, color palettes, and structural stereotypes, your script block must import the standard library file directly below your startup tag. You can optionally apply one of the official themes to ensure high-contrast visibility: PlantUML Edit PlantUML in VPasCode @startuml !include <archimate/Archimate> !theme archimate-standard from <archimate/themes> Edit PlantUML in VPasCode 2. Declaring Elements Using Category Macros The standard library simplifies element creation by wrapping native shapes inside category-prefixed macros. Elements follow a strict Category_ElementName(ID, “Label”) naming convention. The prefix determines the structural layer and auto-injects the correct color token: Strategy & Motivation (Purple): Motivation_Stakeholder(), Strategy_Capability() Business Layer (Yellow): Business_Actor(), Business_Process(), Business_Service() Application Layer (Blue): Application_Component(), Application_Service() Technology Layer (Green): Technology_Node(), Technology_SystemSoftware() PlantUML Edit PlantUML in VPasCode !include <archimate/Archimate> Motivation_Stakeholder(CEO, “Chief Executive Officer”) Application_Component(CRM, “Salesforce CRM System”) Edit PlantUML in VPasCode 3. Defining Group Boundaries and Structural Nesting Enterprise maps rely heavily on visual containment to represent ownership or runtime isolation. You can create bounding folders using the Group() or Grouping() macros, or nest elements inside one another using curly braces: PlantUML Edit PlantUML in VPasCode !include <archimate/Archimate> Grouping(AppSubsystem, “Customer Management Suite”) { Application_Component(AuthMod, “OAuth Token Module”) Application_Service(UserReg, “User Registration API”) } Edit PlantUML in VPasCode 4. Mapping Standardized Enterprise Relationships ArchiMate enforces a strict vocabulary for connections. Instead of raw arrows, the standard library offers dedicated relationship macros formatted as Rel_RelationType(From_ID, To_ID, “Label”). To force manual orientation adjustments, you can append spatial directional hints (such as _Up, _Down, _Left, or _Right): PlantUML Edit PlantUML in VPasCode !include <archimate/Archimate> Motivation_Stakeholder(CEO, “Chief Executive Officer”) Application_Component(CRM, “Salesforce CRM System”) Grouping(AppSubsystem, “Customer Management Suite”) { Application_Component(AuthMod, “OAuth Token Module”) Application_Service(UserReg, “User Registration API”) } ‘ Structural & Behavioral relationship examples Rel_Realization(UserReg, AuthMod, “Implements security”) Rel_Serving_Right(CRM, CEO, “Provides dashboards”) Edit PlantUML in VPasCode Best Practices for Layered Architecture Diagrams Isolate Distinct Layers: Organize your scripts sequentially from top to bottom (Motivation > Business > Application > Technology) to make your architecture layouts intuitive for stakeholders. Leverage Short Component IDs: Keep your internal macro tracking strings brief (e.g., use AP_01 or Srv_Auth), while reserving descriptive, customer-facing text for the double-quoted label parameter. Enforce Explicit Directions on Cross-Layer Wires: Layout paths can shift unpredictably when crossing structural boundaries. Using directional macros like Rel_Access_Down() ensures your data flows move smoothly downward across layer splits. Real-World PlantUML ArchiMate Examples Example 1: Classic Strategic Capabilities Mapping (Motivation & Strategy Tiers) This functional blueprint documents the strategic layer of an organization, illustrating how corporate stakeholders align with business capabilities and realized technical outcomes. PlantUML Edit PlantUML in VPasCode @startuml !include <archimate/Archimate> !theme archimate-standard from <archimate/themes> title Strategic Enterprise Alignment Map Motivation_Stakeholder(CFO, “Chief Financial Officer”) Motivation_Driver(CostEfficiency, “Operational Cost Reduction”) Strategy_Capability(AutomatedBilling, “Enterprise Invoicing Automation”) Business_Process(InvoiceRun, “End-of-Month Ledger Reconciliation”) ‘ Wire strategic dependencies Rel_Association(CFO, CostEfficiency, “Seeks to improve”) Rel_Influence(AutomatedBilling, CostEfficiency, “Positively impacts”) Rel_Realization(InvoiceRun, AutomatedBilling, “Fulfills capability”) @enduml Edit PlantUML in VPasCode Syntax Breakdown: By executing the purple strategic macros, the engine maps elements out cleanly. Clear relational macros link the human stakeholder down through organizational motivations, aligning corporate strategy cleanly with underlying execution behaviors. Example 2: End-to-End Three-Tier Enterprise System (Cross-Layer Mesh) This advanced blueprint demonstrates a comprehensive, cross-layer architecture topology. It maps an operational business process down through supporting application microservices to the underlying cloud infrastructure host. PlantUML Edit PlantUML in VPasCode @startuml !include <archimate/Archimate> !theme archimate-standard from <archimate/themes> title Multi-Tier Application Architecture Alignment Grouping(BizLayer, “Business Operations”) { Business_Actor(Agent, “Customer Service Support Agent”) Business_Process(Ticketing, “Process Enterprise Support Ticket”) } Grouping(AppLayer, “Application Ecosystem”) { Application_Service(TicketSvc, “Zendesk Integration API”) Application_Component(DataRouter, “Event Processing Engine”) } Grouping(TechLayer, “Infrastructure Tier”) { Technology_SystemSoftware(K8sCluster, “Kubernetes Orchestration Cluster”) Technology_Node(CloudVM, “AWS EC2 m6i.xlarge Compute Target”) } ‘ Establish cross-layer mappings smoothly using directional hints Rel_Assignment(Agent, Ticketing, “Executes daily”) Rel_Serving_Down(TicketSvc, Ticketing, “Powers web desk ui”) Rel_Composition(DataRouter, TicketSvc, “Ingests webhooks from”) Rel_Realization_Down(K8sCluster, DataRouter, “Hosts application container”) Rel_Composition_Down(CloudVM, K8sCluster, “Provides core hypervisor bare-metal”) @enduml Edit PlantUML in VPasCode Syntax Breakdown: This map highlights the power of structured Grouping components. Elements automatically receive distinct, layer-specific color tints (Yellow, Blue, Green) based on their macro families. Directional relationship overrides like Rel_Serving_Down and Rel_Realization_Down force dependencies to cascade elegantly down the enterprise grid.

What is an Entity Relationship Diagram (ERD)? An Entity Relationship Diagram (ERD) is a structural blueprint used to design, document, and analyze relational databases. It visualizes the tables (entities) within a system, the specific columns (attributes) they contain, and how those tables link together. In PlantUML, ERDs are authored using the Information Engineering (IE) notation, which implements standard crow’s foot notation to represent relational constraints. Whether you are designing a microservice data store, optimizing SQL join paths, or mapping out an enterprise-wide data warehouse architecture, a text-driven UML ERD ensures your database schemas are perfectly clear. With VPasCode, you can define your database tables, index keys, and logical relationships using a clean, declarative syntax. The engine automatically handles table box sizing and routes your foreign key connector strings without any overlapping layout lines. Core Syntax Guide: Elements and Constructs Building a robust IE-style ERD in PlantUML relies on structured entity blocks, explicit key designations, and crow’s foot cardinality modifiers. 1. Declaring Entities (Database Tables) You declare a database table using the entity keyword, followed by the table name and a set of curly braces. Inside the braces, you list your table columns. To make your schema clean and readable, use a horizontal line separator (–) to separate your primary/foreign keys from standard data attributes: PlantUML Edit PlantUML in VPasCode entity “users” as users_table { id : INT [PK] — email : VARCHAR(255) created_at : TIMESTAMP } Edit PlantUML in VPasCode 2. Designating Primary and Foreign Keys While text indicators like `[PK]` or `[FK]` work well, PlantUML’s IE engine also supports visual key icons. Placing an asterisk (*) before an attribute designates it as a **mandatory (not null)** column, while a clean text string or tag adds explicit indexing context: PlantUML Edit PlantUML in VPasCode entity “orders” { * id : INT <<PK>> — * user_id : INT <<FK>> discount_code : VARCHAR(50) } Edit PlantUML in VPasCode 3. Mapping Crow’s Foot Cardinality and Relationships To connect tables and enforce referential integrity constraints, use a combination of dashes, brackets, and pipe characters. In IE notation, these symbols form distinct **crow’s foot** heads that represent database relationships: ||–|| **Exactly One to Exactly One:** A strict, mandatory one-to-one mapping. ||–o| **Exactly One to Zero or One:** An optional one-to-one mapping. ||–|{ **Exactly One to One or Many:** A mandatory one-to-many dependency. ||–o{ **Exactly One to Zero, One, or Many:** A standard, optional one-to-many relationship. PlantUML Edit PlantUML in VPasCode users_table ||–o{ orders : “places” Edit PlantUML in VPasCode Best Practices for Clean Database Schemas Maintain Casing Conventions: Keep your entity declarations predictable. Use lowercase snake_case (e.g., order_items) for actual SQL-mapped tables, or use uppercase CamelCase for conceptual domain models. Always Document Foreign Keys: When linking two tables, always specify the foreign key column inside the child table block. This provides clear reference contexts for engineering teams during data migrations. Control Crow’s Foot Spacing: Complex database schemas with dozens of tables can quickly become crowded. If your relationship lines begin to cross unnaturally, replace your double-dash connectors (–) with three or four dashes (—) to push the tables apart and allow the layout engine more room to organize the grid. Real-World PlantUML ERD Examples Example 1: Core Core E-Commerce Relational Model (Keys & Mappings) This functional blueprint models a core e-commerce database transaction loop, showing how users, orders, and payment ledgers link together using strict crow’s foot relationships. PlantUML Edit PlantUML in VPasCode @startuml ‘ Freeze entity box rendering into sharp modern squares hide circle skinparam LINETYPE ortho entity “users” as user { * id : INT <<PK>> — * email : VARCHAR(100) * password_hash : VARCHAR(255) phone : VARCHAR(20) } entity “orders” as order { * id : INT <<PK>> — * user_id : INT <<FK>> * total_amount : DECIMAL(10,2) status : VARCHAR(50) } entity “payment_ledgers” as ledger { * id : INT <<PK>> — * order_id : INT <<FK>> * transaction_reference : VARCHAR(100) gateway : VARCHAR(50) } ‘ Define relational schema bindings user ||–o{ order : “places” order ||–|| ledger : “generates” @enduml Edit PlantUML in VPasCode Syntax Breakdown: The directive hide circle disables the default UML class token bubbles, while skinparam LINETYPE ortho forces relationship paths into clean 90-degree right angles. The schema clearly shows that a user can place zero or many orders (||–o{), while an order must have exactly one associated payment ledger record (||–||). Example 2: Advanced Content Management System Schema (Many-to-Many Intersection) This advanced enterprise blueprint maps a complete content management system (CMS) topology. It showcases how to handle many-to-many architectures cleanly by leveraging an intermediate mapping table. PlantUML Edit PlantUML in VPasCode @startuml hide circle skinparam LINETYPE ortho entity “posts” as post { * id : INT <<PK>> — * author_id : INT <<FK>> * title : VARCHAR(255) slug : VARCHAR(255) body : TEXT } entity “categories” as category { * id : INT <<PK>> — * name : VARCHAR(100) description : VARCHAR(255) } entity “post_category_mappings” as mapping { * post_id : INT <<PK>><<FK>> * category_id : INT <<PK>><<FK>> — assigned_at : TIMESTAMP } entity “comments” as comment { * id : INT <<PK>> — * post_id : INT <<FK>> author_name : VARCHAR(100) * content : TEXT } ‘ Relational link structures post ||–o{ mapping : “contains” category ||–o{ mapping : “categorizes” post ||–o{ comment : “attaches” @enduml Edit PlantUML in VPasCode Syntax Breakdown: This template models a classic many-to-many relationship between posts and categories. Rather than connecting them directly, it introduces an intermediate table (post_category_mappings) where both columns serve as a composite primary key. The crow’s foot indicators explicitly map the cascading relationships down to the comments layer.

What is a Timing Diagram? A Timing Diagram is a specialized behavioral UML diagram designed to visualize the exact duration of states and the precise conditions under which those states change along a linear timeline. As an essential part of the Unified Modeling Language (UML) specification, this specific UML diagram type focuses heavily on hard time constraints, clock cycles, and wave signals. It tracks waveforms or step-lines to illustrate exactly how long an object remains in a specific condition before an external trigger shifts its state. Timing maps are widely used by embedded systems engineers, network protocol developers, and hardware architects to model race conditions, track thread lifecycle changes, or map hardware register transitions. With VPasCode, you don’t have to manually calculate pixel widths or map timeline coordinates. Our rendering engine handles the entire temporal grid automatically based on your plain-text scripts. Core Syntax Guide: Elements and Constructs To design an accurate, standards-compliant UML timing diagram in PlantUML, you need to master participant types, state definitions, time intervals, and synchronization constraints. 1. Declaring Participants (Robust vs. Concise) You can model timelines using two distinct visual styles depending on how much detail your system requires. You must declare them using explicit keywords: Robust Timelines: Displays states as distinct, stacked rows. Ideal for high-level software processes. robust “Application Thread” as Thread Concise Timelines: Displays states along a single flat line, using cross-hatched blocks to indicate changes. Perfect for compact hardware signal maps. concise “CPU Register” as Reg 2. Defining State Transitions and Time Steps Unlike other diagrams, you change states by declaring a time checkpoint using the @ symbol, referencing your participant, and using the is keyword. State names containing spaces or special characters must be wrapped in quotation marks: @0 Thread is Idle @10 Thread is “Processing Data” 3. Generating Clock Signals To simulate binary hardware clocks, use the clock keyword. You must specify a cycle period, an optional duty cycle, and an internal name: clock “System Clock” as CLK with period 2 4. Adding Precision Constraints and Time Slates To document strict execution deadlines (such as ensuring a system transition happens within a specified window), use the <-> syntax to bridge two time coordinates with a descriptive label: @10 <-> @40 : {Less than 30ms} Best Practices for Clean Timing Layouts Keep Time Units Uniform: PlantUML treats timeline integers as generic sequential steps. Choose a uniform time unit for your project (e.g., ticks, microseconds, or seconds) and maintain it consistently. Use Labels for Intricate Transitions: You can append text messages directly onto state changes by adding a colon immediately after the state assignment (e.g., @10\nReg is Reading : “Trigger Interrupt”). Order Declarations Strategically: PlantUML stacks lifelines vertically in the exact order they are declared in your script. Always put your master clocks at the very top for easier alignment. Real-World PlantUML Timing Diagram Examples Example 1: Microcontroller Cache & Register States (Concise & Clock Waveforms) This runnable blueprint demonstrates a classic embedded hardware engineering timeline, running a standard system clock alongside a concise data storage register tracking hardware states. PlantUML Edit PlantUML in VPasCode @startuml clock “System Clock (CLK)” as clk with period 2 concise “Data Bus Register” as Reg @0 Reg is Empty @2 Reg is Reading : “Fetch” @6 Reg is Writing @10 Reg is Locked @14 Reg is Empty @enduml Edit PlantUML in VPasCode Syntax Breakdown: The clock directive creates a rhythmic high/low square wave automatically. The Reg line handles multiple state assignments sequentially over the absolute timeline grid. Text strings appended with a colon (like : “Fetch”) render as neat callouts directly over the transition boundary line. Example 2: Async Web Consumer Token Refresh (Robust Multi-Thread Constraints) This advanced, fully functional software architecture blueprint leverages the robust layout format to trace a multi-threaded web application workflow, mapping precise timing deadlines between a web client and an authorization worker. PlantUML Edit PlantUML in VPasCode @startuml robust “Web Browser Client” as Web robust “Auth Token Worker” as Auth @0 Web is Idle Auth is Sleep @5 Web is AwaitingToken Auth is Validating @15 Auth is Generating @15 <-> @25 : {Generation Window} @25 Auth is Sleep Web is RenderingPage @40 Web is Idle @enduml Edit PlantUML in VPasCode Syntax Breakdown: By using the robust declaration, the states are cleanly listed on the Y-axis for each individual lifeline row. The time evaluation constraint (@15 <-> @25 : {Generation Window}) draws a standard double-sided dimension arrow across the top of the timeline grid, indicating a strict operational limit.

What is a Deployment Diagram? A Deployment Diagram is a structural UML diagram that models the physical execution architecture of a software system. As a core standard of the Unified Modeling Language (UML) specification, this specific UML diagram type maps out how software components are physically deployed onto hardware hosting targets, cloud infrastructure elements, or container runtimes. It provides system engineers, DevOps professionals, and network architects with a clear layout of server cluster boundaries, database replication paths, load balancer tiers, and hardware network protocols across development and production regions. With VPasCode, you don’t need to struggle with complex vector grouping shapes or manual coordinate mapping. By using plain declarative script blocks, our engine automatically groups, calculates, and nests your hardware node structures cleanly. Core Syntax Guide: Elements and Constructs To design an accurate, standards-compliant UML deployment diagram in PlantUML, you need to master hardware nodes, execution environments, deployment artifacts, and network linkages. 1. Declaring Infrastructure Cubes (Nodes) In a deployment layout, physical computing resources are represented as 3D three-dimensional cubes. You declare these elements using the node keyword, or by choosing specialized variants that give readers instant visual context about the hardware tier: PlantUML Edit PlantUML in VPasCode node “Bare Metal Application Server” as CoreServer node Server1 database “Database Server” as DB_Node Edit PlantUML in VPasCode 2. Modeling Cloud Layers and Virtual Environments Modern applications are rarely deployed straight onto physical hardware. PlantUML provides nested grouping wrappers to represent logical execution boundaries, cloud provider footprints, or virtual container runtimes like Docker and Kubernetes: cloud — Represents external public web tiers or cloud network boundaries (e.g., AWS, Azure). frame — Represents virtual systems or organizational regions. storage — Represents physical SAN configurations or object store locations. PlantUML Edit PlantUML in VPasCode cloud “Amazon Web Services VPC” { node “EC2 Linux Instance” as WorkerNode } Edit PlantUML in VPasCode 3. Defining Deployment Artifacts (What Runs Where) An artifact represents the actual physical file (such as a compiled JAR file, a static build folder, or a zipped package) that is deployed onto a node. You declare an artifact using the artifact keyword, or place it inside your hardware blocks directly: PlantUML Edit PlantUML in VPasCode node “Application Server” { artifact “api_v1.0.war” as API_File } Edit PlantUML in VPasCode 4. Mapping Network Communication Links Connections between infrastructure elements represent concrete physical networks, wire paths, or wireless channels. You map these links using solid double dashes (–), and append text inside quotes to explicitly define the network protocol used (e.g., HTTPS, TCP/IP, SSH): PlantUML Edit PlantUML in VPasCode node Server1 node DB_Node Server1 — DB_Node : “TCP/IP (Port 5432)” Edit PlantUML in VPasCode Best Practices for Practical Deployment Maps Nest Structures Correctly: Always draw your internal components or artifacts *inside* the curly brackets of your node declarations to clearly show execution residency. Label Communication Protocols: Never draw a blank line between servers. Always label the connection with its primary communication protocol (e.g., “HTTPS (Port 443)”) to help network and security reviews. Isolate Availability Zones: When documenting high-availability cloud configurations, use separate frame wrappers to illustrate split region setups (e.g., us-east-1a vs. us-east-1b). Real-World PlantUML Deployment Diagram Examples Example 1: Classic Three-Tier Web Setup (Nodes & Protocols) This boilerplate models a standard modern corporate application structure, mapping an external content distribution network, an application server cluster, and a secured internal database host tier. PlantUML Edit PlantUML in VPasCode @startuml cloud “Public Internet” as net node “Cloudflare CDN Edge” as cdn frame “Demilitarized Zone (DMZ)” { node “Nginx Load Balancer Server” as proxy } frame “Private Application VPC Subnet” { node “Ubuntu Server 22.04” as app_node { artifact “core_api.jar” as application } } database “Managed Database Tier” { node “PostgreSQL Primary Cluster” as db_master } ‘ Establish topological connection wires net — cdn : “HTTPS” cdn — proxy : “HTTPS (TLS 1.3)” proxy — app_node : “HTTP (Port 8080)” app_node — db_master : “TCP/IP (Port 5432)” @enduml Edit PlantUML in VPasCode Syntax Breakdown: This map clearly dictates security perimeters. The compiled asset core_api.jar is nested safely inside the app_node server box. Network pathways scale cleanly inward, establishing strict protocol rules for every segment from the public web edge down to the managed database tier. Example 2: Cloud-Native Container Architecture (Kubernetes & AWS Mesh) This advanced enterprise blueprint maps a highly scalable, multi-region cloud deployment. It utilizes nested node layouts to visualize a load-balanced Kubernetes container system interacting with standalone cloud databases. PlantUML Edit PlantUML in VPasCode @startuml cloud “Amazon Web Services (AWS)” { node “AWS Application Load Balancer” as alb frame “Availability Zone: us-east-1a” { node “EC2 Worker Node Node A” as ec2_a { node “K8s Pod: Web Frontend” as pod_web_a node “K8s Pod: Order API” as pod_api_a } } frame “Availability Zone: us-east-1b” { node “EC2 Worker Node Node B” as ec2_b { node “K8s Pod: Web Frontend” as pod_web_b node “K8s Pod: Order API” as pod_api_b } } storage “AWS Aurora Serverless Clusters” { database “Customer Database” as rds_db } } ‘ Route infrastructure orchestration lines alb — pod_web_a : “HTTP Round-Robin” alb — pod_web_b : “HTTP Round-Robin” pod_web_a — pod_api_a : “Internal gRPC” pod_web_b — pod_api_b : “Internal gRPC” pod_api_a — rds_db : “SSL/TCP” pod_api_b — rds_db : “SSL/TCP” @enduml Edit PlantUML in VPasCode Syntax Breakdown: By nesting node targets within child node structures, this template models a containerized layout perfectly (Pods executing inside EC2 Virtual Machines). The application load balancer seamlessly distributes incoming requests across availability zones, while the cluster components route database calls back into a shared storage pool.

What is a Component Diagram? A Component Diagram is a structural UML diagram that maps out the high-level modular organization of a software system. As a vital component of the Unified Modeling Language (UML) specification, this specific UML diagram type visualizes how physical code modules, libraries, microservices, execution packages, and database layers are structurally grouped and interconnected. It shifts the documentation focus away from fine-grained class definitions, allowing software architects and principal engineers to illustrate system integration boundaries, API orchestration paths, and third-party dependencies clearly. Whether you are outlining a modern cloud-native microservice topology or showing how an internal framework library hooks into your legacy application core, a UML component map provides a clear, structural overview of system boundaries. With VPasCode, your component layouts are rendered automatically based on declarative text, eliminating the hassle of manually adjusting layout boxes or connector wires. Core Syntax Guide: Elements and Constructs To design an elegant, standards-compliant UML component diagram in PlantUML, you need to master modular code block declarations, interface wiring mechanics, system package groupings, and directional connection parameters. 1. Declaring Software Components You declare a software module using the component keyword. Alternatively, you can wrap a clean text identifier inside square brackets ([Component Name]), which acts as a global shorthand indicator: PlantUML Edit PlantUML in VPasCode component PaymentEngine [Auth Service] as AuthService Edit PlantUML in VPasCode Pro Tip: Always pair long component strings with an as identifier (like as AuthService) to keep relationship lines clean and readable. 2. Defining Ports and Interfaces Components interact with one another through structural entry points. You can explicitly model standard UML interfaces (represented visually by a clean “lollipop” circle icon) using the interface keyword: PlantUML Edit PlantUML in VPasCode interface “REST API v2” as WebAPI [AuthService] –() WebAPI : “exposes” Edit PlantUML in VPasCode 3. Mapping Component Dependencies To show that one system module relies on or communicates with another, use directional arrows (–>). You can also use standard dotted dependency lines (..>) to represent looser relationships, like message-queue consumption patterns or transient runtime calls: PlantUML Edit PlantUML in VPasCode [Frontend App] –> WebAPI WebAPI ..> [Database Engine] : “SQL Queries” Edit PlantUML in VPasCode 4. Organizing Boundaries with Packages To establish clean sub-system borders or categorize components based on deployment environments, wrap your module blocks inside structural package or cloud wrappers: PlantUML Edit PlantUML in VPasCode package “Security Context” { [Auth Service] [Token Validator] } Edit PlantUML in VPasCode Best Practices for Clean Component Sub-Systems Keep Node Names High-Level: Avoid naming components after specific internal code files or directories. Use functional, high-level names like [Notification Router] or [Cache Layer]. Leverage the Lollipop Notation: Instead of drawing plain lines between boxes, route connections through explicit interface nodes. This clearly distinguishes *what* interface is being exposed from *who* is consuming it. Control Layout Expansion: Component maps expand quickly when tracking multiple sub-systems. Use spatial flags inside your dependency arrows (such as -right-> or -down->) to organize your components cleanly across the canvas grid. Real-World PlantUML Object Diagram Examples Example 1: Core API Gateway Mesh (Interfaces & Package Groupings) This boilerplate demonstrates a standard multi-tier system web setup, highlighting how a public user application hooks into internal microservices through structured REST API interfaces. PlantUML Edit PlantUML in VPasCode @startuml package “Public Presentation Layer” { [Web SPA Client] as client [Mobile iOS Client] as mobile } package “API Gateway Subsystem” { interface “HTTPS Gateway Endpoint” as HTTP_GW [Kong API Gateway] as gateway } package “Core Backend Services” { interface “User Management API” as UserAPI interface “Billing API” as BillingAPI [Identity Service] as auth [Payment Processing Engine] as billing } ‘ Wire presentation to gateway client –> HTTP_GW mobile –> HTTP_GW HTTP_GW — gateway ‘ Wire gateway to backend interfaces gateway –> UserAPI gateway –> BillingAPI UserAPI — auth BillingAPI — billing @enduml Edit PlantUML in VPasCode Syntax Breakdown: By nesting modules inside clean package boundaries, the automated layout engine creates beautifully distinct zones. The presentation clients connect exclusively to the single exposed HTTP_GW gateway port, which then manages internal traffic routing to the specialized backend microservice layers below. Example 2: Cloud Data Processing Pipeline (Asynchronous Clouds & Queues) This advanced enterprise blueprint maps a real-world asynchronous cloud data architecture, tracing ingestion pipelines, decoupled message brokers, and physical storage endpoints. PlantUML Edit PlantUML in VPasCode @startuml cloud “AWS Cloud Network Boundary” { [Ingestion Webhook] as webhook queue “Apache Kafka Cluster” as broker [Stream Processor Event Worker] as worker database “Amazon S3 Data Lake” as storage } database “Corporate Data Warehouse” as redshift ‘ Processing pipeline flow mechanics [External Client App] –> webhook : “POST /telemetry” webhook -right-> broker : “Publish raw logs” broker ..> worker : “Consume topic data stream” worker –> storage : “Write compressed Parquet files” storage ..> redshift : “Nightly ETL Synchronization” @enduml Edit PlantUML in VPasCode Syntax Breakdown: This example introduces the specialized cloud and queue shapes, giving developers immediate visual cues about structural topology. The use of the horizontal arrow override -right-> ensures that data ingestion flows smoothly from left to right across the network grid, while dotted dependencies (..>) accurately represent decoupled, asynchronous communications.