AKS: Architecture Knowledge Syntax

Welcome to the Architecture Knowledge Syntax (AKS) documentation. AKS is the native language for defining, modeling, and validating distributed system architectures in archkit.

What is AKS?

AKS is a domain-specific language (DSL) designed to model complex systems through:

Entities - System components (services, databases, external systems)
Shapes - Data structures and type definitions
Events - State changes and system communications
Relationships - Connections and dependencies between entities
Policies - Governance rules and constraints
Lattices - Domain-specific partial orders and refinements
Views - Projections for different stakeholders (dependency graphs, workflows, data flows)

Why AKS?

Modern distributed systems are complex. Traditional documentation and diagrams fall out of sync with code. AKS solves this by:

Single source of truth - One model drives all documentation, diagrams, and validation
Machine-readable - Parse and transform AKS into TypeScript, JSON Schema, Mermaid diagrams, and more
Type-safe - Shapes and events automatically generate type definitions for your code
Governance-first - Define policies and constraints that archkit can validate
Evidence-tracked - Know where every piece of architecture came from (code, documentation, or mirrored)

Quick Start

The 2-Minute Version

Create a file myapp.archkit.model.aks:

workspace "MyApp"
  module myapp@1.0.0

  shape User
    id: String
    email: String
    created_at: Timestamp
  end shape

  entity auth_service: User
    has role: orchestration
  end entity

  entity user_db database
  end entity

  entity frontend
    has role: presentation

    edge auth_service depends on
    end edge
  end entity
end workspace

Then ask archkit to validate it or generate types from it:

archkit parse -i myapp.archkit.model.aks
archkit generate code -i myapp.archkit.model.aks -t typescript.type -o generated/

Where to Go Next

I want to…

Learn AKS basics in 15 minutes → Getting Started
Understand core concepts → Core Concepts
See real examples → Examples (choose your use case)
Look up syntax → Full Grammar
Generate code from my model → Type Extraction
Understand how archkit processes AKS → How Archkit Uses AKS
Trace exact frontend behavior against source (lexer/parser/lowering internals, live vs. dead pipelines) → Frontend Internals
Extend archkit with custom behavior → Extension Pipeline
Migrate from AKS v1 → Migration Guide

Core Concepts at a Glance

Concept	Purpose	Example
Workspace	Root container for all architecture	`workspace "MyApp" … end workspace`
Entity	System component (service, database, queue)	`entity user_db database … end entity`
Shape	Data structure or type definition	`shape User … end shape`
Event	State change or message	`event UserCreated … end event`
Relationship	Dependency or connection between entities	`relationship api calls db … end relationship`
Policy	Governance rule or constraint	`policy pii_encryption … end policy`
Lattice	Partial order for domain-specific reasoning	`lattice Environment … end lattice`
View	Projection for specific audience	`view revenue_overview … end view`
Evidence	Source of truth (code, docs, mirror)	`derived from: "doc:checkout-design"`

File Naming Convention

AKS files follow a predictable naming pattern:

<subject>.archkit.<kind>.<format>

Examples:
  workspace.archkit.model.aks              (authored model)
  tags.archkit.overlay.aks                 (overlay annotations)
  2026-06-30.cargo-workspace.archkit.mirror.aks  (timestamped mirror)

Subject: What the file describes (workspace, service, module)
Kind: model (authored), overlay (patches), mirror (auto-generated)
Format: Always aks for AKS files

Learning Path

Beginner

Getting Started — Write your first model
Examples: Systems Modeling — See progression from minimal to complex

Intermediate

Core Concepts — Deep dive on each construct
Grammar Reference — Detailed syntax rules
Examples: Your Use Case — Type definition, governance, or data flow examples

Advanced

Integration Docs — How archkit processes AKS
Extension Framework — Custom validators, transformers
Best Practices — Patterns for large models

Getting Help

Common Questions:

See Troubleshooting for errors and debugging
Check FAQ below

Need More?

Read the Full Grammar for comprehensive syntax
Explore Examples for working code
Check the Integration Guide for how archkit works internally

FAQ

Q: Do I need AKS for every project? A: No. AKS is ideal for distributed systems with multiple components, complex dependencies, or governance needs. Simple microservices might not benefit.

Q: Can I use AKS with existing code? A: Yes. Archkit can mirror your Cargo workspace or Rustdoc and auto-generate an AKS model as a starting point.

Q: What if my system is too complex for AKS? A: Break it into modules. AKS supports multi-file models with imports.

Q: Can I generate code from AKS? A: Yes. Shapes and events automatically generate TypeScript, JSON Schema, and other type definitions. See Type Extraction.

Q: What formats does archkit export to? A: TypeScript, JSON Schema, Mermaid diagrams, Graphviz/DOT, and more. See Artifact Generation.

Ready? Start with Getting Started or jump to Examples.

Keyboard shortcuts

Archkit Documentation