Acefy Architecture Language (AAL)

Learn the Acefy Architecture Language syntax for describing software systems, containers, components, relationships, and C4 views.

AAL C4 v0.2 — Level-Aware Semantics

Use C4 AI Instructions with an external AI assistant, then copy its generated AAL into a new C4 Architecture project. Inspect diagnostics and explicitly Save.

Independent project copies

Use Clone to cloud or Clone to local from a project card’s menu. The copy includes the last saved source and layout; future changes do not sync. Duplicate keeps the same location. Cloning is available only on the Projects page. At three cloud projects, delete one to make room; existing cloud projects can still be saved.

What is AAL?

Acefy Architecture Language (AAL) is a human-readable architecture description language used to create architecture models and generate C4 diagrams.

AAL separates three concerns:

Structural Type — Where does this element sit in C4? (person, system, container, component)
Semantic Type — What architectural role does it perform? (e.g. crm, api, repository)
Technology — How is that role implemented? (e.g. "Java / Spring Boot")

Pipeline

AAL Source → Parser → Architecture Model → View Engine → Layout Engine → Renderer → Canvas

AAL C4 v0.2 provides a small structural grammar (Person → System → Container → Component) combined with a rich level-aware semantic vocabulary of 270 semantic types across System, Container, and Component levels.

First Diagram

Here is a complete three-level AAL file demonstrating System, Container, and Component semantics:

The file starts with an architecture block, defines elements and relationships, then declares views at Context, Container, and Component levels.

AAL

architecture DigitalBanking {

    person Customer "Customer"

    system BankingPlatform "Digital Banking Platform" platform {

        container MobileApp "Mobile Banking App" mobile

        container BankingAPI "Banking API" api {
            technology "Java / Spring Boot"

            component AccountController "Account Controller" controller

            component AccountService "Account Service" applicationservice

            component AccountRepository "Account Repository" repository

            component CoreBankingAdapter "Core Banking Adapter" adapter

            component TransactionPublisher "Transaction Event Publisher" publisher
        }

        container EventBus "Banking Event Bus" eventbus

        container AccountDB "Account Database" relationaldb {
            technology "PostgreSQL"
        }
    }

    system IdentityPlatform "Identity Platform" external identity

    system CoreBanking "Core Banking System" external coresystem

    system FraudPlatform "Fraud Platform" external fraud

    Customer -> BankingPlatform "Uses"

    BankingAPI -> IdentityPlatform "Validates customer identity" {
        mode synchronous
        protocol oidc
    }

    BankingAPI -> CoreBanking "Executes banking transactions" {
        mode synchronous
        protocol https
    }

    BankingAPI -> EventBus "Publishes transaction events" {
        mode event
        protocol kafka
    }

    AccountRepository -> AccountDB "Reads and writes account data" {
        mode synchronous
        protocol postgres
    }

    CoreBankingAdapter -> CoreBanking "Invokes banking services" {
        mode synchronous
        protocol https
    }

    TransactionPublisher -> EventBus "Publishes transaction event" {
        mode event
        protocol kafka
    }
}

view context {
    title "Digital Banking — System Context"
}

view container BankingPlatform {
    title "Digital Banking — Container Architecture"
    layout left-to-right
}

view component BankingAPI {
    title "Banking API — Component Architecture"
    layout top-to-bottom
}

Language Structure

Every AAL file follows this structure:

Structure

architecture <Name> {

    // 1. Define persons (top-level)
    person <id> "<name>"

    // 2. Define systems (may contain containers)
    system <id> "<name>" [external <semanticType>] {
        container <id> "<name>" <semanticType> {
            component <id> "<name>" <semanticType>
        }
    }

    // 3. Define relationships
    <source> -> <destination> "<description>" {
        technology "..."
        protocol <protocol>
        mode <mode>
    }

    // 4. Define views
    view <level> [<target>] {
        title "..."
        layout left-to-right
        include <ElementId>
        exclude <ElementId>
    }
}

Elements use a hierarchy: Person → System → Container → Component. Semantic types are level-aware: System semantics apply to systems, Container semantics to containers, Component semantics to components.