# project-terra-lang/terra architecture

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

- Interactive diagram: https://gitdiagram.com/project-terra-lang/terra
- Repository: https://github.com/project-terra-lang/terra

## Overview

Terra is a small language compiler and runtime: users write Terra programs, which are transpiled to Erlang and executed on the BEAM. The documented language surface includes module imports/exports, checked Erlang FFI, process primitives, and a small standard library. The README establishes these capabilities and relationships, but no source excerpts were provided, so internal call flow and the exact compiler entry point are left unspecified.

Main entry points: [`src/transpiler.erl`](https://github.com/project-terra-lang/terra/blob/main/src/transpiler.erl) (Erlang FFI), [`src/program.erl`](https://github.com/project-terra-lang/terra/blob/main/src/program.erl) (Module Imports), [`std/std_collection.terra`](https://github.com/project-terra-lang/terra/blob/main/std/std_collection.terra) (Collections), [`std/std_string.terra`](https://github.com/project-terra-lang/terra/blob/main/std/std_string.terra) (Strings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler"]
  node_tokenizer["Tokenizer<br/>[tokenizer.erl]"]
  node_transpiler["Transpiler<br/>[transpiler.erl]"]
  node_program["Program Handling<br/>[program.erl]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.erl]"]
end

subgraph group_language["Language Features"]
  node_language_core["Core Language<br/>[datatypes.erl]"]
  node_variables["Variables<br/>[variables.erl]"]
  node_module_imports["Module Imports<br/>[program.erl]"]
  node_ffi["Erlang FFI<br/>[transpiler.erl]"]
end

subgraph group_stdlib["Standard Library"]
  node_std_collection["Collections"]
  node_std_string["Strings<br/>[std_string.terra]"]
  node_std_binary["Binary<br/>[std_binary.terra]"]
  node_std_fs["Filesystem<br/>[std_fs.terra]"]
  node_std_random["Random<br/>[std_random.terra]"]
  node_std_time["Time<br/>[std_time.terra]"]
  node_std_test["Assertions<br/>[std_test.terra]"]
end

subgraph group_runtime["BEAM Runtime"]
  node_erlang["Erlang Functions"]
  node_beam["BEAM Runtime"]
  node_launcher["Generated Launcher"]
end

node_author(("Terra Author"))
node_terra_program["Terra Program"]

node_author -->|"writes"| node_terra_program
node_terra_program -->|"transpiles"| node_transpiler
node_transpiler -->|"emits Erlang"| node_beam
node_beam -->|"runs program"| node_launcher
node_launcher -->|"invokes Main"| node_terra_program
node_terra_program -->|"imports modules"| node_module_imports
node_module_imports -->|"resolves std_ imports"| node_std_collection
node_terra_program -->|"declares externs"| node_ffi
node_ffi -->|"calls declared functions"| node_erlang
node_std_collection -.->|"uses checked wrappers"| node_ffi
node_std_string -.->|"uses checked wrappers"| node_ffi
node_std_binary -.->|"uses checked wrappers"| node_ffi
node_std_fs -.->|"uses checked wrappers"| node_ffi
node_std_random -.->|"uses checked wrappers"| node_ffi
node_std_time -.->|"uses checked wrappers"| node_ffi

click node_tokenizer "https://github.com/project-terra-lang/terra/blob/main/src/tokenizer.erl"
click node_transpiler "https://github.com/project-terra-lang/terra/blob/main/src/transpiler.erl"
click node_program "https://github.com/project-terra-lang/terra/blob/main/src/program.erl"
click node_diagnostics "https://github.com/project-terra-lang/terra/blob/main/src/diagnostics.erl"
click node_language_core "https://github.com/project-terra-lang/terra/blob/main/src/datatypes.erl"
click node_variables "https://github.com/project-terra-lang/terra/blob/main/src/variables.erl"
click node_module_imports "https://github.com/project-terra-lang/terra/blob/main/src/program.erl"
click node_ffi "https://github.com/project-terra-lang/terra/blob/main/src/transpiler.erl"
click node_std_collection "https://github.com/project-terra-lang/terra/blob/main/std/std_collection.terra"
click node_std_string "https://github.com/project-terra-lang/terra/blob/main/std/std_string.terra"
click node_std_binary "https://github.com/project-terra-lang/terra/blob/main/std/std_binary.terra"
click node_std_fs "https://github.com/project-terra-lang/terra/blob/main/std/std_fs.terra"
click node_std_random "https://github.com/project-terra-lang/terra/blob/main/std/std_random.terra"
click node_std_time "https://github.com/project-terra-lang/terra/blob/main/std/std_time.terra"
click node_std_test "https://github.com/project-terra-lang/terra/blob/main/std/std_test.terra"

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_tokenizer,node_transpiler,node_program,node_diagnostics toneBlue
class node_language_core,node_variables,node_module_imports,node_ffi toneAmber
class node_std_collection,node_std_string,node_std_binary,node_std_fs,node_std_random,node_std_time,node_std_test toneMint
class node_erlang,node_beam,node_launcher toneRose
class node_author,node_terra_program toneIndigo
```

## Components

### Compiler

- [Tokenizer](https://github.com/project-terra-lang/terra/blob/main/src/tokenizer.erl): `src/tokenizer.erl`
- [Transpiler](https://github.com/project-terra-lang/terra/blob/main/src/transpiler.erl): `src/transpiler.erl`
- [Program Handling](https://github.com/project-terra-lang/terra/blob/main/src/program.erl): `src/program.erl`
- [Diagnostics](https://github.com/project-terra-lang/terra/blob/main/src/diagnostics.erl): `src/diagnostics.erl`

### Language Features

- [Core Language](https://github.com/project-terra-lang/terra/blob/main/src/datatypes.erl): `src/datatypes.erl`
- [Variables](https://github.com/project-terra-lang/terra/blob/main/src/variables.erl): `src/variables.erl`
- [Module Imports](https://github.com/project-terra-lang/terra/blob/main/src/program.erl): `src/program.erl`
- [Erlang FFI](https://github.com/project-terra-lang/terra/blob/main/src/transpiler.erl): `src/transpiler.erl`

### Standard Library

- [Collections](https://github.com/project-terra-lang/terra/blob/main/std/std_collection.terra): `std/std_collection.terra`
- [Strings](https://github.com/project-terra-lang/terra/blob/main/std/std_string.terra): `std/std_string.terra`
- [Binary](https://github.com/project-terra-lang/terra/blob/main/std/std_binary.terra): `std/std_binary.terra`
- [Filesystem](https://github.com/project-terra-lang/terra/blob/main/std/std_fs.terra): `std/std_fs.terra`
- [Random](https://github.com/project-terra-lang/terra/blob/main/std/std_random.terra): `std/std_random.terra`
- [Time](https://github.com/project-terra-lang/terra/blob/main/std/std_time.terra): `std/std_time.terra`
- [Assertions](https://github.com/project-terra-lang/terra/blob/main/std/std_test.terra): `std/std_test.terra`

### BEAM Runtime

- **Erlang Functions**
- **BEAM Runtime**
- **Generated Launcher**

### Other components

- **Terra Author**
- **Terra Program**

## Connections

- Terra Author → Terra Program: writes (evidence: `README.md`)
- Terra Program → Transpiler: transpiles (evidence: `README.md`)
- Transpiler → BEAM Runtime: emits Erlang (evidence: `README.md`)
- BEAM Runtime → Generated Launcher: runs program (evidence: `README.md`)
- Generated Launcher → Terra Program: invokes Main (evidence: `README.md`)
- Terra Program → Module Imports: imports modules (evidence: `README.md`)
- Module Imports → Collections: resolves std_ imports (evidence: `README.md`)
- Terra Program → Erlang FFI: declares externs (evidence: `README.md`)
- Erlang FFI → Erlang Functions: calls declared functions (evidence: `README.md`)
- Collections → Erlang FFI: uses checked wrappers (evidence: `README.md`)
- Strings → Erlang FFI: uses checked wrappers (evidence: `README.md`)
- Binary → Erlang FFI: uses checked wrappers (evidence: `README.md`)
- Filesystem → Erlang FFI: uses checked wrappers (evidence: `README.md`)
- Random → Erlang FFI: uses checked wrappers (evidence: `README.md`)
- Time → Erlang FFI: uses checked wrappers (evidence: `README.md`)
