May 20, 2024

Documentation performs a vital position in any mission, serving as a compass for improvement groups, and as a great way for the brand new joiners to understand how the mission is completed. Most of the time, documentation turns into a activity that’s both indefinitely postponed or accomplished as soon as and by no means up to date, leaving it outdated and doubtlessly counterproductive.

An efficient technique for builders is to leverage a instrument seamlessly built-in into their IDE. This eliminates friction attributable to the necessity to swap between completely different instruments, making certain comfort, ease of use, and the flexibility to effortlessly replace documentation. A superb option to method it’s with C4 PlantUML — a robust instrument that permits builders to generate complete system structure documentation with only a few strains of code, making the documentation course of not solely environment friendly but in addition an integral a part of the event workflow.

What Is C4 PlantUML?

It’s a fusion of two highly effective ideas—the C4 Mannequin and PlantUML.

Let’s see what every idea is about:

Context diagrams (stage 1)

Stage 1 context diagrams are designed to supply a conceptual understanding of the system’s scope and the roles that work together inside its ecosystem. These diagrams encapsulate the “large image” of the system with out delving into technical intricacies. As a substitute, they provide a high-level overview, articulating the essence of the system and elucidating its function. Inside the context diagrams, emphasis is positioned on elucidating the roles and interactions amongst completely different techniques.

In essence:

Container diagrams (stage 2)

  • Decompose the system into interconnected containers, reminiscent of functions and databases. 
  • Spotlight the general structure’s form and the expertise selections employed. 
  • Emphasize deployable items and illustrate interactions by way of connecting strains.

Part diagrams (stage 3)

  • Additional break down containers into interrelated elements.
  • Set up relationships between elements, in addition to their connections to different containers or exterior techniques.
  • Deal with logical elements and their interactions inside a selected container, working on the code architectural stage.

Code diagrams (stage 4)

  • Represented, as an example, as UML diagrams.
  • Element part implementation specifics.
  • Recognizing the dynamic nature of code, these diagrams shouldn’t be overly detailed, acknowledging that frequent updates could render detailed documentation shortly out of date.

PlantUML

PlantUML is an open-source instrument launched by Arnaud Roques in 2009, a flexible answer enabling customers to generate diagrams utilizing a easy plain textual content language. It gives a user-friendly and environment friendly option to visually signify complicated techniques and processes by way of a wide range of diagram varieties. Its simplicity and suppleness make it a worthwhile instrument for builders and system architects, facilitating the creation of varied diagram varieties with ease and effectivity.

PlantUML helps the creation of numerous diagrams:

Sequence Diagrams

Illustrate the interactions between completely different elements or objects over time.

@startuml
actor Creator
participant Vendor
actor Approver


   Creator -> Vendor: Create Vendor
   word proper: standing:Pending
   Vendor --> Approver: Ship notification
@enduml

create vendor

Use Case Diagrams

Depict the interactions between customers and a system, showcasing varied use instances.

Class Diagrams

Reveal the relationships and construction of lessons in a system.

@startuml


Vendor "1" *-> "*" Materials : incorporates not less than 1
Materials "*"  *--> "1" CategoryLevel3
CategoryLevel3 "*"  *--> "1" CategoryLevel2
CategoryLevel2 "*"  *--> "1" CategoryLevel1


Vendor  "*"  *--> "1" CategoryLevel1 : Solely One L1


@enduml

categories

Exercise Diagrams

Signify workflows, processes, or actions inside a system.

Part Diagrams

Show the elements and their interactions in a system.

State Diagrams

Mannequin the states and transitions of an object or system.

@startuml
[*] --> Vendor: Create


state Vendor 
 [*] --> Pending: is created with standing
 Pending: An approver must approve it
 Pending --> Accredited: Approve
 Pending --> Rejected: Reject
 Accredited --> Pending: Replace

@enduml

create

Deployment Diagrams

Illustrate the distribution of elements throughout completely different nodes.

Timing Diagrams

Visualize the timing features of interactions in a system.

Community Diagrams

Show the relationships and connections in a community.

Wireframe Diagrams

Present a skeletal view of the person interface or a system.

Archimate Diagrams

Observe the ArchiMate modeling language for enterprise structure.

Gantt Charts

Signify mission schedules and timelines.

Thoughts Maps

Visualize hierarchical data or concepts.

WBS (Work Breakdown Construction) Diagrams

Decompose a mission into smaller, manageable elements.

JSON and YAML Diagrams

Visualize information constructions utilizing JSON or YAML notation.

C4 PlantUML

C4 PlantUML seamlessly merges the strengths of PlantUML and the C4 mannequin, offering a simple methodology for describing and speaking software program architectures. This integration gives a handy and environment friendly method to creating and sustaining up-to-date system structure diagrams.

Key Options

Outlined Macros

C4 PlantUML introduces particular macros, together with Individual, Person_Ext, System, System_Ext, Container, Relationship, Boundary, and System_Boundary. These macros streamline the creation of C4 mannequin components in PlantUML syntax.

Customization With Icons

The instrument permits customization with varied icons, enhancing visible illustration. Icon libraries reminiscent of plantuml-icon-font-sprites supply a broad choice to tailor diagrams to particular wants.

Infrastructure diagrams could be enriched with cloud icons utilizing sprite libraries like Azure-PlantUML, AWS Icons, and GCP-C4 PlantUML. 

Google Cloud Platform Icons

google cloud platform icons

IDE Integration

C4 PlantUML is supported by integration plugins for well-liked Built-in Improvement Environments (IDEs) like IntelliJ and Visible Studio, enabling a easy workflow for builders.

Plugin hyperlinks:

To make use of these plugins graphviz library must be put in:

Let’s see right here an instance,  a container diagram (stage 2), explaining the principle interplay. The code:

@startuml
!embody https://uncooked.githubusercontent.com/plantuml-stdlib/C4-PlantUML/grasp/C4_Container.puml


!outline DEVICONS https://uncooked.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/grasp/devicons
!outline FONTAWESOME https://uncooked.githubusercontent.com/tupadr3/plantuml-icon-font-sprites/grasp/font-awesome-5
!embody DEVICONS/angular.puml
!embody DEVICONS/java.puml
!embody DEVICONS/msql_server.puml
!embody FONTAWESOME/customers.puml


LAYOUT_WITH_LEGEND()




Individual(person, "Buyer", "Those who want merchandise", $sprite="customers")
Container(spa, "SPA", "angular", "The principle interface that the shopper interacts with", $sprite="angular")
Container(api, "API", "java", "Handles all enterprise logic", $sprite="java")
ContainerDb(db, "Database", "Microsoft SQL", "Holds product, order and bill data", $sprite="msql_server")


Rel(person, spa, "Makes use of", "https")
Rel(spa, api, "Makes use of", "https")
Rel_R(api, db, "Reads/Writes")
@enduml

The resultant picture:


customer

Conclusion

In conclusion, C4 PlantUML emerges as a flexible and invaluable instrument for builders in search of a seamless method to crafting and managing software program structure diagrams. By marrying the expressive energy of PlantUML with the structured magnificence of the C4 mannequin, this integration gives a handy and environment friendly means of making visible representations of complicated techniques.

What units C4 PlantUML aside is its user-friendly nature, permitting for the straightforward technology of diagrams that may be effortlessly manipulated and up to date. With a palette of outlined macros, customization choices with icons, and integration plugins for well-liked IDEs, it empowers builders to streamline the documentation course of. 

In essence, C4 PlantUML not solely simplifies the creation of architectural diagrams but in addition transforms them into dynamic and residing artifacts. Because the software program improvement panorama continues to evolve, having a instrument that adapts with agility turns into paramount. C4 PlantUML stands on the intersection of simplicity and effectiveness, embodying a brand new commonplace for software program structure visualization. Embrace the facility of C4 PlantUML to articulate, iterate, and talk your architectural imaginative and prescient with finesse.