# alve-dev/zonetic-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/alve-dev/zonetic-compiler
- Repository: https://github.com/alve-dev/zonetic-compiler

## Overview

Zonetic is a statically typed, expression-oriented language compiler with CLI tooling and a bytecode backend. The main workflow is source input through lexing, normalization, parsing into an AST, semantic/type analysis, optimization, and bytecode emission for the external ZonVM. The graph also shows the compiler’s symbol/type layer and shared diagnostics. The README documents REPL and legacy-interpreter modes, but this source tree does not expose a separate interpreter or VM implementation; the CLI excerpt shows REPL input being sent through compilation.

Main entry points: [`src/zonc/cli/cmd_zonc.py`](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/cli/cmd_zonc.py) (CLI Commands), [`src/zonc/parser/parser.py`](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/parser/parser.py) (Parser), [`src/zonc/zonc_errors/engine.py`](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonc_errors/engine.py) (Diagnostic Engine), [`src/zonc/enviroment/enviroment.py`](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/enviroment/enviroment.py) (Symbols and Scopes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI Interface"]
  node_cli["CLI Commands<br/>[cmd_zonc.py]"]
end

subgraph group_front["Front End"]
  node_lexer["Lexer<br/>[lexer.py]"]
  node_normalizer["Normalizer<br/>[the_normalizer.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast["AST<br/>[program.py]"]
end

subgraph group_analysis["Analysis"]
  node_semantic["Semantic Analysis<br/>[semantic.py]"]
  node_typeinfer["Type Inference<br/>[type_inference.py]"]
  node_symbols["Symbols and Scopes<br/>[enviroment.py]"]
  node_optimization["AST Optimizations"]
  node_dce["Dead-Code Elimination"]
end

subgraph group_backend["Bytecode Backend"]
  node_emitter["Bytecode Emitter<br/>[emitter.py]"]
  node_exprgen["Expression Generation<br/>[expr_gen.py]"]
  node_stmtgen["Statement Generation<br/>[stmt_gen.py]"]
  node_scope["Bytecode Scope<br/>[bytecodescope.py]"]
  node_registers["Register Allocation"]
  node_instructions["Instructions and Data<br/>[instruction.py]"]
end

subgraph group_support["Compiler Support"]
  node_diagnostics["Diagnostic Engine<br/>[engine.py]"]
  node_renderer["Diagnostic Renderer<br/>[renderer.py]"]
  node_sourcepos["Source Spans<br/>[span.py]"]
end

node_user(("Programmer"))
node_vm["ZonVM"]

node_user -->|"submits code"| node_cli
node_cli -->|"scans source"| node_lexer
node_lexer -->|"tokens to"| node_normalizer
node_normalizer -->|"tokens to"| node_parser
node_parser -->|"builds"| node_ast
node_parser -->|"uses scopes"| node_symbols
node_parser -->|"emits errors"| node_diagnostics
node_cli -->|"parses tokens"| node_parser
node_cli -->|"checks AST"| node_semantic
node_semantic -->|"inherits inference"| node_typeinfer
node_semantic -->|"checks bindings"| node_symbols
node_typeinfer -->|"looks up names"| node_symbols
node_semantic -->|"emits errors"| node_diagnostics
node_cli -->|"folds constants"| node_optimization
node_cli -->|"eliminates dead code"| node_dce
node_optimization -->|"uses environment"| node_symbols
node_dce -->|"uses environment"| node_symbols
node_cli -->|"emits bytecode"| node_emitter
node_emitter -.->|"generates statements"| node_stmtgen
node_stmtgen -->|"generates expressions"| node_exprgen
node_exprgen -->|"uses scope"| node_scope
node_stmtgen -->|"uses scope"| node_scope
node_exprgen -->|"builds instructions"| node_instructions
node_stmtgen -->|"builds instructions"| node_instructions
node_emitter -.->|"allocates registers"| node_registers
node_emitter -->|"writes bytecode for"| node_vm
node_cli -->|"reports failures"| node_diagnostics
node_diagnostics -->|"renders diagnostics"| node_renderer
node_renderer -->|"uses spans"| node_sourcepos
node_lexer -->|"emits errors"| node_diagnostics

click node_cli "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/cli/cmd_zonc.py"
click node_lexer "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/scanner/lexer.py"
click node_normalizer "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/syntatic_normalizer/the_normalizer.py"
click node_parser "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/parser/parser.py"
click node_ast "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonast/program.py"
click node_semantic "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/semantic/semantic.py"
click node_typeinfer "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/semantic/type_inference.py"
click node_symbols "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/enviroment/enviroment.py"
click node_optimization "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/optimization/constant_folding.py"
click node_dce "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/optimization/dead_code_elimination.py"
click node_emitter "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/emitter.py"
click node_exprgen "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/expr_gen.py"
click node_stmtgen "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/stmt_gen.py"
click node_scope "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/bytecodescope.py"
click node_registers "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/linear_scan_register_allocation.py"
click node_instructions "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/instruction.py"
click node_diagnostics "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonc_errors/engine.py"
click node_renderer "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonc_errors/renderer.py"
click node_sourcepos "https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/location_file/span.py"

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_cli toneBlue
class node_lexer,node_normalizer,node_parser,node_ast toneAmber
class node_semantic,node_typeinfer,node_symbols,node_optimization,node_dce toneMint
class node_emitter,node_exprgen,node_stmtgen,node_scope,node_registers,node_instructions toneRose
class node_diagnostics,node_renderer,node_sourcepos,node_user,node_vm toneIndigo
```

## Components

### CLI Interface

- [CLI Commands](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/cli/cmd_zonc.py): `src/zonc/cli/cmd_zonc.py`

### Front End

- [Lexer](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/scanner/lexer.py): `src/zonc/scanner/lexer.py`
- [Normalizer](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/syntatic_normalizer/the_normalizer.py): `src/zonc/syntatic_normalizer/the_normalizer.py`
- [Parser](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/parser/parser.py): `src/zonc/parser/parser.py`
- [AST](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonast/program.py): `src/zonc/zonast/program.py`

### Analysis

- [Semantic Analysis](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/semantic/semantic.py): `src/zonc/semantic/semantic.py`
- [Type Inference](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/semantic/type_inference.py): `src/zonc/semantic/type_inference.py`
- [Symbols and Scopes](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/enviroment/enviroment.py): `src/zonc/enviroment/enviroment.py`
- [AST Optimizations](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/optimization/constant_folding.py): `src/zonc/optimization/constant_folding.py`
- [Dead-Code Elimination](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/optimization/dead_code_elimination.py): `src/zonc/optimization/dead_code_elimination.py`

### Bytecode Backend

- [Bytecode Emitter](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/emitter.py): `src/zonc/bytecodegen/emitter.py`
- [Expression Generation](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/expr_gen.py): `src/zonc/bytecodegen/expr_gen.py`
- [Statement Generation](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/stmt_gen.py): `src/zonc/bytecodegen/stmt_gen.py`
- [Bytecode Scope](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/bytecodescope.py): `src/zonc/bytecodegen/bytecodescope.py`
- [Register Allocation](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/linear_scan_register_allocation.py): `src/zonc/bytecodegen/linear_scan_register_allocation.py`
- [Instructions and Data](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/bytecodegen/instruction.py): `src/zonc/bytecodegen/instruction.py`

### Compiler Support

- [Diagnostic Engine](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonc_errors/engine.py): `src/zonc/zonc_errors/engine.py`
- [Diagnostic Renderer](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/zonc_errors/renderer.py): `src/zonc/zonc_errors/renderer.py`
- [Source Spans](https://github.com/alve-dev/zonetic-compiler/blob/main/src/zonc/location_file/span.py): `src/zonc/location_file/span.py`

### Other components

- **Programmer**
- **ZonVM**

## Connections

- Programmer → CLI Commands: submits code
- CLI Commands → Lexer: scans source (evidence: `src/zonc/cli/cmd_zonc.py`)
- Lexer → Normalizer: tokens to
- Normalizer → Parser: tokens to
- Parser → AST: builds (evidence: `src/zonc/parser/parser.py`)
- Parser → Symbols and Scopes: uses scopes (evidence: `src/zonc/parser/parser.py`)
- Parser → Diagnostic Engine: emits errors (evidence: `src/zonc/parser/parser.py`)
- CLI Commands → Parser: parses tokens (evidence: `src/zonc/cli/cmd_zonc.py`)
- CLI Commands → Semantic Analysis: checks AST (evidence: `src/zonc/cli/cmd_zonc.py`)
- Semantic Analysis → Type Inference: inherits inference (evidence: `src/zonc/semantic/semantic.py`)
- Semantic Analysis → Symbols and Scopes: checks bindings (evidence: `src/zonc/semantic/semantic.py`)
- Type Inference → Symbols and Scopes: looks up names (evidence: `src/zonc/semantic/type_inference.py`)
- Semantic Analysis → Diagnostic Engine: emits errors (evidence: `src/zonc/semantic/semantic.py`)
- CLI Commands → AST Optimizations: folds constants (evidence: `src/zonc/cli/cmd_zonc.py`)
- CLI Commands → Dead-Code Elimination: eliminates dead code (evidence: `src/zonc/cli/cmd_zonc.py`)
- AST Optimizations → Symbols and Scopes: uses environment (evidence: `src/zonc/optimization/constant_folding.py`)
- Dead-Code Elimination → Symbols and Scopes: uses environment (evidence: `src/zonc/optimization/dead_code_elimination.py`)
- CLI Commands → Bytecode Emitter: emits bytecode (evidence: `src/zonc/cli/cmd_zonc.py`)
- Bytecode Emitter → Statement Generation: generates statements
- Statement Generation → Expression Generation: generates expressions (evidence: `src/zonc/bytecodegen/stmt_gen.py`)
- Expression Generation → Bytecode Scope: uses scope (evidence: `src/zonc/bytecodegen/expr_gen.py`)
- Statement Generation → Bytecode Scope: uses scope (evidence: `src/zonc/bytecodegen/stmt_gen.py`)
- Expression Generation → Instructions and Data: builds instructions (evidence: `src/zonc/bytecodegen/expr_gen.py`)
- Statement Generation → Instructions and Data: builds instructions (evidence: `src/zonc/bytecodegen/stmt_gen.py`)
- Bytecode Emitter → Register Allocation: allocates registers
- Bytecode Emitter → ZonVM: writes bytecode for
- CLI Commands → Diagnostic Engine: reports failures (evidence: `src/zonc/cli/cmd_zonc.py`)
- Diagnostic Engine → Diagnostic Renderer: renders diagnostics (evidence: `src/zonc/zonc_errors/engine.py`)
- Diagnostic Renderer → Source Spans: uses spans
- Lexer → Diagnostic Engine: emits errors (evidence: `src/zonc/scanner/lexer.py`)
