C4 Model Overview - Archyl Docs

Learn about the C4 model and how Archyl implements it for architecture documentation

C4 Model Overview

The C4 model is a lean graphical notation technique for modeling the architecture of software systems. Created by Simon Brown, it provides a way to communicate software architecture at different levels of abstraction.

Why C4?

Traditional architecture diagrams often suffer from:

  • Inconsistent notation: Different teams use different symbols
  • Wrong level of detail: Either too abstract or too detailed
  • Outdated documentation: Diagrams don't reflect reality

The C4 model addresses these issues by providing:

  • Standardized abstraction levels: Four clear levels from high to low
  • Simple notation: Easy to understand for technical and non-technical audiences
  • Hierarchical navigation: Zoom in for more detail, zoom out for context

The Four Levels

Level 1: System Context

The System Context diagram shows your system as a box in the center, surrounded by its users and the other systems it interacts with.

Purpose: Show the big picture - how your system fits into the world

Audience: Everyone (technical and non-technical)

Contains:

  • Your software system (central)
  • Users/personas who use the system
  • External systems your system depends on

Level 2: Container

The Container diagram zooms into your system to show the high-level technical building blocks.

Purpose: Show the major technology choices and how responsibilities are distributed

Audience: Technical people inside and outside of the development team

Contains:

  • Containers (applications, data stores, etc.)
  • Relationships between containers
  • Connections to external systems

Level 3: Component

The Component diagram zooms into a container to show its internal components.

Purpose: Show how a container is made up of components and their responsibilities

Audience: Software architects and developers

Contains:

  • Components within a container
  • Relationships between components
  • Technology/implementation choices

Level 4: Code

The Code diagram (optional) shows how a component is implemented.

Purpose: Show code-level details for complex or critical components

Audience: Developers

Contains:

  • Classes, interfaces, functions
  • Inheritance and implementation relationships
  • Design patterns

C4 in Archyl

Archyl implements the C4 model with these features:

Navigation

  • Double-click on any element to zoom into the next level
  • Use breadcrumbs to navigate back up
  • Keyboard shortcuts for quick navigation (← → ↑ ↓)

Element Types

Each level has its own element types:

Level Element Types
System Context System, External System, Person
Container Container, External Container
Component Component
Code Class, Interface, Function

Relationships

Relationships can be created between elements at any level:

  • Drag from one element to another
  • Add labels describing the interaction
  • Specify the technology used

Styling

Customize the appearance of your diagrams:

  • Colors for different element types
  • Custom icons
  • Grouping with overlays

Best Practices

Start at the Top

Always start with the System Context diagram. It forces you to think about:

  • Who uses your system?
  • What external systems do you depend on?
  • What is the scope of your system?

Keep It Simple

Each diagram should fit on a single page/screen. If it doesn't:

  • Split into multiple diagrams
  • Reduce the level of detail
  • Use the next level down for more detail

Use Consistent Naming

  • Use clear, descriptive names
  • Follow your team's naming conventions
  • Avoid abbreviations that aren't universally understood

Document Relationships

Relationships are as important as elements:

  • Always add labels describing the interaction
  • Include the technology/protocol when relevant
  • Show the direction of communication

Next Steps