# sina-salahshour/mahlang architecture

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

- Interactive diagram: https://gitdiagram.com/sina-salahshour/mahlang
- Repository: https://github.com/sina-salahshour/mahlang

## Overview

Mah is a programming language toolchain: users compile or run source through the `mah` CLI, which preprocesses modules, compiles and type-checks them, and emits portable `.mahc` bytecode or executes it. That bytecode is the boundary shared by the Python and Rust VMs. Separate tooling provides formatting, project setup, and LSP features; the README also documents a standard library and editor integrations. Some subsystem links below are documented rather than source-verified because their implementation files were not sampled.

Main entry points: [`mah/cli/main.py`](https://github.com/sina-salahshour/mahlang/blob/main/mah/cli/main.py) (Mah CLI), [`mah/lsp/analysis.py`](https://github.com/sina-salahshour/mahlang/blob/main/mah/lsp/analysis.py) (Language analysis), [`mah/bytecode/lower.py`](https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/lower.py) (Bytecode lowering), [`mah/code_interpreter.py`](https://github.com/sina-salahshour/mahlang/blob/main/mah/code_interpreter.py) (Python VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Language frontend"]
  node_preprocessor["Module preprocessor<br/>[preprocessor.py]"]
  node_lexer["Lexer<br/>[lexer.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast["AST model<br/>[ast_nodes.py]"]
  node_resolver["Resolver<br/>[resolve.py]"]
  node_typechecker["Type checker<br/>[typecheck.py]"]
  node_codegen["Code generator<br/>[codegen.py]"]
end

subgraph group_bytecode["Bytecode"]
  node_lower["Bytecode lowering<br/>[lower.py]"]
  node_format["Bytecode format<br/>[format.py]"]
  node_program["Program model<br/>[program.py]"]
  node_decoder["Bytecode decoder<br/>[decode.py]"]
end

subgraph group_runtime["Execution runtimes"]
  node_pythonvm["Python VM"]
  node_values["Runtime values<br/>[runtime_values.py]"]
  node_natives["Native functions<br/>[natives.py]"]
  node_rustvm["Rust VM<br/>[exec.rs]"]
  node_rustdecode["Rust decoder<br/>[decode.rs]"]
end

subgraph group_tooling["Developer tooling"]
  node_formatter["Source formatter<br/>[formatter.py]"]
  node_lsp["Language server<br/>[server.py]"]
  node_analysis["Language analysis<br/>[analysis.py]"]
  node_editor["VS Code extension<br/>[extension.ts]"]
end

subgraph group_project["Project support"]
  node_cli["Mah CLI<br/>[main.py]"]
  node_manifest["Project manifest<br/>[manifest.py]"]
  node_projectinit["Project initializer<br/>[init.py]"]
end

node_user(("Language user"))
node_editoruser(("Editor user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"compiles source"| node_preprocessor
node_preprocessor -->|"prepares source"| node_lexer
node_lexer -->|"produces tokens"| node_parser
node_parser -->|"produces AST"| node_ast
node_resolver -->|"walks AST"| node_ast
node_cli -->|"compiles source"| node_resolver
node_cli -->|"checks types"| node_typechecker
node_typechecker -->|"checks AST"| node_ast
node_cli -->|"generates code"| node_codegen
node_codegen -->|"reads AST"| node_ast
node_codegen -->|"lowers code"| node_lower
node_lower -->|"uses module data"| node_preprocessor
node_lower -->|"uses opcodes"| node_format
node_lower -->|"builds program"| node_program
node_cli -->|"runs bytecode"| node_pythonvm
node_cli -->|"runs bytecode"| node_rustvm
node_pythonvm -->|"decodes bytecode"| node_decoder
node_decoder -->|"reads format"| node_format
node_decoder -->|"creates program"| node_program
node_pythonvm -->|"uses values"| node_values
node_pythonvm -->|"links natives"| node_natives
node_rustvm -->|"executes decoded code"| node_rustdecode
node_rustdecode -->|"links bytecode"| node_rustvm
node_cli -->|"formats source"| node_formatter
node_cli -->|"starts server"| node_lsp
node_lsp -->|"requests analysis"| node_analysis
node_analysis -->|"uses parser"| node_parser
node_analysis -->|"uses resolver"| node_resolver
node_analysis -->|"uses checker"| node_typechecker
node_analysis -.->|"uses formatter"| node_formatter
node_cli -->|"loads project"| node_manifest
node_cli -->|"initializes project"| node_projectinit
node_projectinit -->|"creates manifest"| node_manifest
node_editoruser -->|"uses editor"| node_editor
node_editor -.->|"connects to server"| node_lsp

click node_cli "https://github.com/sina-salahshour/mahlang/blob/main/mah/cli/main.py"
click node_preprocessor "https://github.com/sina-salahshour/mahlang/blob/main/mah/preprocessor.py"
click node_lexer "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/lexer.py"
click node_parser "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/parser.py"
click node_ast "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/ast_nodes.py"
click node_resolver "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/resolve.py"
click node_typechecker "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/typecheck.py"
click node_codegen "https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/codegen.py"
click node_lower "https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/lower.py"
click node_format "https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/format.py"
click node_program "https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/program.py"
click node_decoder "https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/decode.py"
click node_pythonvm "https://github.com/sina-salahshour/mahlang/blob/main/mah/code_interpreter.py"
click node_values "https://github.com/sina-salahshour/mahlang/blob/main/mah/runtime_values.py"
click node_natives "https://github.com/sina-salahshour/mahlang/blob/main/mah/natives.py"
click node_rustvm "https://github.com/sina-salahshour/mahlang/blob/main/runtime/src/vm/exec.rs"
click node_rustdecode "https://github.com/sina-salahshour/mahlang/blob/main/runtime/src/decode.rs"
click node_formatter "https://github.com/sina-salahshour/mahlang/blob/main/mah/format/formatter.py"
click node_lsp "https://github.com/sina-salahshour/mahlang/blob/main/mah/lsp/server.py"
click node_analysis "https://github.com/sina-salahshour/mahlang/blob/main/mah/lsp/analysis.py"
click node_manifest "https://github.com/sina-salahshour/mahlang/blob/main/mah/project/manifest.py"
click node_projectinit "https://github.com/sina-salahshour/mahlang/blob/main/mah/project/init.py"
click node_editor "https://github.com/sina-salahshour/mahlang/blob/main/editors/vscode/src/extension.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_preprocessor,node_lexer,node_parser,node_ast,node_resolver,node_typechecker,node_codegen,node_user,node_editoruser toneBlue
class node_lower,node_format,node_program,node_decoder toneAmber
class node_pythonvm,node_values,node_natives,node_rustvm,node_rustdecode toneMint
class node_formatter,node_lsp,node_analysis,node_editor toneRose
class node_cli,node_manifest,node_projectinit toneIndigo
```

## Components

### Language frontend

- [Module preprocessor](https://github.com/sina-salahshour/mahlang/blob/main/mah/preprocessor.py): `mah/preprocessor.py`
- [Lexer](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/lexer.py): `mah/compiler/lexer.py`
- [Parser](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/parser.py): `mah/compiler/parser.py`
- [AST model](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/ast_nodes.py): `mah/compiler/ast_nodes.py`
- [Resolver](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/resolve.py): `mah/compiler/resolve.py`
- [Type checker](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/typecheck.py): `mah/compiler/typecheck.py`
- [Code generator](https://github.com/sina-salahshour/mahlang/blob/main/mah/compiler/codegen.py): `mah/compiler/codegen.py`

### Bytecode

- [Bytecode lowering](https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/lower.py): `mah/bytecode/lower.py`
- [Bytecode format](https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/format.py): `mah/bytecode/format.py`
- [Program model](https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/program.py): `mah/bytecode/program.py`
- [Bytecode decoder](https://github.com/sina-salahshour/mahlang/blob/main/mah/bytecode/decode.py): `mah/bytecode/decode.py`

### Execution runtimes

- [Python VM](https://github.com/sina-salahshour/mahlang/blob/main/mah/code_interpreter.py): `mah/code_interpreter.py`
- [Runtime values](https://github.com/sina-salahshour/mahlang/blob/main/mah/runtime_values.py): `mah/runtime_values.py`
- [Native functions](https://github.com/sina-salahshour/mahlang/blob/main/mah/natives.py): `mah/natives.py`
- [Rust VM](https://github.com/sina-salahshour/mahlang/blob/main/runtime/src/vm/exec.rs): `runtime/src/vm/exec.rs`
- [Rust decoder](https://github.com/sina-salahshour/mahlang/blob/main/runtime/src/decode.rs): `runtime/src/decode.rs`

### Developer tooling

- [Source formatter](https://github.com/sina-salahshour/mahlang/blob/main/mah/format/formatter.py): `mah/format/formatter.py`
- [Language server](https://github.com/sina-salahshour/mahlang/blob/main/mah/lsp/server.py): `mah/lsp/server.py`
- [Language analysis](https://github.com/sina-salahshour/mahlang/blob/main/mah/lsp/analysis.py): `mah/lsp/analysis.py`
- [VS Code extension](https://github.com/sina-salahshour/mahlang/blob/main/editors/vscode/src/extension.ts): `editors/vscode/src/extension.ts`

### Project support

- [Mah CLI](https://github.com/sina-salahshour/mahlang/blob/main/mah/cli/main.py): `mah/cli/main.py`
- [Project manifest](https://github.com/sina-salahshour/mahlang/blob/main/mah/project/manifest.py): `mah/project/manifest.py`
- [Project initializer](https://github.com/sina-salahshour/mahlang/blob/main/mah/project/init.py): `mah/project/init.py`

### Other components

- **Language user**
- **Editor user**

## Connections

- Language user → Mah CLI: runs commands
- Mah CLI → Module preprocessor: compiles source (evidence: `mah/cli/main.py`)
- Module preprocessor → Lexer: prepares source (evidence: `mah/preprocessor.py`)
- Lexer → Parser: produces tokens (evidence: `mah/compiler/parser.py`)
- Parser → AST model: produces AST (evidence: `mah/compiler/parser.py`)
- Resolver → AST model: walks AST (evidence: `mah/compiler/resolve.py`)
- Mah CLI → Resolver: compiles source (evidence: `mah/cli/main.py`)
- Mah CLI → Type checker: checks types (evidence: `mah/cli/main.py`)
- Type checker → AST model: checks AST (evidence: `mah/compiler/typecheck.py`)
- Mah CLI → Code generator: generates code (evidence: `mah/cli/main.py`)
- Code generator → AST model: reads AST (evidence: `mah/compiler/codegen.py`)
- Code generator → Bytecode lowering: lowers code (evidence: `mah/bytecode/lower.py`)
- Bytecode lowering → Module preprocessor: uses module data (evidence: `mah/bytecode/lower.py`)
- Bytecode lowering → Bytecode format: uses opcodes (evidence: `mah/bytecode/lower.py`)
- Bytecode lowering → Program model: builds program (evidence: `mah/bytecode/lower.py`)
- Mah CLI → Python VM: runs bytecode (evidence: `mah/cli/main.py`)
- Mah CLI → Rust VM: runs bytecode
- Python VM → Bytecode decoder: decodes bytecode (evidence: `mah/code_interpreter.py`)
- Bytecode decoder → Bytecode format: reads format (evidence: `mah/bytecode/decode.py`)
- Bytecode decoder → Program model: creates program (evidence: `mah/bytecode/decode.py`)
- Python VM → Runtime values: uses values (evidence: `mah/code_interpreter.py`)
- Python VM → Native functions: links natives (evidence: `mah/code_interpreter.py`)
- Rust VM → Rust decoder: executes decoded code (evidence: `runtime/src/vm/exec.rs`)
- Rust decoder → Rust VM: links bytecode (evidence: `runtime/src/decode.rs`)
- Mah CLI → Source formatter: formats source
- Mah CLI → Language server: starts server (evidence: `mah/cli/main.py`)
- Language server → Language analysis: requests analysis (evidence: `mah/lsp/server.py`)
- Language analysis → Parser: uses parser (evidence: `mah/lsp/analysis.py`)
- Language analysis → Resolver: uses resolver (evidence: `mah/lsp/analysis.py`)
- Language analysis → Type checker: uses checker (evidence: `mah/lsp/analysis.py`)
- Language analysis → Source formatter: uses formatter (evidence: `mah/lsp/analysis.py`)
- Mah CLI → Project manifest: loads project (evidence: `mah/project/manifest.py`)
- Mah CLI → Project initializer: initializes project (evidence: `mah/cli/main.py`)
- Project initializer → Project manifest: creates manifest (evidence: `mah/project/init.py`)
- Editor user → VS Code extension: uses editor
- VS Code extension → Language server: connects to server
