PlantUML UML guide

Start with the PlantUML document wrapper

PlantUML diagrams begin with @startuml and end with @enduml. Everything between those lines describes the diagram. This wrapper makes the source portable across tools and easy to store in markdown, tickets, architecture docs, or repositories.

Markdownyi lets you write and preview PlantUML source in the UML editor. You can also keep PlantUML blocks inside markdown when you want prose and diagrams to export together.

Sequence diagrams for behaviour

Use sequence diagrams when you need to show messages between users, services, APIs, queues, or databases. Define participants, then use arrows to show calls, responses, retries, and error paths.

Good sequence diagrams are narrow and chronological. If the flow has too many branches, create one diagram for the happy path and a separate diagram for failures or edge cases.

• Use actor for users or external systems
• Use participant for services and applications
• Use arrows to show request and response direction
• Add notes for auth, validation, or important side effects

Class and component diagrams for structure

Class diagrams describe domain models, interfaces, relationships, and inheritance. Component diagrams describe higher-level building blocks such as apps, services, databases, queues, and third-party systems.

For documentation, do not try to model every field or method. Focus on the relationships that help a reviewer understand the system. Detailed implementation belongs in code, while diagrams should explain structure and boundaries.

Preview, export, and embed

Use the Markdownyi UML editor to preview PlantUML quickly, zoom into the result, and export SVG, PNG, or PDF. For architecture specs, you can also embed PlantUML source in markdown and export the full document to Word.

Choose SVG for crisp diagrams in docs and slides, PNG for broad compatibility, PDF for formal attachments, and Word export when the diagram belongs inside a larger written spec.