Overview
Navigation menu structure
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.
Custom form fields
On this page, you can also define and manage your own fields for model elements, diagrams and decisions within your System Architecture Design project. This provides flexibility to tailor data entry to your specific needs, ensuring that all relevant information can be captured efficiently.
You can find the option to Configure custom fields in the overflow menu in the top right corner of the starting page.
Custom fields are defined and saved within a .yaml file for the entire project. Within this file, you can define the following:
- Field name: An identifier for the field
- Display name: The display label of the field in the form
- Type:
textField(small text field),textArea(large text field),multiSelect(dropdown),singleSelect(dropdown),checkbox,rating,number,date - Description: Text that will be displayed below the field (optional)
- Help URL: URL that will be accessible via an info icon next to the label (optional)
- Availability: The form where this field will be displayed. Custom fields can be created for Decisions (
architecturalDecision), Diagrams (diagram), Actors (actor), Systems (system), Containers (container), Components (component), and Relationships (relationship). - Selection options for multiSelect and singleSelect fields: Name (label), icon and color code for the dropdown entries (optional)
Example for the .yaml file:
- fieldName: author
type: textField
availability:
- architecturalDecision
displayName: Author
description: The author of this description
helpUrl: https://help.url
- fieldName: reach
type: singleSelect
availability:
- architecturalDecision
displayName: Reach
description: The reach of this decision
options:
- name: System
- name: Project
- name: Company
- fieldName: technicalFit
type: rating
availability:
- system
- container
displayName: Technical Fit
description: >-
The rating whether this item is fit for the future from a technical
perspective
- fieldName: businessFit
type: rating
availability:
- system
- container
displayName: Business Fit
description: >-
The rating whether this item is fit for the future from a business
perspective
- fieldName: modernization
type: multiSelect
availability:
- system
- container
displayName: Modernization Phase
description: In which phases is this item tackled
options:
- name: Horizon 1
- name: Horizon 2
- name: Horizon 3`
- fieldName: estimatedCost
type: number
availability:
- system
- container
displayName: Estimated Cost
description: >-
The number estimating the overall cost for the project
- fieldName: nextEvaluationDate
type: date
availability:
- system
- container
displayName: Next Evaluation Date
description: >-
The date to determine when is the next phase of evaluation
Defined fields will be displayed in the order that is given within the .yaml file, directly after non-custom fields of the form that has been specified (decisions, diagrams, or a model element type), as well as in creation dialogs of said elements. In tables, the fields are available as optional columns that can be displayed by adjusting the table settings in the table tool bar.
Custom fields are always optional fields by definition.
Changes to the form fields defined in the .yaml file after their initial setup may lead to inconsistencies, data loss, or unexpected behaviour in existing views. To ensure stability, configure these fields only once and avoid modifications unless absolutely necessary.
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.
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.