# lamina-dev/lamina architecture

> Architecture diagram of the GitHub repository lamina-dev/lamina, 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/lamina-dev/lamina
- Repository: https://github.com/lamina-dev/lamina

## Overview

Lamina is a statically typed, expression-oriented mathematical language with a compiler front end, register-based virtual machine, mathematical bridge, and C ABI. Its main workflow takes source text through lexing, parsing, type checking, MIR generation, and bytecode assembly before VM execution. The README documents that pipeline and the mathematical standard-library capabilities; sampled excerpts also show VM instruction handling and sparse-matrix bridge operations. Some mathematical subsystems are represented by their exact enclosing directories because their implementation files were not sampled.

Main entry points: [`bridge/conversions.hpp`](https://github.com/lamina-dev/lamina/blob/master/bridge/conversions.hpp) (Math bridge), [`runtime/vm.cpp`](https://github.com/lamina-dev/lamina/blob/master/runtime/vm.cpp) (Virtual machine), [`lmx.cpp`](https://github.com/lamina-dev/lamina/blob/master/lmx.cpp) (C ABI), [`compiler/compiler.hpp`](https://github.com/lamina-dev/lamina/blob/master/compiler/compiler.hpp) (Compiler pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Compiler frontend"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_ast["AST and types<br/>[ast.hpp]"]
  node_checker["Type checker<br/>[type_checker.cpp]"]
  node_mir["MIR builder<br/>[mir_builder.cpp]"]
  node_assembler["Assembler<br/>[assembler.cpp]"]
  node_compiler["Compiler pipeline<br/>[compiler.hpp]"]
end

subgraph group_backend["Bytecode runtime"]
  node_bytecode["Code modules<br/>[code_module.cpp]"]
  node_vm["Virtual machine<br/>[vm.cpp]"]
  node_values["Runtime values<br/>[value.hpp]"]
  node_objects["Runtime objects<br/>[object.hpp]"]
  node_strings["Strings<br/>[StringObj.hpp]"]
  node_arrays["Arrays<br/>[array.hpp]"]
  node_adt["Algebraic data<br/>[adt.hpp]"]
  node_fractions["Fractions<br/>[fraction.hpp]"]
  node_expressions["Expr values<br/>[expr_obj.hpp]"]
  node_matrices["Matrices<br/>[matrix.hpp]"]
end

subgraph group_math["Math capabilities"]
  node_bridge["Math bridge<br/>[conversions.hpp]"]
  node_results["Math results<br/>[result.hpp]"]
  node_cas["Symbolic CAS"]
  node_linear["Linear algebra"]
  node_stats["Statistics<br/>[stats.cpp]"]
  node_random["Random numbers<br/>[random_numbers.cpp]"]
  node_units["Units<br/>[units.cpp]"]
  node_sparse["Sparse matrices"]
end

subgraph group_interop["Interfaces and values"]
  node_cli["CLI<br/>[main.cpp]"]
  node_cabi["C ABI<br/>[lmx.cpp]"]
  node_headers["Public C headers<br/>[lmx.h]"]
end

node_user(("Language user"))

node_user -->|"runs source"| node_cli
node_cli -->|"starts compilation"| node_compiler
node_cabi -->|"compiles source"| node_compiler
node_compiler -->|"lexes"| node_lexer
node_lexer -->|"produces tokens"| node_parser
node_parser -->|"builds AST"| node_ast
node_ast -->|"checks types"| node_checker
node_checker -->|"builds HIR"| node_mir
node_mir -->|"lowers MIR"| node_assembler
node_assembler -->|"assembles bytecode"| node_bytecode
node_bytecode -->|"runs module"| node_vm
node_cabi -->|"runs module"| node_vm
node_vm -->|"executes with"| node_values
node_values -->|"holds references"| node_objects
node_vm -->|"constructs and matches"| node_adt
node_vm -->|"executes container operations"| node_arrays
node_vm -->|"uses arithmetic"| node_fractions
node_vm -.->|"calls math bindings"| node_bridge
node_bridge -->|"converts results"| node_results
node_bridge -->|"converts expressions"| node_expressions
node_bridge -->|"converts matrices"| node_matrices
node_bridge -->|"exposes symbolic APIs"| node_cas
node_bridge -->|"exposes linear algebra"| node_linear
node_bridge -->|"exposes statistics"| node_stats
node_bridge -->|"exposes random APIs"| node_random
node_bridge -->|"exposes unit APIs"| node_units
node_bridge -->|"implements sparse operations"| node_sparse
node_cabi -->|"implements public ABI"| node_headers

click node_lexer "https://github.com/lamina-dev/lamina/blob/master/compiler/lexer.cpp"
click node_parser "https://github.com/lamina-dev/lamina/blob/master/compiler/parser.cpp"
click node_ast "https://github.com/lamina-dev/lamina/blob/master/compiler/ast/ast.hpp"
click node_checker "https://github.com/lamina-dev/lamina/blob/master/compiler/hir/type_checker.cpp"
click node_mir "https://github.com/lamina-dev/lamina/blob/master/compiler/mir/mir_builder.cpp"
click node_assembler "https://github.com/lamina-dev/lamina/blob/master/compiler/assembler.cpp"
click node_compiler "https://github.com/lamina-dev/lamina/blob/master/compiler/compiler.hpp"
click node_cli "https://github.com/lamina-dev/lamina/blob/master/main.cpp"
click node_cabi "https://github.com/lamina-dev/lamina/blob/master/lmx.cpp"
click node_headers "https://github.com/lamina-dev/lamina/blob/master/include/lmx.h"
click node_bytecode "https://github.com/lamina-dev/lamina/blob/master/runtime/object/code_module.cpp"
click node_vm "https://github.com/lamina-dev/lamina/blob/master/runtime/vm.cpp"
click node_values "https://github.com/lamina-dev/lamina/blob/master/runtime/object/value.hpp"
click node_objects "https://github.com/lamina-dev/lamina/blob/master/runtime/object/object.hpp"
click node_strings "https://github.com/lamina-dev/lamina/blob/master/runtime/object/StringObj.hpp"
click node_arrays "https://github.com/lamina-dev/lamina/blob/master/runtime/object/array.hpp"
click node_adt "https://github.com/lamina-dev/lamina/blob/master/runtime/object/adt.hpp"
click node_fractions "https://github.com/lamina-dev/lamina/blob/master/runtime/object/fraction.hpp"
click node_expressions "https://github.com/lamina-dev/lamina/blob/master/runtime/object/expr_obj.hpp"
click node_matrices "https://github.com/lamina-dev/lamina/blob/master/runtime/object/matrix.hpp"
click node_bridge "https://github.com/lamina-dev/lamina/blob/master/bridge/conversions.hpp"
click node_results "https://github.com/lamina-dev/lamina/blob/master/bridge/result.hpp"
click node_cas "https://github.com/lamina-dev/lamina/tree/master/bridge/cas"
click node_linear "https://github.com/lamina-dev/lamina/tree/master/bridge"
click node_stats "https://github.com/lamina-dev/lamina/blob/master/bridge/stats.cpp"
click node_random "https://github.com/lamina-dev/lamina/blob/master/bridge/random_numbers.cpp"
click node_units "https://github.com/lamina-dev/lamina/blob/master/bridge/units.cpp"
click node_sparse "https://github.com/lamina-dev/lamina/blob/master/bridge/sparse_linear_algebra_storage.cpp"

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_lexer,node_parser,node_ast,node_checker,node_mir,node_assembler,node_compiler,node_user toneBlue
class node_bytecode,node_vm,node_values,node_objects,node_strings,node_arrays,node_adt,node_fractions,node_expressions,node_matrices toneAmber
class node_bridge,node_results,node_cas,node_linear,node_stats,node_random,node_units,node_sparse toneMint
class node_cli,node_cabi,node_headers toneRose
```

## Components

### Compiler frontend

- [Lexer](https://github.com/lamina-dev/lamina/blob/master/compiler/lexer.cpp): `compiler/lexer.cpp`
- [Parser](https://github.com/lamina-dev/lamina/blob/master/compiler/parser.cpp): `compiler/parser.cpp`
- [AST and types](https://github.com/lamina-dev/lamina/blob/master/compiler/ast/ast.hpp): `compiler/ast/ast.hpp`
- [Type checker](https://github.com/lamina-dev/lamina/blob/master/compiler/hir/type_checker.cpp): `compiler/hir/type_checker.cpp`
- [MIR builder](https://github.com/lamina-dev/lamina/blob/master/compiler/mir/mir_builder.cpp): `compiler/mir/mir_builder.cpp`
- [Assembler](https://github.com/lamina-dev/lamina/blob/master/compiler/assembler.cpp): `compiler/assembler.cpp`
- [Compiler pipeline](https://github.com/lamina-dev/lamina/blob/master/compiler/compiler.hpp): `compiler/compiler.hpp`

### Bytecode runtime

- [Code modules](https://github.com/lamina-dev/lamina/blob/master/runtime/object/code_module.cpp): `runtime/object/code_module.cpp`
- [Virtual machine](https://github.com/lamina-dev/lamina/blob/master/runtime/vm.cpp): `runtime/vm.cpp`
- [Runtime values](https://github.com/lamina-dev/lamina/blob/master/runtime/object/value.hpp): `runtime/object/value.hpp`
- [Runtime objects](https://github.com/lamina-dev/lamina/blob/master/runtime/object/object.hpp): `runtime/object/object.hpp`
- [Strings](https://github.com/lamina-dev/lamina/blob/master/runtime/object/StringObj.hpp): `runtime/object/StringObj.hpp`
- [Arrays](https://github.com/lamina-dev/lamina/blob/master/runtime/object/array.hpp): `runtime/object/array.hpp`
- [Algebraic data](https://github.com/lamina-dev/lamina/blob/master/runtime/object/adt.hpp): `runtime/object/adt.hpp`
- [Fractions](https://github.com/lamina-dev/lamina/blob/master/runtime/object/fraction.hpp): `runtime/object/fraction.hpp`
- [Expr values](https://github.com/lamina-dev/lamina/blob/master/runtime/object/expr_obj.hpp): `runtime/object/expr_obj.hpp`
- [Matrices](https://github.com/lamina-dev/lamina/blob/master/runtime/object/matrix.hpp): `runtime/object/matrix.hpp`

### Math capabilities

- [Math bridge](https://github.com/lamina-dev/lamina/blob/master/bridge/conversions.hpp): `bridge/conversions.hpp`
- [Math results](https://github.com/lamina-dev/lamina/blob/master/bridge/result.hpp): `bridge/result.hpp`
- [Symbolic CAS](https://github.com/lamina-dev/lamina/tree/master/bridge/cas): `bridge/cas`
- [Linear algebra](https://github.com/lamina-dev/lamina/tree/master/bridge): `bridge`
- [Statistics](https://github.com/lamina-dev/lamina/blob/master/bridge/stats.cpp): `bridge/stats.cpp`
- [Random numbers](https://github.com/lamina-dev/lamina/blob/master/bridge/random_numbers.cpp): `bridge/random_numbers.cpp`
- [Units](https://github.com/lamina-dev/lamina/blob/master/bridge/units.cpp): `bridge/units.cpp`
- [Sparse matrices](https://github.com/lamina-dev/lamina/blob/master/bridge/sparse_linear_algebra_storage.cpp): `bridge/sparse_linear_algebra_storage.cpp`

### Interfaces and values

- [CLI](https://github.com/lamina-dev/lamina/blob/master/main.cpp): `main.cpp`
- [C ABI](https://github.com/lamina-dev/lamina/blob/master/lmx.cpp): `lmx.cpp`
- [Public C headers](https://github.com/lamina-dev/lamina/blob/master/include/lmx.h): `include/lmx.h`

### Other components

- **Language user**

## Connections

- Language user → CLI: runs source
- CLI → Compiler pipeline: starts compilation
- C ABI → Compiler pipeline: compiles source (evidence: `lmx.cpp`)
- Compiler pipeline → Lexer: lexes
- Lexer → Parser: produces tokens
- Parser → AST and types: builds AST
- AST and types → Type checker: checks types
- Type checker → MIR builder: builds HIR
- MIR builder → Assembler: lowers MIR
- Assembler → Code modules: assembles bytecode
- Code modules → Virtual machine: runs module
- C ABI → Virtual machine: runs module
- Virtual machine → Runtime values: executes with (evidence: `runtime/vm.cpp`)
- Runtime values → Runtime objects: holds references (evidence: `runtime/object/value.hpp`)
- Virtual machine → Algebraic data: constructs and matches (evidence: `runtime/vm.cpp`)
- Virtual machine → Arrays: executes container operations (evidence: `runtime/vm.cpp`)
- Virtual machine → Fractions: uses arithmetic (evidence: `runtime/vm.cpp`)
- Virtual machine → Math bridge: calls math bindings
- Math bridge → Math results: converts results (evidence: `bridge/result.hpp`)
- Math bridge → Expr values: converts expressions (evidence: `bridge/conversions.hpp`)
- Math bridge → Matrices: converts matrices (evidence: `bridge/conversions.hpp`)
- Math bridge → Symbolic CAS: exposes symbolic APIs (evidence: `bridge/cas/expr.cpp`)
- Math bridge → Linear algebra: exposes linear algebra (evidence: `bridge/conversions.hpp`)
- Math bridge → Statistics: exposes statistics
- Math bridge → Random numbers: exposes random APIs
- Math bridge → Units: exposes unit APIs
- Math bridge → Sparse matrices: implements sparse operations (evidence: `bridge/sparse_linear_algebra_storage.cpp`)
- C ABI → Public C headers: implements public ABI (evidence: `lmx.cpp`)
