Skip to main content
Reference

C4 Model

⏱ 3 min readEdit on GitHub ↗

CALM tools can show an architecture as a C4 model: system context, container, component and deployment diagrams. The CALM C4 standard sets how CALM nodes become C4 elements. You do not change your architecture to get a C4 view.

The standard has two parts:

  • A C4 mapping: a JSON document that gives the C4 kind of each node type. CALM publishes a default mapping. Your organisation can write its own mapping. The tools accept mappings for version 1.0 and 1.1 of the standard. The two versions have the same schema and the same default mapping.
  • Rules for the node types that the mapping does not name, and for external elements.

The default mapping​

CALM node-typeC4 kind
actorperson
systemsoftware-system
service, database, webclient, data-asset, ldapcontainer
ecosystementerprise-boundary
networkdeployment-node

A custom mapping​

A custom mapping gives the C4 kind of your own node types. Use extends to start from the default mapping:

{
"$schema": "https://calm.finos.org/standards/c4/1.1/c4-mapping.json",
"unique-id": "acme-c4-mapping",
"extends": "https://calm.finos.org/standards/c4/1.1/calm-default.c4-mapping.json",
"node-types": {
"aws:lambda": "container",
"acme:module": "component",
"acme:vendor-platform": { "kind": "software-system", "external": true },
"k8s:cluster": "deployment-node"
},
"nesting": "demote"
}
  • Kinds: person, software-system, container, component, deployment-node, enterprise-boundary and hidden. Tools do not show a hidden node, and its composed-of children take its place. Tools do not draw its connects and interacts relationships, and report each one as a conflict.
  • extends: the entries of the mapping replace the entries of the mapping that it extends, for each node type. A mapping with no extends replaces the default mapping. When a mapping that extends names does not load, the tool stops with an error. It does not use the default mapping instead.
  • external: every node of the type is outside the enterprise. Use it only with the kinds person, software-system, container and component.
  • nesting: what to do with a node at the wrong depth, such as a container inside a container. demote shows it one level below its parent. Below a component, it is a component, and the tool reports a conflict. strict keeps the mapped kind and reports a conflict. A mapping that does not set nesting uses the nesting of the mapping that it extends. When no mapping in the chain sets it, it is demote.

How CALM finds the C4 model​

Only composed-of sets the C4 hierarchy. When the mapping does not name a node type, the structure sets the kind:

  1. A top-level node with composed-of children, or a top-level node with no children, is a software system.
  2. A child of a software system is a container. A child of a container is a component. A child of a component is a component, and the tool reports a conflict.
  3. deployed-in sets the deployment diagram only.
  4. details.detailed-architecture holds the next level down, in a different document.
  5. Containers that no software system holds belong to one implicit software system, named after the architecture.

An enterprise boundary, a deployment node, a hidden node or a person does not count as a parent: the tool uses the nearest ancestor of another kind. A node inside a person is a conflict.

Tools mark an element whose kind comes from the structure as guessed. Add its node type to your mapping to fix the kind.

A node is external when one of these rules applies:

RuleWhen
E1It is a software system other than the system in scope
E2The architecture has an enterprise-boundary node, and the node is not inside it
E3Its detailed architecture is in a CALM Hub namespace that is not the namespace of this architecture, or below it
E4The mapping marks its node type external. With no enterprise-boundary node, tools show it in grey with no enterprise boundary

The projection also reports conflicts. For example, a person inside a system, or a component with no container above it.

Which mapping a tool uses​

ToolMapping
CALM Hub, with the C4 extensionThe c4-mapping default convention of the namespace, or of its nearest parent namespace. Else the default mapping. When the namespace mapping does not load, the C4 lens shows the error and no diagram
calm docify--c4-mapping, else c4.mapping in the workspace config, else the CALM Hub namespace default when the architecture comes from CALM Hub. Else the default mapping

The c4-diagram widget draws C4 diagrams in docify templates, with a table of the conflicts under each diagram. It does not apply rule E3, because docify replaces each detailed-architecture link with the document that it loads. TypeScript tools can use projectC4 from @finos/calm-models/c4.