# ultimatehaider/plantlang architecture

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

- Interactive diagram: https://gitdiagram.com/ultimatehaider/plantlang
- Repository: https://github.com/ultimatehaider/plantlang

## Overview

#### Purpose and entry points
PlantLang—Chloroplast is a self-hosted native compiler toolchain. It translates `.plant` source into C, then relies on GCC plus a C runtime to create executables. The user-facing compiler is `bin/Chloroplast`; the immutable bootstrap compiler is `dist/Chloroplast`. Compiler CLI behavior and compilation orchestration originate in `src/plantc/main.plant`.

#### Self-hosting build chain
The repository’s central control flow is bootstrap → compile compiler sources → link native compiler → repeat generations and compare artifacts for convergence. `Makefile` owns this build and self-hosting verification boundary; generated/intermediate compiler generations live under `build/`, while release-like executable outputs are under `bin/` and `dist/`. Required build infrastructure is local `make` and `gcc`; no VM or JavaScript runtime is involved.
Paths: `Makefile`, `dist/Chloroplast`, `build/plantc_all.plant`.

#### Front end: lexical and syntactic lowering
The compiler is itself PlantLang source. The lexer turns source text into tokens, and the parser constructs/interprets the language’s syntax and AST-level representation, including declarations, control flow, module imports, types, generics, closures, async constructs, and FFI declarations. Parse failures form the primary source-language diagnostic boundary before C emission.
Paths: `src/plantc/lexer.plant`, `src/plantc/parser.plant`, `src/plantc/main.plant`.

#### C code generation
The code generator maps PlantLang semantics to standalone C: native actions, data shapes/classes/unions, generic monomorphizations, closure environment/function pairs, cooperative async state machines, exception machinery, and external C declarations/calls. Generated C is the boundary between language implementation and platform compiler/linker; it includes or targets runtime APIs rather than embedding their implementation.
Paths: `src/plantc/codegen_c.plant`, `src/plantc/main.plant`.

#### Native runtime and memory model
The compiled program links against a lightweight C runtime that supplies PlantLang’s operational substrate: core value/container/string facilities, deterministic scope-oriented arena allocation, exception/control support, async scheduling/draining, and native service integrations. Runtime headers define the ABI and compatibility/type layer used by generated C. Programs compile with the runtime source and `-lm`.
Paths: `runtime/c/plant_runtime.c`, `runtime/c/plant_runtime.h`, `runtime/c/plant_types.h`.

#### External integration boundary
PlantLang code can call native C through declared externals, including reference values, structs, callbacks, varargs, handles, and error reporting. The runtime also exposes built-in native services such as filesystem, JSON, time, math, strings, and collections. Network/server and filesystem behavior is implemented as native capabilities invoked by compiled programs, not as repository-hosted services.
Paths: `runtime/c/plant_compat.h`, `runtime/c/plant_runtime.h`, `src/plantc/codegen_c.plant`.

#### Verification and executable lifecycle
The primary validation model is compile-and-run native integration coverage: test programs are compiled by Chloroplast, linked to the runtime, and compared with expected outputs. Suites specifically exercise language regressions, FFI/runtime behavior, generics, closures, async, persistence/memory, and performance. Examples provide direct source inputs for the same compiler-to-C-to-native lifecycle.
Paths: `tests/regression/run_regression_tests.sh`, `tests/native/run_native_tests.sh`, `examples/hello.plant`.

Main entry points: [`bin/Chloroplast`](https://github.com/ultimatehaider/plantlang/blob/Safarna/bin/Chloroplast) (Chloroplast), [`Makefile`](https://github.com/ultimatehaider/plantlang/blob/Safarna/Makefile) (Make build pipeline), [`src/plantc/main.plant`](https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/main.plant) (Compiler CLI and orchestration), [`build/plantc_all.plant`](https://github.com/ultimatehaider/plantlang/blob/Safarna/build/plantc_all.plant) (Combined compiler sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Self-hosting build"]
  node_makefile["Make build pipeline<br/>build orchestrator"]
  node_bootstrap["Bootstrap compiler<br/>native executable"]
  node_compiler_sources["Combined compiler sources<br/>generated source bundle<br/>[plantc_all.plant]"]
  node_chloroplast["Chloroplast<br/>native compiler"]
end

subgraph group_compiler["PlantLang compiler"]
  node_compiler_main["Compiler CLI and orchestration<br/>PlantLang module<br/>[main.plant]"]
  node_lexer["Lexer<br/>PlantLang module<br/>[lexer.plant]"]
  node_parser["Parser and diagnostics<br/>PlantLang module<br/>[parser.plant]"]
  node_codegen["C code generator<br/>PlantLang module<br/>[codegen_c.plant]"]
  node_generated_c["Generated C<br/>intermediate artifact"]
end

subgraph group_runtime["Native runtime"]
  node_runtime_c["Runtime implementation<br/>C runtime<br/>[plant_runtime.c]"]
  node_runtime_api["Runtime ABI<br/>C headers<br/>[plant_runtime.h]"]
  node_compat_api["Native integration API<br/>C compatibility header<br/>[plant_compat.h]"]
end

subgraph group_verify["Verification"]
  node_test_suites["Integration test suites<br/>shell test runners"]
  node_examples["Example programs<br/>PlantLang source<br/>[hello.plant]"]
end

node_native_program["Native executable<br/>GCC output"]

node_makefile -->|"starts from"| node_bootstrap
node_bootstrap -->|"compiles"| node_compiler_sources
node_makefile -->|"assembles generations"| node_compiler_sources
node_compiler_sources -->|"generates and links"| node_chloroplast
node_makefile -->|"rebuilds and compares"| node_chloroplast
node_compiler_main -->|"tokenizes input with"| node_lexer
node_compiler_main -->|"parses with"| node_parser
node_compiler_main -->|"emits through"| node_codegen
node_parser -->|"syntax representation"| node_codegen
node_codegen -->|"lowers to"| node_generated_c
node_generated_c -->|"includes ABI"| node_runtime_api
node_generated_c -->|"uses external declarations"| node_compat_api
node_generated_c -->|"GCC compiles"| node_native_program
node_runtime_c -->|"links into"| node_native_program
node_runtime_api -->|"declares"| node_runtime_c
node_compat_api -->|"extends integration boundary"| node_runtime_api
node_chloroplast -->|"compiles .plant programs"| node_generated_c
node_test_suites -->|"exercise"| node_chloroplast
node_test_suites -->|"runs and checks"| node_native_program
node_examples -->|"compile input"| node_chloroplast

click node_makefile "https://github.com/ultimatehaider/plantlang/blob/Safarna/Makefile"
click node_bootstrap "https://github.com/ultimatehaider/plantlang/blob/Safarna/dist/Chloroplast"
click node_compiler_sources "https://github.com/ultimatehaider/plantlang/blob/Safarna/build/plantc_all.plant"
click node_chloroplast "https://github.com/ultimatehaider/plantlang/blob/Safarna/bin/Chloroplast"
click node_compiler_main "https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/main.plant"
click node_lexer "https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/lexer.plant"
click node_parser "https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/parser.plant"
click node_codegen "https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/codegen_c.plant"
click node_runtime_c "https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_runtime.c"
click node_runtime_api "https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_runtime.h"
click node_compat_api "https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_compat.h"
click node_test_suites "https://github.com/ultimatehaider/plantlang/blob/Safarna/tests/regression/run_regression_tests.sh"
click node_examples "https://github.com/ultimatehaider/plantlang/blob/Safarna/examples/hello.plant"

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_makefile,node_bootstrap,node_compiler_sources,node_chloroplast toneBlue
class node_compiler_main,node_lexer,node_parser,node_codegen,node_generated_c toneAmber
class node_runtime_c,node_runtime_api,node_compat_api toneMint
class node_test_suites,node_examples toneRose
class node_native_program toneNeutral
```

## Components

### Self-hosting build

- [Make build pipeline](https://github.com/ultimatehaider/plantlang/blob/Safarna/Makefile): build orchestrator · Bootstraps, rebuilds, and compares compiler generations. · `Makefile`
- [Bootstrap compiler](https://github.com/ultimatehaider/plantlang/blob/Safarna/dist/Chloroplast): native executable · Immutable compiler seed. · `dist/Chloroplast`
- [Combined compiler sources](https://github.com/ultimatehaider/plantlang/blob/Safarna/build/plantc_all.plant): generated source bundle · `build/plantc_all.plant`
- [Chloroplast](https://github.com/ultimatehaider/plantlang/blob/Safarna/bin/Chloroplast): native compiler · User-facing self-hosted compiler executable. · `bin/Chloroplast`

### PlantLang compiler

- [Compiler CLI and orchestration](https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/main.plant): PlantLang module · `src/plantc/main.plant`
- [Lexer](https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/lexer.plant): PlantLang module · `src/plantc/lexer.plant`
- [Parser and diagnostics](https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/parser.plant): PlantLang module · Builds syntax representation and reports source parse failures. · `src/plantc/parser.plant`
- [C code generator](https://github.com/ultimatehaider/plantlang/blob/Safarna/src/plantc/codegen_c.plant): PlantLang module · Lowers language semantics into standalone C. · `src/plantc/codegen_c.plant`
- **Generated C**: intermediate artifact · Platform compilation boundary for PlantLang programs.

### Native runtime

- [Runtime implementation](https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_runtime.c): C runtime · Provides allocation, exceptions, async, values, and native services. · `runtime/c/plant_runtime.c`
- [Runtime ABI](https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_runtime.h): C headers · ABI, type, and compatibility contracts used by generated C. · `runtime/c/plant_runtime.h`
- [Native integration API](https://github.com/ultimatehaider/plantlang/blob/Safarna/runtime/c/plant_compat.h): C compatibility header · Supports declared C externals and native capability calls. · `runtime/c/plant_compat.h`

### Verification

- [Integration test suites](https://github.com/ultimatehaider/plantlang/blob/Safarna/tests/regression/run_regression_tests.sh): shell test runners · Compile and run language and native-runtime coverage. · `tests/regression/run_regression_tests.sh`
- [Example programs](https://github.com/ultimatehaider/plantlang/blob/Safarna/examples/hello.plant): PlantLang source · `examples/hello.plant`

### Other components

- **Native executable**: GCC output · Generated C linked with the runtime and libm.

## Connections

- Make build pipeline → Bootstrap compiler: starts from
- Bootstrap compiler → Combined compiler sources: compiles
- Make build pipeline → Combined compiler sources: assembles generations
- Combined compiler sources → Chloroplast: generates and links
- Make build pipeline → Chloroplast: rebuilds and compares
- Compiler CLI and orchestration → Lexer: tokenizes input with
- Compiler CLI and orchestration → Parser and diagnostics: parses with
- Compiler CLI and orchestration → C code generator: emits through
- Parser and diagnostics → C code generator: syntax representation
- C code generator → Generated C: lowers to
- Generated C → Runtime ABI: includes ABI
- Generated C → Native integration API: uses external declarations
- Generated C → Native executable: GCC compiles
- Runtime implementation → Native executable: links into
- Runtime ABI → Runtime implementation: declares
- Native integration API → Runtime ABI: extends integration boundary
- Chloroplast → Generated C: compiles .plant programs
- Integration test suites → Chloroplast: exercise
- Integration test suites → Native executable: runs and checks
- Example programs → Chloroplast: compile input