# programming-language-xiao/xiao architecture

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

- Interactive diagram: https://gitdiagram.com/programming-language-xiao/xiao
- Repository: https://github.com/programming-language-xiao/xiao

## Overview

Xiao is an in-development programming language and toolchain: Rust contains language semantics and execution components, while TypeScript provides the CLI/REPL boundary. The principal workflow is a user command or REPL input passing through the CLI protocol client to the Rust driver, then into language processing and a run/build/package operation. README documents static language analysis, configuration, modules, lifecycle, runtime, package management, environments, bytecode and LLVM paths. Some subsystems are documented but their wiring was not sampled; those links are omitted or marked planned.

Main entry points: [`core/rust/crates/xiao-driver/src/frontend.rs`](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/frontend.rs) (Language frontend), [`cli/ts/src/main.ts`](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/main.ts) (CLI entry), [`cli/ts/src/commands/index.ts`](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/commands/index.ts) (Command dispatch), [`core/rust/crates/xiao-driver/src/protocol/service.rs`](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/protocol/service.rs) (Protocol service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and REPL"]
  node_main["CLI entry<br/>[main.ts]"]
  node_args["Argument parser<br/>[parser.ts]"]
  node_commands["Command dispatch<br/>[index.ts]"]
  node_repl["REPL session<br/>[session.ts]"]
end

subgraph group_protocol["Core Protocol"]
  node_client["Protocol client<br/>[client.ts]"]
  node_driver["Protocol service<br/>[service.rs]"]
end

subgraph group_language["Language Core"]
  node_frontend["Language frontend<br/>[frontend.rs]"]
  node_syntax["Lexer and parser<br/>[parser.rs]"]
  node_types["Static semantics<br/>[lib.rs]"]
  node_modules["Module resolution<br/>[lib.rs]"]
  node_config["Config parsing<br/>[parser.rs]"]
  node_lifetime["Lifetime planning<br/>[lib.rs]"]
  node_diagnostics["Structured diagnostics<br/>[lib.rs]"]
end

subgraph group_execution["Execution Paths"]
  node_ir["Typed IR<br/>[lib.rs]"]
  node_bytecode["Bytecode lowering<br/>[mod.rs]"]
  node_vm["Bytecode VM<br/>[lib.rs]"]
  node_llvm["LLVM backend<br/>[lib.rs]"]
  node_runtime["Runtime<br/>[lib.rs]"]
end

subgraph group_operations["Packages and Environments"]
  node_packages["Package management<br/>[lib.rs]"]
  node_environment["Environment commands<br/>[index.ts]"]
end

node_user(("CLI user"))

node_user -->|"invokes"| node_main
node_main -->|"parses arguments"| node_args
node_main -->|"dispatches command"| node_commands
node_main -->|"starts session"| node_repl
node_commands -->|"sends requests"| node_client
node_repl -->|"runs source"| node_client
node_client -->|"frames requests"| node_driver
node_driver -->|"dispatches run"| node_frontend
node_frontend -->|"parses source"| node_syntax
node_frontend -->|"checks semantics"| node_types
node_frontend -->|"resolves imports"| node_modules
node_frontend -->|"parses configuration"| node_config
node_frontend -->|"plans releases"| node_lifetime
node_frontend -->|"reports errors"| node_diagnostics
node_frontend -.->|"produces typed IR"| node_ir
node_driver -->|"dispatches package operation"| node_packages
node_commands -->|"handles environment command"| node_environment
node_ir -.->|"lowers to bytecode"| node_bytecode
node_bytecode -.->|"executes bytecode"| node_vm
node_ir -.->|"feeds native backend"| node_llvm
node_vm -.->|"uses runtime"| node_runtime
node_llvm -.->|"targets runtime ABI"| node_runtime

click node_main "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/main.ts"
click node_args "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/commands/parser.ts"
click node_commands "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/commands/index.ts"
click node_repl "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/repl/session.ts"
click node_client "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/protocol/client.ts"
click node_driver "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/protocol/service.rs"
click node_frontend "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/frontend.rs"
click node_syntax "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-syntax/src/parser.rs"
click node_types "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-types/src/lib.rs"
click node_modules "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-modules/src/lib.rs"
click node_config "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-config/src/parser.rs"
click node_lifetime "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-lifetime/src/lib.rs"
click node_diagnostics "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-diagnostics/src/lib.rs"
click node_ir "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-ir/src/lib.rs"
click node_bytecode "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-bytecode/src/lower/mod.rs"
click node_vm "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-vm/src/lib.rs"
click node_llvm "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-codegen-llvm/src/lib.rs"
click node_runtime "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-runtime/src/lib.rs"
click node_packages "https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-package/src/lib.rs"
click node_environment "https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/environments/index.ts"

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_main,node_args,node_commands,node_repl,node_user toneBlue
class node_client,node_driver toneAmber
class node_frontend,node_syntax,node_types,node_modules,node_config,node_lifetime,node_diagnostics toneMint
class node_ir,node_bytecode,node_vm,node_llvm,node_runtime toneRose
class node_packages,node_environment toneIndigo
```

## Components

### CLI and REPL

- [CLI entry](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/main.ts): `cli/ts/src/main.ts`
- [Argument parser](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/commands/parser.ts): `cli/ts/src/commands/parser.ts`
- [Command dispatch](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/commands/index.ts): `cli/ts/src/commands/index.ts`
- [REPL session](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/repl/session.ts): `cli/ts/src/repl/session.ts`

### Core Protocol

- [Protocol client](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/protocol/client.ts): `cli/ts/src/protocol/client.ts`
- [Protocol service](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/protocol/service.rs): `core/rust/crates/xiao-driver/src/protocol/service.rs`

### Language Core

- [Language frontend](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-driver/src/frontend.rs): `core/rust/crates/xiao-driver/src/frontend.rs`
- [Lexer and parser](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-syntax/src/parser.rs): `core/rust/crates/xiao-syntax/src/parser.rs`
- [Static semantics](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-types/src/lib.rs): `core/rust/crates/xiao-types/src/lib.rs`
- [Module resolution](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-modules/src/lib.rs): `core/rust/crates/xiao-modules/src/lib.rs`
- [Config parsing](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-config/src/parser.rs): `core/rust/crates/xiao-config/src/parser.rs`
- [Lifetime planning](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-lifetime/src/lib.rs): `core/rust/crates/xiao-lifetime/src/lib.rs`
- [Structured diagnostics](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-diagnostics/src/lib.rs): `core/rust/crates/xiao-diagnostics/src/lib.rs`

### Execution Paths

- [Typed IR](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-ir/src/lib.rs): `core/rust/crates/xiao-ir/src/lib.rs`
- [Bytecode lowering](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-bytecode/src/lower/mod.rs): `core/rust/crates/xiao-bytecode/src/lower/mod.rs`
- [Bytecode VM](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-vm/src/lib.rs): `core/rust/crates/xiao-vm/src/lib.rs`
- [LLVM backend](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-codegen-llvm/src/lib.rs): `core/rust/crates/xiao-codegen-llvm/src/lib.rs`
- [Runtime](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-runtime/src/lib.rs): `core/rust/crates/xiao-runtime/src/lib.rs`

### Packages and Environments

- [Package management](https://github.com/programming-language-xiao/xiao/blob/main/core/rust/crates/xiao-package/src/lib.rs): `core/rust/crates/xiao-package/src/lib.rs`
- [Environment commands](https://github.com/programming-language-xiao/xiao/blob/main/cli/ts/src/environments/index.ts): `cli/ts/src/environments/index.ts`

### Other components

- **CLI user**

## Connections

- CLI user → CLI entry: invokes
- CLI entry → Argument parser: parses arguments
- CLI entry → Command dispatch: dispatches command
- CLI entry → REPL session: starts session
- Command dispatch → Protocol client: sends requests
- REPL session → Protocol client: runs source
- Protocol client → Protocol service: frames requests
- Protocol service → Language frontend: dispatches run
- Language frontend → Lexer and parser: parses source
- Language frontend → Static semantics: checks semantics
- Language frontend → Module resolution: resolves imports
- Language frontend → Config parsing: parses configuration
- Language frontend → Lifetime planning: plans releases
- Language frontend → Structured diagnostics: reports errors
- Language frontend → Typed IR: produces typed IR
- Protocol service → Package management: dispatches package operation
- Command dispatch → Environment commands: handles environment command
- Typed IR → Bytecode lowering: lowers to bytecode
- Bytecode lowering → Bytecode VM: executes bytecode
- Typed IR → LLVM backend: feeds native backend
- Bytecode VM → Runtime: uses runtime
- LLVM backend → Runtime: targets runtime ABI