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

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")
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.
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:
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.