Skip to main content

Drawing like an architect for people who don`t draw and who are not architects

Want to learn how to create nice clean diagrams without dragging boxes all over the screen? Ever wanted to write something like: 
Client -> Server: Authentication Request
And get:

Keep reading and your dreams will come true!

PlantUML

First, install plantUml with choco: 
choco install plantuml
Next thing, we need an editor, VS Code plugin is quite good:
ext install plantuml
And you are ready!
The mark up from above is rendered by PlantUml engine: https://plantuml.com/
What can it do?
We`ve already seen sequence diagrams: 
@startuml
 Alice -> Bob: Authentication Request
 Bob --> Alice: Authentication Response
@enduml
But, basically, it can do any.

Swimlanes? Sure! 
@startuml
|Swimlane1|
   start
   :foo1;
|#AntiqueWhite|Swimlane2|
   :foo2;
   :foo3;
|Swimlane1|
   :foo4;
|Swimlane2|
   :foo5;
   stop
@enduml



 Tired of linking boxes for some hierarchy? Lets fix it 
@startmindmap
* Debian
** Ubuntu
*** Linux Mint
*** Kubuntu
*** Lubuntu
*** KDE Neon
** LMDE
** SolydXK
** SteamOS
** Raspbian with a very long name
@endmindmap



Rendering and exporting each diagram can be a bit annoying.
The good thing is, plantUML is nothing but a jar file, so you can use it in your proj build to generate images for all diagrams, just add: 
 java -jar "plantuml.jar" "folder"

C4

But that's not all.
Ask yourself, do you actually remember the uml convention?
Does your client know UML?
How do you define how deep in detail your diagram should go?
Are you following UML when you are explaining something to your colleague and drawing it on a piece of paper?
Can the process of visualizing architecture be as simple as a drawing on a napkin but look professional?

Some people tried to answer those questions and created a c4 model for software architecture https://c4model.com/

In short, we have 3 types of diagrams (well 4 but no one uses code one)
1) High-level overview: Context diagram - to show how other systems or people interact with yours
2) Container diagram - your apps and services (zoom in from context)
3) Component diagram - contents of your app(s)
(Read a page, that 5 minutes will change your life and make you an architect)

Now, how do we combine c4 and planutUml?
Easy - we need c4-plantUML!
https://github.com/RicardoNiepel/C4-PlantUML 
@startuml
    !includeurl https://raw.githubusercontent.com/RicardoNiepel/C4-PlantUML/release/1-0/C4_Container.puml
    System(systemAlias, "System", "System Description")
    Container(containerAlias, "Container", "Technology", "Optional Description")
    Rel(systemAlias, containerAlias, "Action", "Optional Technology")
@enduml


Congratulations! you are an architect!
Oh, wait - add snippets to VS Code:
https://github.com/RicardoNiepel/C4-PlantUML/blob/master/.vscode/C4.code-snippets

Ok, now you are! Enjoy it :)
Labels:

Comments

Post a Comment

Popular posts from this blog

Avoiding distributed transactions (DTC) with SQL Server and async code

Wrapping async code in transaction scope is not as straightforward as sync one. Let's say we have some simple code: await using (var connection = new SqlConnection(connectionString)) { await using var command = new SqlCommand("select 1", connection); await connection.OpenAsync(); await command.ExecuteScalarAsync(); } We can wrap it in transaction scope and test that it still works: using var ts = new TransactionScope(); await using (var connection = new SqlConnection(connectionString)) { await using var command = new SqlCommand("select 1", connection); await connection.OpenAsync(); await command.ExecuteScalarAsync(); } ts.Complete(); But if you try to run this code you will get: "A TransactionScope must be disposed on the same thread that it was created" exception.  The fix is easy: we need to add TransactionScopeAsyncFlowOption.Enabled option to the constructor: var options = new TransactionOptions { IsolationLevel = IsolationLevel.ReadCom...
Post a Comment
Read more

Using MinIO as on premises object storage with .NET and S3 SDK

Ever tried to find a blob store that can work on-premises as well as in a cloud, support meta-data, scale well and have .NET client libraries? I did and stopped on MinIO . Well, honestly to my surprise I was quite limited in my choice. It's free, it's open-source, it can work on-premises and has helm charts for k8s. The best thing is that its S3 compatible, so if one day you move to the cloud the only thing you`ll need to change in your code is a connection string. The easiest way to start is by starting a docker image. Pull the image: docker pull minio/minio start for testing (data will be part of the container, so after a restart, all files will be gone docker run -p 9000:9000 minio/minio server /data Or start with a mapped image in windows: docker run -p 9000:9000 --name minio1 \ -v C:\data:/data \ minio/minio server /data When the server is up you can access it by http://127.0.0.1:9000/minio/login default user/password: minioadmin/minioadmin Working wi...
Post a Comment
Read more

Accessing VM Host (localhost) from minikube

Time to time I need to access resources outside of your Kubernetes cluster. It can be some .net framework app that I can`t put in linux container or shared db, like SQL server. We can easily access resources in kube via kubefwd or ingress\exposed port. However, that doesn't work backwards. Services in k8s cluster can`t just access your machine, they need to know VM`s host IP. The main point here is finding an ip of the host machine: $ route -n | grep ^0.0.0.0 | awk "{ print \$2 }" 172.17.8.1 In order to run in from powershell we need to escape quotes: minikube ssh 'route -n | grep ^0.0.0.0 | awk \"{ print \$2 }\"' 172.17.8.1 What can it be use it for? I can setup that ip in PODS connection string but I don’t want to update every pod when my ip changes (a typical problem with hyberV). It would be much better to reference resources by dns name and let dns service decide how to resolve that resource. So let’s make a ‘dns-service’ that wil...
Post a Comment
Read more