C4 Model

Archgram has first-class support for the C4 model using Mermaid's C4 diagram types. C4 gives you a structured way to document architecture at four levels of abstraction, each aimed at a different audience.

C4Context — System Context

The highest-level view. Show your system as a single box, surrounded by the people who use it and the external systems it integrates with.

Audience: Everyone — business stakeholders, product, security, new engineers.

C4Context
  title System Context — Order Management System
  Person(buyer, "Buyer", "Places and tracks orders")
  Person(ops, "Operations Team", "Monitors and manages fulfilment")
  System(oms, "Order Management System", "Handles order lifecycle from placement to delivery")
  System_Ext(erp, "ERP System", "Finance, inventory master data")
  System_Ext(carrier, "Shipping APIs", "DHL, FedEx, UPS — carrier booking and tracking")
  System_Ext(notify, "Notification Platform", "Email and SMS via SendGrid + Twilio")

  Rel(buyer, oms, "Places orders, tracks shipments", "HTTPS")
  Rel(ops, oms, "Reviews exceptions, manages manual holds", "HTTPS")
  Rel(oms, erp, "Syncs inventory and posts invoices", "REST/EDI")
  Rel(oms, carrier, "Books shipments and retrieves tracking", "REST")
  Rel(oms, notify, "Sends order confirmations and alerts", "REST")Open in Archgram

C4Container — Containers

Zoom into the system boundary. Show the deployable units (services, databases, queues, frontends) and how they communicate.

Audience: Engineers, architects, technical leads.

C4Container
  title Container Diagram — Order Management System
  Person(buyer, "Buyer")
  Person(ops, "Operations Team")

  System_Boundary(oms, "Order Management System") {
    Container(portal, "Buyer Portal", "React / TypeScript", "SPA — order placement and tracking")
    Container(ops_ui, "Ops Dashboard", "React / TypeScript", "Internal: exception management and reporting")
    Container(api, "Order API", "Go / Gin", "REST API — core order lifecycle")
    Container(worker, "Fulfilment Worker", "Go", "Consumes events; books carriers; updates tracking")
    ContainerDb(db, "Order Store", "PostgreSQL 15", "Orders, line items, shipments, events")
    Container(bus, "Event Bus", "Apache Kafka", "Async event stream between services")
  }

  System_Ext(carrier, "Shipping APIs")
  System_Ext(erp, "ERP System")
  System_Ext(notify, "Notification Platform")

  Rel(buyer, portal, "Uses", "HTTPS")
  Rel(ops, ops_ui, "Uses", "HTTPS")
  Rel(portal, api, "Calls", "HTTPS/REST")
  Rel(ops_ui, api, "Calls", "HTTPS/REST")
  Rel(api, db, "Reads/writes", "SQL")
  Rel(api, bus, "Publishes OrderPlaced, OrderUpdated", "Kafka")
  Rel(worker, bus, "Consumes events", "Kafka")
  Rel(worker, db, "Updates shipment status", "SQL")
  Rel(worker, carrier, "Books and tracks", "REST")
  Rel(worker, notify, "Triggers notifications", "REST")
  Rel(api, erp, "Syncs inventory", "REST")Open in Archgram

C4Component — Components

Zoom into one container and show its internal logical structure: domain services, repositories, adapters, event handlers.

Audience: The team building and maintaining that container.

C4Component
  title Component Diagram — Order API (Go service)
  Container_Boundary(api, "Order API") {
    Component(router, "HTTP Router", "Gin", "Route definitions, middleware chain (auth, logging, rate-limit)")
    Component(handler, "Order Handler", "Go struct", "Request parsing, validation, response mapping")
    Component(svc, "Order Service", "Go struct", "Domain logic: create, update, cancel, query orders")
    Component(repo, "Order Repository", "pgx/sqlc", "SQL queries; transaction management")
    Component(pub, "Event Publisher", "confluent-kafka-go", "Serialises and publishes domain events")
    Component(auth, "Auth Middleware", "Go func", "Validates JWTs; extracts claims")
  }
  ContainerDb(db, "PostgreSQL")
  Container_Ext(bus, "Kafka")

  Rel(router, auth, "Passes requests through")
  Rel(router, handler, "Routes to")
  Rel(handler, svc, "Delegates to")
  Rel(svc, repo, "Reads/writes via")
  Rel(svc, pub, "Publishes events via")
  Rel(repo, db, "SQL over TLS")
  Rel(pub, bus, "Kafka protocol")Open in Archgram

Drill-Down Navigation

In Archgram, you can create linked diagrams that form a navigable C4 hierarchy. From a container diagram, clicking on a container navigates to its component diagram. Configure drill-down links via the Link property in your diagram metadata.

Best Practices

• Always draw Level 1 first — it forces clarity about system boundaries
• Use System_Ext for everything outside your system boundary, including third-party SaaS
• Include technology labels on every Container ("Go / Gin", "PostgreSQL 15")
• Label every relationship with what it does and the protocol used
• Commit diagrams alongside the services they describe in git
• Update the relevant C4 level as part of any PR that changes a system boundary