Skip to main content

Overview

Let's start with having a look on the project's structure and the UI elements used to represent the different components of a System Architecture Design project.

After creation, you will be directed to the project's Overview page (see setting up projects). On the left there is the main navigation bar offering the following entries:

Starting page​

The overview page is the starting point from which you can start designing your system architecture.

Here you can find information about the project's "Acronym", "Git Provider", "Repository group", "Git repository group", "Git repository key", "Stack", and "Stack version". Besides, it shows additional information on "Tags" and the "Icon", the project's "Description" and the name of the creator ("Created by") and the creation date ("Created on").

The documentation section on a project's overview page is intended to provide an overall documentation of the project and all of its components.

Introduction to C4 modeling​

The C4 model is a framework for visualizing the architecture of software systems. It provides a set of diagrams to represent different levels of a software system's architecture, helping teams communicate structure and design effectively. This manual will guide you through the steps to create C4 models, covering each level of the model.

Overview of the C4 Model Levels​

The C4 model is composed of four levels of diagrams:

  • Context Diagram (Level 1)
  • Container Diagram (Level 2)
  • Component Diagram (Level 3)
  • Code (Class) Diagram (Level 4)

Each level provides a different perspective on the system, from a high-level overview to detailed code structure.

Step-by-Step Guide to Creating C4 Models​

Level 1: Context Diagram​

The Context Diagram provides a high-level view of the system and its interactions with external entities (e.g., users, other systems).

Steps to Create:

  • Identify the system boundaries: Define the system you are modeling. This is your central box, typically labeled as "System Name."
  • Identify external entities: List all external entities that interact with your system. These can be users, external systems, or third-party services.
  • Define relationships: Draw arrows to represent the relationships between your system and external entities. Label the arrows to indicate the type of interaction or data flow.
  • Add descriptions: Briefly describe the purpose of each external entity and the nature of its interaction with your system.

Example:

+-----------------------------------+
|      <Actor> External User        |
+-----------------------------------+
               |
               | Uses
               v
+-----------------------------------+
|           Your System             |
|  - Core functionality overview    |
+-----------------------------------+
               |
               | Sends data to
               v
+-----------------------------------+
|       External System             |
+-----------------------------------+

Level 2: Container Diagram​

The Container Diagram breaks down the system into its main containers, such as web applications, databases, or microservices.

Steps to Create:

  • Identify containers: Determine the main components of your system. These can include web applications, mobile apps, databases, microservices, etc.
  • Show relationships: Draw arrows between containers to represent data flows and interactions. Label these arrows with the data or services exchanged.
  • Add descriptions: Include brief descriptions of each container, focusing on its role and responsibilities.

Example:

+-----------------------------------+
|           Web Application         |
|  - Handles user interaction       |
+-----------------------------------+
               |
               | API Calls
               v
+-----------------------------------+    +-----------------------------------+
|        Backend Service 1          |<-->|        Backend Service 2          |
|  - Business logic processing      |    |  - Data processing                |
+-----------------------------------+    +-----------------------------------+
               |
               | DB Queries
               v
+-----------------------------------+
|             Database              |
|  - Stores user data               |
+-----------------------------------+

Level 3: Component Diagram​

The Component Diagram zooms in on a single container, breaking it down into components, each representing a cohesive part of the containers functionality.

Steps to Create:

  • Select a container: Choose one container from the previous level (Container Diagram) to focus on.
  • Identify components: Break down the container into smaller components. Each component should represent a specific responsibility or functionality.
  • Show interactions: Draw arrows to represent the interaction between components. Include details on the data exchanged or methods invoked.
  • Add descriptions: Briefly describe each component, focusing on its role within the container.

Example:

+-----------------------------------+
|         Web Application           |
|  - Handles user interaction       |
+-----------------------------------+
               |
               v
    +------------------------+       +-------------------------+
    |   Authentication        |<---->|     User Profile         |
    |   Component             |       |     Component            |
    +------------------------+       +-------------------------+
               |
               v
    +------------------------+
    |   Logging Component     |
    |   (Logs user actions)   |
    +------------------------+

Level 4: Code (Class) Diagram​

The Code Diagram (or Class Diagram) represents the implementation details of the components, showing classes, methods, properties, and relationships.

ℹ️note

Code Diagrams are supposed to be created and stored within the implementation projects directly. You can leverage plantuml embedded in any markdown documentation field.

Best Practices​

  • Keep it simple: Start with high-level overviews and gradually add details. Avoid overcomplicating diagrams.
  • Use consistent notation: Ensure all diagrams use consistent symbols, labels, and formatting for clarity.
  • Regularly update diagrams: As the system evolves, update diagrams to reflect current architecture accurately.
  • Document assumptions: Document any assumptions made during the modeling process, especially for components not yet implemented.
  • Incorporate feedback: Regularly review diagrams with the team and stakeholders to ensure accuracy and relevance.