Architecture as Code with the C4 model — a complete archyl.yaml example (via https://www.archyl.com)

README.md

Architecture as Code with the C4 model — a complete archyl.yaml example

A minimal but complete example of defining a software architecture as version-controlled YAML using the C4 model (System → Container → Component → Code).

Why Architecture as Code?

Diagrams drawn in GUI tools drift out of date the moment code changes. Keeping your C4 model in a plain-text file next to your code means it is:

• Version-controlled — history, blame, and rollbacks like any other file.
• Reviewed in pull requests — architecture changes are discussed where code is.
• CI-checkable — you can fail a build when the documented architecture no longer matches reality.

The file

archyl.yaml defines a small "Checkout" system: a web app, a payments API with two components, an orders database, and an external Stripe system, with the relationships between them.

This is the format used by Archyl, an AI-powered architecture documentation platform built on the C4 model. Commit archyl.yaml to your repo and Archyl renders interactive C4 diagrams, then computes a drift score (0–100%) of how well the model matches your actual codebase. Full schema and docs: https://www.archyl.com/docs.

Valid type values (handy reference)

Container types: web_app, mobile_app, desktop_app, api, database, file_storage, message_queue, cache, service, function, worker, consumer, infrastructure, gateway, library

Relationship types: uses, depends_on, calls, reads_from, writes_to, sends_to, receives_from, implements, extends, contains, deployed_on, provisions, publishes_to, consumes_from

Learn more

• C4 model: https://c4model.com/
• Architecture as Code with Archyl: https://www.archyl.com

archyl.yaml

# archyl.yaml — Architecture as Code (C4 model)
# Define your software architecture in version-controlled YAML.
# Format used by Archyl (https://www.archyl.com). Docs: https://www.archyl.com/docs
# C4 hierarchy: System -> Container -> Component -> Code

version: "1.0"

project:
  name: "Checkout Platform"
  description: "Customer-facing purchase flow and order lifecycle"

# Optional technology catalog, reusable across containers
technologies:
  - name: Go
  - name: React
  - name: PostgreSQL
  - name: Stripe

systems:
  - name: Checkout
    type: software_system
    description: "Handles cart, payment and order fulfilment"
    containers:
      - name: Web App
        type: web_app
        technologies: [React, TypeScript]
        description: "Single-page storefront served to customers"

      - name: Payments API
        type: api
        technologies: [Go]
        description: "Stripe-backed charge and refund service"
        components:
          - name: OrderService
            description: "Orchestrates checkout -> payment -> fulfilment"
          - name: StripeClient
            description: "Wraps the Stripe charge/refund API"

      - name: Orders Database
        type: database
        technologies: [PostgreSQL]
        description: "Orders, payments and idempotency keys"

  # External systems are drawn as boundaries on the diagram
  - name: Stripe
    type: software_system
    external: true
    description: "Third-party payment provider"

relationships:
  - from: Web App
    to: Payments API
    label: "Submits payment"
    type: uses
  - from: Payments API
    to: Orders Database
    label: "Reads and writes orders"
    type: writes_to
  - from: Payments API
    to: Stripe
    label: "Charges card"
    type: uses