Core Concepts

C* model

Rougly based on the C4 model, the C4 model works great if you can immediately recognize and label your objects and know what to build before-hand. But real architecture work is messy. You often start with a vague idea. You know you have services and databases, but you don’t know how they all fit together yet. You might have to move and merge them, add more detail or remove some.

tlDiagram is opinionated with attempts to simplify this process. It is C* because it allows more than 4 levels of hierarchy, however you picture your system.

The Data Model

Elements are the objects or nodes in graph terms. Services. Databases. Queues. People. External systems. Each element can have a unique view(a diagram). This is where you put the internal structure of that element. A service might have a diagram showing its internal modules and dependencies. A database might have a diagram showing its tables and relationships.

Elements can be placed in multiple views. A database might appear in both the root view and a specific service’s child view.

Connectors are the relationships or edges in graph terms. They connect two elements with a direction (forward, backward, bidirectional, or none), a label, and a style. Connectors don’t have to belong to a specific view. If two elements are connected you can see the external element visually in the view of the internal element.

Views Views are the diagrams. They contain elements and connectors. Each element can have its own view, but elements can also appear in multiple views. Connectors are placed in views based on the elements they connect.

The root view

Every workspace has a synthetic root. It’s the top-level container. Everything lives inside it.

The root view is where you put your system context. External users. Your system boundary. Maybe a few key external dependencies. It’s the 50,000-foot view.

From root, you drill down into subsystems. Each subsystem reveals its own internal architecture. Each layer adds detail.