C4 Model

About

A simple and clear model for documenting/visualizing Software Architecture.

It has 4 levels of detailed diagrams.

Levels

Context (Software System)

It is the highest level of abstraction and describes something that delivers value to its users.

This includes the software system being modelled, and any other depended softwares.

What is not Software Systems:

• Product domains.

• Bounded contexts.

• Business capabilities.

• Feature teams, tribes or squads.

Diagram exemple.

Container

Represents an application or data store. (It is a Deployable Unit)

A container is something that needs to be running in order for overall software systems to work.

• Server-side web applications: A container could be a Node.js application, a Ruby on Rails application, etc.

• Client-side applications: A container could be an Angular or React SPA or SSR.

• Serverless functions: A container could be a single serverless function (Ex.: Lambda, Azure Function, etc).

• Database: A container could be a relational database, noSQL or Amazon RDS.

• File systems: A container could be full local file system or portion or a larger networked fs (Ex.: SAN, NAS, etc).

• Shell scripts: Could be a single shell script in Bash.

Diagram example.

Component

It is a grouping of related functionalities encapsulated behind a well defined interface.

All the Components inside a container execute in the same process space.

• OOP languages: A component is made up of classes and interfaces.

• Procedural programming languages: A component could be made up of a number of files in a particular directory.

• JS: A component could be a JS module.

Diagram example.

Code

These are one or more elements constructed with the basic building blocks of the used programming language, (like class, interface, enums, function, object, etc).

Diagram example.

PlantUML

It is a library to create C4 Model diagrams through code.

A VSCode plugin named PlantUML is also available to run PlantUML.

Requires Java and Graphviz.

Creating a Context

context.puml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

title "Digital Wallet Context"
Person(client, "Client", "Wallet User")

System(wallet, "Digital Wallet System", "Digital Wallet")

System_Ext(apm, "APM", "Application Performance Monitoring")
System_Ext(payment_gateway, "Payment Gateway", "Payment Processor")

Rel(client, wallet, "Uses", "HTTPS")
Rel(wallet, apm, "Uses", "HTTPS")
Rel(wallet, payment_gateway, "Uses", "HTTPS")

@enduml

Then execute in VSCode this command PlantUML: Preview Current Diagram.

Creating Containers

context.puml

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
' Define a tag "async" to make dashed Rel lines
AddRelTag("async", $lineStyle = DashedLine())

title "Digital Wallet Containers"
Person(client, "Client", "Wallet User")

System_Ext(payment_gateway, "Payment Gateway", "Payment Processor")

System_Boundary(digital_wallet, "Digital Wallet") {
    Container(spa, "SPA", "React", "Digital Wallet Web App")
    Container(wallet_core, "Wallet Core", "Typescript", "Wallet Core is responsible for the transactions")
    Container(balance_service, "Balance Microservice", "Typescript", "Returns customer balance")
    Container(statement_service, "Statement Microservice", "Typescript", "Returns customer statement")
    Container(payment_acl, "Payment ACL", "Typescript", "Anti-corruption layer for Payment Gateways")

    ContainerDb(wallet_core_db, "Wallet DB", "MySQL")
    Rel(wallet_core, wallet_core_db, "Uses", "MySQL Driver")
    
    ContainerDb(balance_db, "Balance DB", "MySQL")
    Rel(balance_service, balance_db, "Uses", "MySQL Driver")
    
    ContainerDb(statement_db, "Statement DB", "MySQL")
    Rel(statement_service, statement_db, "Uses", "MySQL Driver")
    
    ContainerDb(payment_acl_db, "Payment ACL DB", "MySQL")
    Rel(payment_acl, payment_acl_db, "Uses", "MySQL Driver")
    
    Rel(client, spa, "Uses", "HTTPS")
    Rel(spa, wallet_core, "Uses", "Json/HTTPS")
    Rel(spa, balance_service, "Uses", "Json/HTTPS")
    Rel(spa, statement_service, "Uses", "Json/HTTPS")
    
    Rel(wallet_core, payment_acl, "Uses", "Json/HTTPS")
    Rel(payment_acl, payment_gateway, "Uses", "Json/HTTPS")
    
    ' wallet_core will produce events that will be consumed by balance & statement
    Rel(wallet_core, balance_service, "Uses", "Topic", $tags = "async")
    Rel(wallet_core, statement_service, "Uses", "Topic", $tags = "async")
}

@enduml