Getting Started with AKS

Write your first AKS model in 15 minutes. We’ll build a simple e-commerce system step by step. Every snippet below parses with the real toolchain — the CI conformance test guarantees it.

Prerequisites

archkit CLI built (cargo build -p archkit-cli) or on your PATH
A text editor
15 minutes

Step 1: Create Your First Model (2 min)

Create a file called ecommerce.archkit.model.aks:

workspace "Ecommerce"
end workspace

Two rules to notice immediately: the workspace name is a quoted string, and every block — including the workspace itself — closes with end <keyword>. Verify it:

archkit parse -i ecommerce.archkit.model.aks

Step 2: Add Your First Entities (2 min)

Entities are system components. Properties always take the has keyword:

workspace "Ecommerce"
  entity frontend
    has role: presentation
  end entity

  entity api
    has role: orchestration
  end entity
end workspace

Step 3: Define a Shape (2 min)

Shapes are typed data structures:

workspace "Ecommerce"
  shape Product
    id: String
    name: String
    price: Float
    in_stock: Bool
  end shape

  entity frontend
    has role: presentation
  end entity

  entity api
    has role: orchestration
  end entity
end workspace

Fields are name: Type. Add ? for optional (String?) and [] for lists (String[]).

Step 4: Add a Shape Reference (2 min)

An entity that owns/manages a data structure references it in the header:

entity api: Product
  has role: orchestration
end entity

Step 5: Add Dependencies (3 min)

Dependencies are edge blocks inside entities. depends on is one of the built-in edge phrases:

workspace "Ecommerce"
  shape Product
    id: String
    name: String
    price: Float
    in_stock: Bool
  end shape

  entity frontend
    has role: presentation

    edge api depends on
    end edge
  end entity

  entity api: Product
    has role: orchestration

    edge product_db depends on
    end edge
  end entity

  entity product_db database
  end entity
end workspace

Now we have a dependency chain: frontend → api → product_db. Note entity product_db database — database is one of the built-in element kinds (database, queue, container, component, person, external system).

Step 6: Add an Event (2 min)

Events use the same field syntax as shapes and mark async messages:

event ProductPurchased
  product_id: String
  quantity: Int
  timestamp: Timestamp
end event

Add it inside the workspace alongside your shapes.

Step 7: Try archkit Commands (2 min)

Parse and validate:

archkit parse -i ecommerce.archkit.model.aks
# or the dedicated validator:
archkit-validate -i ecommerce.archkit.model.aks

Generate code from your shapes (TypeScript, JSON Schema, Python, Go, Protobuf, OpenAPI):

archkit generate code -i ecommerce.archkit.model.aks -t typescript.type -o generated/
archkit generate code -i ecommerce.archkit.model.aks -t json.schema -o generated/

Project a view:

archkit view file --help   # see projection options

Your First Complete Model

# Simple e-commerce system model
workspace "Ecommerce"
  module ecommerce@1.0.0

  shape Product
    id: String
    name: String
    price: Float
    in_stock: Bool
  end shape

  event ProductPurchased
    product_id: String
    quantity: Int
    timestamp: Timestamp
  end event

  entity frontend
    has role: presentation
    has description: "User-facing web application"

    edge api depends on
    end edge
  end entity

  entity api: Product
    has role: orchestration
    has description: "Backend API server"

    edge product_db depends on
    end edge
  end entity

  entity product_db database
    has description: "Data persistence layer"
  end entity
end workspace

Common Patterns

Modeling external systems

entity payment_gateway external system
  has description: "Stripe or similar"
end entity

Adding documentation

entity api
  has role: orchestration
  has description: "Main REST API. Implements GraphQL in v2.0"
end entity

Tagging for governance

entity api
  has tag critical
  has tag revenue_path
end entity

Troubleshooting

Parse error: “expected string, found Ident” — quote the workspace name: workspace "Ecommerce".

Parse error: “expected newline, found Ident” inside an entity — you wrote a bare key: value; entity properties need has key: value.

Parse error: “expected ‘end entity’” — every block needs its end <keyword> closer.

Parse error mentioning tabs — AKS indentation is spaces-only.

Next Steps

See more complex examples → Examples by Use Case
Learn all constructs → Core Concepts
The full grammar → grammar/FULL_GRAMMAR.md

Keyboard shortcuts

Archkit Documentation