Skip to content
SayDiagramSayDiagram

Learn

C4 diagram syntax

Learn C4Context persons, systems, external systems, and relationships used in the Notes app context template.

On this page7 sections
  1. Syntax cheatsheet
  2. 1.Start a C4 context diagram
  3. 2.People and systems
  4. 3.Relationships
  5. 4.When to use C4Container
  6. 5.Put it together: Notes app context
  7. Check your level

Syntax cheatsheet

Quick reference for this diagram type

ConceptSyntax
DeclareC4Context · C4Container
PersonPerson(id, "Name", "Desc")
SystemSystem(id, "Name", "Desc")
ExternalSystem_Ext(id, "Name", "Desc")
RelRel(from, to, "Uses", "HTTPS")
BoundaryBoundary(id, "Name") { … }
  1. 1

    Start a C4 context diagram

    Begin with C4Context for a system-context view. Add an optional title on the next line.

    C4 diagrams are Preview-only in SayDiagram (full slide in Present).

    C4Context
  title System Context
  Person(user, "User", "A customer")
  System(app, "App", "Core product")
  Rel(user, app, "Uses")
    Expand
  2. 2

    People and systems

    Person is a human actor. System is software you own. System_Ext is an external dependency (email, payment, storage).

    Ids are identifiers — keep them short; quoted strings are display labels.

    C4Context
  Person(user, "User", "Creates notes")
  System(app, "Notes App", "Web product")
  System_Ext(email, "Email", "Notifications")
    Expand
  3. 3

    Relationships

    Connect elements with Rel(from, to, "label") or Rel(from, to, "label", "tech"). BiRel is bidirectional.

    Labels should describe the interaction (Uses, Sends email), not implementation details alone.

    C4Context
  Person(user, "User", "Creates notes")
  System(app, "Notes App", "Web product")
  System_Ext(email, "Email", "Notifications")
  Rel(user, app, "Uses", "HTTPS")
  Rel(app, email, "Sends email", "SMTP")
    Expand
  4. 4

    When to use C4Container

    Switch to C4Container when you need apps, databases, or APIs inside a system boundary.

    For most Idea → diagram prompts, C4Context is enough — drill into containers only when the idea names them.

    • Tip: SayDiagram’s blank C4 stub and Idea default use C4Context.
    C4Container
  title Containers for Notes App
  Person(user, "User", "Creates notes")
  System_Boundary(b1, "Notes App") {
    Container(web, "Web App", "Next.js", "UI")
    ContainerDb(db, "Database", "Postgres", "Stores notes")
  }
  Rel(user, web, "Uses", "HTTPS")
  Rel(web, db, "Reads/Writes", "SQL")
    Expand
  5. 5

    Put it together: Notes app context

    Combine Person, System, external systems, and Rels into the Examples gallery template.

    C4Context
  title System Context for Notes App
  Person(user, "User", "Creates and shares notes")
  System(app, "Notes App", "Web notes product")
  System_Ext(email, "Email Provider", "Transactional email")
  System_Ext(storage, "Object Storage", "File attachments")
  Rel(user, app, "Uses", "HTTPS")
  Rel(app, email, "Sends email", "SMTP")
  Rel(app, storage, "Stores files", "S3 API")
    Expand

Check your level

80% or higher certifies this lesson. You'll get 3–5 random questions from a larger bank.

Back to examples