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

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

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

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