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

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

Fluent-Bit and Kibana in Kubernetes cluster or minikube

Agenda I`ll show how to setup a centralized logging solution running in k8s cluster that works beyond hello world examples.I`ll use local minikube but the same charts with adjustments could be used for normal k8s cluster (the real diff usually comes with usage of persistent storage). What you need to be installed: K8s Cluster (as I said, I use minikube ) Helm ( https://helm.sh/docs/intro/install/ ) Code: https://github.com/Vfialkin/vf-observability A bit of theory first: Let’s start with how logging works by default in Docker and Kubernetes. application log appender should forward logs to standard output, this way it will be passed to Docker container.  default container logging driver will forward them to Pod where logs are stored as JSON files (see: configure logging drivers ). There are other options for log drivers like  syslog, fluentd or splunk , but for now, I’ll limit scenario to default driver. at the end all those files will end-up in a node folde...
Post a Comment
Read more