# vbxq/aelys_lang architecture

> Architecture diagram of the GitHub repository vbxq/aelys_lang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vbxq/aelys_lang
- Repository: https://github.com/vbxq/aelys_lang

## Overview

Aelys is a programming-language compiler, exposed through a command-line compiler and a public API. Its principal workflow turns source files into native code: the driver resolves imports, frontend stages produce syntax structures, semantic analysis type-checks and infers types, and successive IR/backend stages prepare and emit native output. The README emphasizes managed-memory and `nogc` checking, modules, and LLVM-based native compilation. The supplied excerpts do not show the compile command’s orchestration or all driver calls, so uncertain wiring is omitted; documented but unsampled capabilities are represented at their enclosing source directories.

Main entry points: [`driver/src/api/mod.rs`](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/mod.rs) (Compiler Driver), [`sema/src/infer.rs`](https://github.com/vbxq/aelys_lang/blob/feat/llvm/sema/src/infer.rs) (Type Inference), [`driver/src/api/llvm/link.rs`](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/llvm/link.rs) (LLVM Link And Runtime), [`cli/src/cli/commands/compile.rs`](https://github.com/vbxq/aelys_lang/blob/feat/llvm/cli/src/cli/commands/compile.rs) (Compile Command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Source Frontend"]
  node_lexer["Lexer<br/>[mod.rs]"]
  node_parser["Parser<br/>[mod.rs]"]
  node_syntax["Syntax AST<br/>[mod.rs]"]
end

subgraph group_semantics["Modules And Semantics"]
  node_module_resolve["Module Resolution<br/>[resolve.rs]"]
  node_module_graph["Module Graph<br/>[graph.rs]"]
  node_sema["Type Inference<br/>[infer.rs]"]
  node_typed_ast["Typed AST<br/>[mod.rs]"]
  node_diagnostics["Diagnostics<br/>[mod.rs]"]
end

subgraph group_middle["IR And Optimization"]
  node_optimizer["AST Optimizer<br/>[optimizer.rs]"]
  node_air_lower["AIR Lowering<br/>[program.rs]"]
  node_air_passes["AIR Checks And Passes<br/>[mod.rs]"]
end

subgraph group_backend["Native Backend"]
  node_codegen["LLVM Codegen<br/>[context.rs]"]
  node_llvm_driver["LLVM Link And Runtime<br/>[link.rs]"]
end

subgraph group_runtime["CLI And Runtime"]
  node_cli["Aelys CLI<br/>[main.rs]"]
  node_compile["Compile Command<br/>[compile.rs]"]
  node_facade["Public API<br/>[mod.rs]"]
  node_driver["Compiler Driver<br/>[mod.rs]"]
  node_core["Managed Memory Runtime<br/>[lib.rs]"]
end

node_user(("Programmer"))
node_source["Aelys Sources"]
node_native["Native Program"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_compile
node_compile -->|"requests compilation"| node_driver
node_driver -->|"resolves imports"| node_module_resolve
node_module_resolve -->|"builds graph"| node_module_graph
node_driver -->|"lexes sources"| node_lexer
node_lexer -->|"supplies tokens"| node_parser
node_parser -->|"builds AST"| node_syntax
node_driver -->|"type-checks"| node_sema
node_sema -->|"produces"| node_typed_ast
node_sema -->|"reports errors"| node_diagnostics
node_driver -->|"optimizes AST"| node_optimizer
node_driver -->|"lowers program"| node_air_lower
node_air_lower -->|"produces AIR"| node_air_passes
node_driver -->|"generates LLVM"| node_codegen
node_codegen -->|"supplies module"| node_llvm_driver
node_llvm_driver -->|"emits and links"| node_native
node_llvm_driver -.->|"links runtime"| node_core
node_user -->|"writes"| node_source
node_compile -->|"compiles"| node_source
node_user -->|"runs"| node_native
node_facade -->|"re-exports API"| node_driver

click node_cli "https://github.com/vbxq/aelys_lang/blob/feat/llvm/cli/src/main.rs"
click node_compile "https://github.com/vbxq/aelys_lang/blob/feat/llvm/cli/src/cli/commands/compile.rs"
click node_facade "https://github.com/vbxq/aelys_lang/blob/feat/llvm/aelys/src/api/mod.rs"
click node_driver "https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/mod.rs"
click node_module_resolve "https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/modules/resolve.rs"
click node_module_graph "https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/modules/graph.rs"
click node_lexer "https://github.com/vbxq/aelys_lang/blob/feat/llvm/frontend/src/lexer/mod.rs"
click node_parser "https://github.com/vbxq/aelys_lang/blob/feat/llvm/frontend/src/parser/mod.rs"
click node_syntax "https://github.com/vbxq/aelys_lang/blob/feat/llvm/syntax/src/ast/mod.rs"
click node_sema "https://github.com/vbxq/aelys_lang/blob/feat/llvm/sema/src/infer.rs"
click node_typed_ast "https://github.com/vbxq/aelys_lang/blob/feat/llvm/sema/src/typed_ast/mod.rs"
click node_diagnostics "https://github.com/vbxq/aelys_lang/blob/feat/llvm/common/src/diagnostic/mod.rs"
click node_optimizer "https://github.com/vbxq/aelys_lang/blob/feat/llvm/opt/src/passes/optimizer.rs"
click node_air_lower "https://github.com/vbxq/aelys_lang/blob/feat/llvm/air/src/lower/program.rs"
click node_air_passes "https://github.com/vbxq/aelys_lang/blob/feat/llvm/air/src/passes/mod.rs"
click node_codegen "https://github.com/vbxq/aelys_lang/blob/feat/llvm/codegen/src/api/context.rs"
click node_llvm_driver "https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/llvm/link.rs"
click node_core "https://github.com/vbxq/aelys_lang/blob/feat/llvm/core/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lexer,node_parser,node_syntax toneBlue
class node_module_resolve,node_module_graph,node_sema,node_typed_ast,node_diagnostics toneAmber
class node_optimizer,node_air_lower,node_air_passes toneMint
class node_codegen,node_llvm_driver toneRose
class node_cli,node_compile,node_facade,node_driver,node_core,node_user,node_source,node_native toneIndigo
```

## Components

### Source Frontend

- [Lexer](https://github.com/vbxq/aelys_lang/blob/feat/llvm/frontend/src/lexer/mod.rs): `frontend/src/lexer/mod.rs`
- [Parser](https://github.com/vbxq/aelys_lang/blob/feat/llvm/frontend/src/parser/mod.rs): `frontend/src/parser/mod.rs`
- [Syntax AST](https://github.com/vbxq/aelys_lang/blob/feat/llvm/syntax/src/ast/mod.rs): `syntax/src/ast/mod.rs`

### Modules And Semantics

- [Module Resolution](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/modules/resolve.rs): `driver/src/modules/resolve.rs`
- [Module Graph](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/modules/graph.rs): `driver/src/modules/graph.rs`
- [Type Inference](https://github.com/vbxq/aelys_lang/blob/feat/llvm/sema/src/infer.rs): `sema/src/infer.rs`
- [Typed AST](https://github.com/vbxq/aelys_lang/blob/feat/llvm/sema/src/typed_ast/mod.rs): `sema/src/typed_ast/mod.rs`
- [Diagnostics](https://github.com/vbxq/aelys_lang/blob/feat/llvm/common/src/diagnostic/mod.rs): `common/src/diagnostic/mod.rs`

### IR And Optimization

- [AST Optimizer](https://github.com/vbxq/aelys_lang/blob/feat/llvm/opt/src/passes/optimizer.rs): `opt/src/passes/optimizer.rs`
- [AIR Lowering](https://github.com/vbxq/aelys_lang/blob/feat/llvm/air/src/lower/program.rs): `air/src/lower/program.rs`
- [AIR Checks And Passes](https://github.com/vbxq/aelys_lang/blob/feat/llvm/air/src/passes/mod.rs): `air/src/passes/mod.rs`

### Native Backend

- [LLVM Codegen](https://github.com/vbxq/aelys_lang/blob/feat/llvm/codegen/src/api/context.rs): `codegen/src/api/context.rs`
- [LLVM Link And Runtime](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/llvm/link.rs): `driver/src/api/llvm/link.rs`

### CLI And Runtime

- [Aelys CLI](https://github.com/vbxq/aelys_lang/blob/feat/llvm/cli/src/main.rs): `cli/src/main.rs`
- [Compile Command](https://github.com/vbxq/aelys_lang/blob/feat/llvm/cli/src/cli/commands/compile.rs): `cli/src/cli/commands/compile.rs`
- [Public API](https://github.com/vbxq/aelys_lang/blob/feat/llvm/aelys/src/api/mod.rs): `aelys/src/api/mod.rs`
- [Compiler Driver](https://github.com/vbxq/aelys_lang/blob/feat/llvm/driver/src/api/mod.rs): `driver/src/api/mod.rs`
- [Managed Memory Runtime](https://github.com/vbxq/aelys_lang/blob/feat/llvm/core/src/lib.rs): `core/src/lib.rs`

### Other components

- **Programmer**
- **Aelys Sources**
- **Native Program**

## Connections

- Programmer → Aelys CLI: invokes
- Aelys CLI → Compile Command: dispatches
- Compile Command → Compiler Driver: requests compilation
- Compiler Driver → Module Resolution: resolves imports
- Module Resolution → Module Graph: builds graph
- Compiler Driver → Lexer: lexes sources
- Lexer → Parser: supplies tokens
- Parser → Syntax AST: builds AST
- Compiler Driver → Type Inference: type-checks
- Type Inference → Typed AST: produces
- Type Inference → Diagnostics: reports errors
- Compiler Driver → AST Optimizer: optimizes AST
- Compiler Driver → AIR Lowering: lowers program
- AIR Lowering → AIR Checks And Passes: produces AIR
- Compiler Driver → LLVM Codegen: generates LLVM
- LLVM Codegen → LLVM Link And Runtime: supplies module
- LLVM Link And Runtime → Native Program: emits and links
- LLVM Link And Runtime → Managed Memory Runtime: links runtime
- Programmer → Aelys Sources: writes
- Compile Command → Aelys Sources: compiles
- Programmer → Native Program: runs
- Public API → Compiler Driver: re-exports API