Acefy Architecture Language (AAL)

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

Acefy Architecture Language (AAL) · AAL C4 0.2 · Level-aware semantics

On this page
Independent diagram copies
Copy to Cloud or Local creates an independent diagram in the chosen destination and leaves the original open. Future changes do not sync. Duplicate keeps the same project and location. Cloud folder and diagram counts are unlimited; document size and write-rate limits still apply.
Projects panel with a folder expanded to show its diagrams and Markdown documents
Expand a folder to browse its diagrams and Markdown documents. Click an item to open it.

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.