Architecture as Code

Archyl lets you define your entire C4 architecture in a single YAML file — archyl.yaml. Check it into your repository, edit it alongside your code, and let CI/CD keep your diagrams in sync automatically.

Overview

The archyl.yaml file is a declarative description of your architecture. It supports:

• All four C4 levels (systems, containers, components, code)
• Relationships between any elements
• Technologies, environments, and releases
• ADRs, documentation, API contracts, and event channels
• Visual overlays for diagram grouping
• Monorepo support via include

You can author it by hand, export it from an existing project, or combine both workflows.

File Format

Archyl looks for the DSL file at the repository root, trying these names in order:

1. archyl.yaml
2. .archyl.yaml
3. archyl.yml
4. .archyl.yml

Schema Reference

Root Structure

version: "1.0"

project:
  name: My Platform
  description: E-commerce platform serving 10M users
  tags: [e-commerce, saas]

technologies: [...]
environments: [...]
systems: [...]
relationships: [...]
overlays: [...]
events: [...]
api_contracts: [...]
adrs:
  folder: docs/adrs
  records: [...]
docs:
  folder: docs
  records: [...]
releases: [...]
include: [...]

Only version is required. Every other section is optional — include only what you need.

Systems (C4 Level 1)

Systems are the top-level elements in the C4 model.

systems:
  - name: Payment Service
    description: Handles all payment processing
    type: software_system   # person | software_system | external_system
    external: false
    tags: [payments, critical]
    technologies: [Go, PostgreSQL]
    owners:
      teams: [backend-team]
      users: [vincent]
    containers: [...]

Containers (C4 Level 2)

Containers are nested inside their parent system.

systems:
  - name: Payment Service
    containers:
      - name: API Gateway
        description: REST API for payment operations
        type: api
        tags: [rest, public]
        technologies: [Go, Fiber]
        owners:
          teams: [backend-team]
        components: [...]

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

When using include for monorepo files, use parent_system to specify which system this container belongs to:

# In services/payments/archyl.yaml
containers:
  - name: Payments API
    parent_system: Payment Service
    type: api

Components (C4 Level 3)

Components are nested inside their parent container.

containers:
  - name: API Gateway
    components:
      - name: PaymentHandler
        description: HTTP handler for payment endpoints
        type: handler
        file: internal/handler/payment.go
        tags: [http]
        technologies: [Go]
        code: [...]

Available component types: controller, service, repository, handler, middleware, model, util, config, adapter, port, resource, module, job, bundle, plugin, workflow, activity, entity.

Code Elements (C4 Level 4)

Code elements are nested inside their parent component.

components:
  - name: PaymentHandler
    code:
      - name: ProcessPayment
        description: Handles payment processing requests
        type: function
        language: go
        file: internal/handler/payment.go
        line_start: 42
        line_end: 87
        visibility: public
        signature: "func (h *PaymentHandler) ProcessPayment(c *fiber.Ctx) error"
        methods:
          - name: validate
            signature: "func validate(req PaymentRequest) error"
            return_type: error
            visibility: private
        properties:
          - name: maxRetries
            type: int
            visibility: private
            readonly: true

Available code element types: class, interface, struct, function, method, enum, constant, type.

Relationships

Relationships connect any two elements using dot-notation for nested references.

relationships:
  - from: Payment Service.API Gateway
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL, PostgreSQL]
    tags: [data-access]
    style:
      color: "#6366f1"
      width: 2
      style: solid       # solid | dashed | dotted
      animated: false

Dot-notation format: System.Container.Component.CodeElement. Use only as many levels as needed — Payment Service references the system, Payment Service.API Gateway references a container.

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

Technologies

Define a catalog of technologies used across your architecture.

technologies:
  - name: Go
    description: Primary backend language
    category: programming_language
    icon: go
  - name: PostgreSQL
    description: Main relational database
    category: database
    icon: postgresql

Available categories: programming_language, framework, database, message_broker, object_storage, transport_protocol, cloud_service, devops_tool, library, runtime, cache, other.

Environments

Define deployment environments for your releases.

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"
  - name: Development
    color: "#6366f1"

Releases

Track versioned deployments across environments and elements.

releases:
  - version: "2.4.0"
    status: deployed          # planned | in_progress | deployed | rolled_back | failed
    changelog: "Added payment retry logic and improved error handling"
    environment: Production
    container: Payment Service.API Gateway
    released_at: "2026-03-10T14:00:00Z"
    source: github_action
    source_url: "https://github.com/org/repo/actions/runs/12345"

Event Channels

Define asynchronous messaging between services.

events:
  - name: PaymentCompleted
    description: Fired when a payment is successfully processed
    direction: produce         # produce | consume
    broker: kafka              # kafka | nats | sqs | rabbitmq | redis | pulsar | custom
    topic: payments.completed
    schema_format: json_schema # json_schema | avro | protobuf | text
    schema: |
      { "type": "object", "properties": { "paymentId": { "type": "string" } } }
    links:
      - Payment Service.API Gateway

API Contracts

Attach API specifications to your architecture.

api_contracts:
  - name: Payment API
    description: REST API for payment operations
    type: http                 # http | grpc | graphql | async
    version: "2.0"
    endpoint: /api/v2/payments
    file: docs/openapi.yaml    # path to spec file in repo
    links:
      - Payment Service.API Gateway

You can use file to reference a spec file in the repository, or content to inline the spec directly.

Architecture Decision Records (ADRs)

adrs:
  folder: docs/adrs            # optional: path to ADR folder in repo
  records:
    - title: Use event-driven architecture for payments
      number: 7
      status: accepted         # proposed | accepted | deprecated | superseded
      date: "2026-02-15"
      context: We need to decouple payment processing from order management
      decision: Use Kafka events for async communication between services
      consequences: Added complexity but improved resilience and scalability
      tags: [architecture, messaging]
      links:
        - Payment Service

Documentation

docs:
  folder: docs                 # optional: path to docs folder in repo
  records:
    - title: Payment Processing Guide
      file: docs/payments.md   # path to markdown file in repo
      tags: [payments, guide]
      links:
        - Payment Service.API Gateway

You can use file to reference a markdown file in the repository, or content to inline the content directly.

Overlays

Visual groupings that appear on the diagram.

overlays:
  - name: Payment Domain
    description: All payment-related services
    color: "#6366f1"
    level: 2                   # C4 level (1=system, 2=container, 3=component, 4=code)
    elements:
      - Payment Service.API Gateway
      - Payment Service.Database
      - Payment Service.Worker

Include (Monorepo Support)

For monorepos, split your architecture across multiple files and merge them:

include:
  - services/payments/archyl.yaml
  - services/orders/archyl.yaml
  - services/users/archyl.yaml

Each included file follows the same schema. Use parent_system on containers to specify which system they belong to when defined in a separate file.

Complete Example

version: "1.0"

project:
  name: E-Commerce Platform
  description: Online marketplace with payment processing
  tags: [e-commerce, saas, marketplace]

technologies:
  - name: Go
    category: programming_language
  - name: React
    category: framework
  - name: PostgreSQL
    category: database
  - name: Kafka
    category: message_broker
  - name: Redis
    category: cache

environments:
  - name: Production
    color: "#22c55e"
  - name: Staging
    color: "#f59e0b"

systems:
  - name: Storefront
    description: Customer-facing web application
    type: software_system
    technologies: [React]
    containers:
      - name: Web App
        type: web_app
        technologies: [React]
      - name: BFF
        description: Backend for frontend
        type: api
        technologies: [Go]

  - name: Payment Service
    description: Handles payment processing
    type: software_system
    technologies: [Go, PostgreSQL]
    containers:
      - name: API
        type: api
        technologies: [Go]
        components:
          - name: PaymentHandler
            type: handler
          - name: PaymentService
            type: service
          - name: PaymentRepository
            type: repository
      - name: Database
        type: database
        technologies: [PostgreSQL]
      - name: Worker
        type: worker
        technologies: [Go]

  - name: Stripe
    description: Third-party payment processor
    type: external_system
    external: true

relationships:
  - from: Storefront.Web App
    to: Storefront.BFF
    label: API calls
    type: uses
    technologies: [HTTPS]
  - from: Storefront.BFF
    to: Payment Service.API
    label: Process payments
    type: calls
    technologies: [gRPC]
  - from: Payment Service.API
    to: Payment Service.Database
    label: Reads/writes payment data
    type: uses
    technologies: [SQL]
  - from: Payment Service.API
    to: Stripe
    label: Process charges
    type: calls
    technologies: [HTTPS]
  - from: Payment Service.Worker
    to: Payment Service.Database
    label: Polls for pending payments
    type: reads_from

events:
  - name: PaymentCompleted
    broker: kafka
    topic: payments.completed
    direction: produce
    links:
      - Payment Service.API

overlays:
  - name: Payment Domain
    level: 2
    color: "#6366f1"
    elements:
      - Payment Service.API
      - Payment Service.Database
      - Payment Service.Worker

releases:
  - version: "1.2.0"
    status: deployed
    environment: Production
    container: Payment Service.API
    changelog: Added retry logic for failed charges
    released_at: "2026-03-01T10:00:00Z"

Syncing from a Repository

If your repository contains an archyl.yaml, you can sync it directly from the Archyl UI:

1. Go to Project Settings > Architecture as Code
2. Click Sync Now

Archyl fetches the file from your repository's default branch (or the branch configured in DSL settings) and imports it. Elements that already exist are updated; new elements are created.

CI/CD Integration

GitHub Action (Official)

The official archyl-com/actions/sync GitHub Action is the easiest way to keep your architecture in sync. It reads your archyl.yaml, pushes it to the Archyl API, and reports what was created or updated.

Minimal setup:

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

With summary output:

- uses: archyl-com/actions/sync@v1
  id: sync
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
- run: echo "${{ steps.sync.outputs.summary }}"

Custom file path (monorepo):

- uses: archyl-com/actions/sync@v1
  with:
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'
    file: 'services/payments/archyl.yaml'

Self-hosted Archyl:

- uses: archyl-com/actions/sync@v1
  with:
    api-url: 'https://archyl.your-company.com'
    api-key: ${{ secrets.ARCHYL_API_KEY }}
    project-id: 'your-project-uuid'

Action Inputs

Action Outputs

GitLab CI/CD

sync-architecture:
  stage: deploy
  only:
    changes: [archyl.yaml]
  script:
    - |
      curl -sf -X POST https://your-instance.com/api/v1/projects/${PROJECT_ID}/dsl/ingest \
        -H "X-API-Key: ${ARCHYL_API_KEY}" \
        -H "Content-Type: application/json" \
        -d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"

REST API

You can push DSL content from any CI/CD system or script:

curl -X POST https://your-instance.com/api/v1/projects/{projectId}/dsl/ingest \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat archyl.yaml | jq -Rs .)}"

The ingest endpoint returns a summary of what was created:

{
  "source": "api",
  "import": {
    "systemsCreated": 2,
    "containersCreated": 5,
    "componentsCreated": 12,
    "codeElementsCreated": 0,
    "relationshipsCreated": 8,
    "overlaysCreated": 1,
    "technologiesCreated": 4,
    "adrsCreated": 0,
    "docsCreated": 0,
    "eventsCreated": 1,
    "apiContractsCreated": 0,
    "environmentsCreated": 2,
    "releasesCreated": 1
  }
}

Exporting to YAML

You can export any existing project as an archyl.yaml file:

1. Open your project
2. Click Export in the toolbar
3. Select YAML (Architecture as Code)

This generates a complete archyl.yaml that you can check into your repository. It's a great way to bootstrap the file from an existing project or from an AI-discovered architecture.

You can also export via the API:

curl -H "X-API-Key: your-api-key" \
  https://your-instance.com/api/v1/projects/{projectId}/dsl/export \
  -o archyl.yaml

JSON Schema for IDE Support

Archyl provides a JSON Schema for archyl.yaml files so your editor can offer autocomplete and validation. The schema is available at:

https://your-instance.com/api/v1/dsl/schema

VS Code

Add this to your archyl.yaml to enable schema validation:

# yaml-language-server: $schema=https://your-instance.com/api/v1/dsl/schema
version: "1.0"

Or configure it globally in VS Code settings:

{
  "yaml.schemas": {
    "https://your-instance.com/api/v1/dsl/schema": ["archyl.yaml", ".archyl.yaml"]
  }
}

Image & PDF Export

Archyl also supports exporting your diagrams as images for presentations and documents.

Available Formats

How to Export

1. Navigate to the C4 level you want to export
2. Click Export in the toolbar
3. Select your format (PNG, SVG, or PDF)
4. Configure options (background, quality, viewport)
5. Click Export

Check Export all levels to generate separate files for each C4 level.

Export Options

• Background: Include dark canvas background or use transparent
• Quality (PNG only): Standard, High, or Print resolution
• Viewport: Fit content, include padding, or export current view

Importing Projects

You can create a new project by importing from multiple formats. Archyl supports four import sources:

How to Import

1. From your project list, click Import Project
2. Select the source format tab (Archyl YAML, Structurizr DSL, LikeC4, or IcePanel)
3. Upload the file or paste its content
4. Click Validate to preview what will be created
5. Click Create Project

The entire process takes under a minute. All systems, containers, components, relationships, technologies, and tags are imported automatically.

Structurizr DSL Import

Archyl parses Structurizr's .dsl workspace files and extracts the full C4 model:

• person, softwareSystem, container, component elements
• All -> relationships with descriptions and technologies
• External system detection from tags
• Technology extraction from positional arguments
• Groups mapped to tags

Views, styles, themes, and deployment nodes are skipped (Archyl has its own visual layer).

LikeC4 Import

Archyl is the first tool to import LikeC4 files. The importer handles LikeC4's unique features:

• Custom element kinds from specification blocks mapped to C4 levels
• Nested element hierarchies resolved to systems, containers, and components
• technology: and description: properties (with or without colon syntax)
• #hashtag tags converted to standard tags
• #external tag detection for boundary classification
• Multiple model blocks merged automatically
• Single-quoted and triple-quoted strings supported

IcePanel JSON Import

IcePanel's JSON export format is fully supported:

• system, actor, app, store, component object types mapped to C4 elements
• external: true field for external system classification
• modelConnections mapped to relationships
• tagIds resolved to tag names from the tags array
• domain objects used as project name

Import via MCP (AI Agents)

The same import capability is available through the import_dsl MCP tool:

Use the import_dsl tool with:
- projectId: your project UUID
- content: the DSL/JSON content
- format: "archyl", "structurizr", "likec4", or "icepanel"

This lets AI coding agents (Claude Code, Cursor, Windsurf) programmatically import architecture files.

Import into Existing Projects

You can also import into an existing project (not just create new ones):

1. Open your project
2. Go to Architecture as Code
3. Click Import
4. Select the format and upload

Elements that already exist are updated; new elements are created.

Next Steps

• API Overview — Full API reference for DSL endpoints
• Sharing & Embedding — Share live diagrams
• Release Management — Track deployments in your YAML
• Webhook Notifications — Get notified when architecture changes