May 18, 2024

Documentation performs a vital position in any undertaking, serving as a compass for improvement groups, and as a great way for the brand new joiners to know the way the undertaking is finished. Most of the time, documentation turns into a process 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 software seamlessly built-in into their IDE. This eliminates friction brought on by the necessity to swap between completely different instruments, guaranteeing comfort, ease of use, and the flexibility to effortlessly replace documentation. A superb method to method it’s with C4 PlantUML — a robust software that enables builders to generate complete system structure documentation with just some traces 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 (degree 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 an alternative, they provide a high-level overview, articulating the essence of the system and elucidating its goal. Throughout the context diagrams, emphasis is positioned on elucidating the roles and interactions amongst completely different programs.

In essence:

Container diagrams (degree 2)

  • Decompose the system into interconnected containers, comparable to purposes and databases. 
  • Spotlight the general structure’s form and the know-how selections employed. 
  • Emphasize deployable models and illustrate interactions by way of connecting traces.

Part diagrams (degree 3)

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

Code diagrams (degree 4)

  • Represented, as an illustration, 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 software launched by Arnaud Roques in 2009, a flexible resolution enabling customers to generate diagrams utilizing a easy plain textual content language. It supplies a user-friendly and environment friendly method to visually characterize advanced programs and processes by way of quite a lot of diagram sorts. Its simplicity and adaptability make it a beneficial software for builders and system architects, facilitating the creation of assorted diagram sorts with ease and effectivity.

PlantUML helps the creation of various 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 circumstances.

Class Diagrams

Reveal the relationships and construction of courses in a system.

@startuml


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


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


@enduml

categories

Exercise Diagrams

Symbolize 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 --> Accepted: Approve
 Pending --> Rejected: Reject
 Accepted --> Pending: Replace

@enduml

create

Deployment Diagrams

Illustrate the distribution of elements throughout completely different nodes.

Timing Diagrams

Visualize the timing elements of interactions in a system.

Community Diagrams

Show the relationships and connections in a community.

Wireframe Diagrams

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

Archimate Diagrams

Comply with the ArchiMate modeling language for enterprise structure.

Gantt Charts

Symbolize undertaking schedules and timelines.

Thoughts Maps

Visualize hierarchical data or concepts.

WBS (Work Breakdown Construction) Diagrams

Decompose a undertaking into smaller, manageable elements.

JSON and YAML Diagrams

Visualize knowledge 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 provides 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 Particular person, Person_Ext, System, System_Ext, Container, Relationship, Boundary, and System_Boundary. These macros streamline the creation of C4 mannequin parts in PlantUML syntax.

Customization With Icons

The software permits customization with varied icons, enhancing visible illustration. Icon libraries comparable to 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 common 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 (degree 2), explaining the principle interplay. The code:

@startuml
!embrace 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
!embrace DEVICONS/angular.puml
!embrace DEVICONS/java.puml
!embrace DEVICONS/msql_server.puml
!embrace FONTAWESOME/customers.puml


LAYOUT_WITH_LEGEND()




Particular person(consumer, "Buyer", "Those that want merchandise", $sprite="customers")
Container(spa, "SPA", "angular", "The primary interface that the client 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(consumer, 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 software 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 class of the C4 mannequin, this integration supplies a handy and environment friendly means of making visible representations of advanced programs.

What units C4 PlantUML aside is its user-friendly nature, permitting for the simple 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 common 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 dwelling artifacts. Because the software program improvement panorama continues to evolve, having a software that adapts with agility turns into paramount. C4 PlantUML stands on the intersection of simplicity and effectiveness, embodying a brand new normal for software program structure visualization. Embrace the facility of C4 PlantUML to articulate, iterate, and talk your architectural imaginative and prescient with finesse.