# marcobambini/gravity architecture

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

## Overview

Gravity is an embeddable, dynamically typed scripting language. A user supplies source to the CLI or a host application; the compiler parses and transforms it into a closure/bytecode, and the VM executes it and exposes a result. The graph also preserves the documented optional modules and runtime capabilities. Source-index references and README workflows support the principal connections; unsampled implementation details are not asserted.

Main entry points: [`src/runtime/gravity_vm.c`](https://github.com/marcobambini/gravity/blob/master/src/runtime/gravity_vm.c) (Virtual machine), [`src/optionals`](https://github.com/marcobambini/gravity/tree/master/src/optionals) (Optional modules), [`src/cli/gravity.c`](https://github.com/marcobambini/gravity/blob/master/src/cli/gravity.c) (Gravity CLI), [`api/exec_c.c`](https://github.com/marcobambini/gravity/blob/master/api/exec_c.c) (Embedding API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Entry points"]
  node_cli["Gravity CLI<br/>[gravity.c]"]
  node_embed["Embedding API<br/>[exec_c.c]"]
end

subgraph group_compile["Compilation"]
  node_lexer["Lexer<br/>[gravity_lexer.c]"]
  node_parser["Parser and AST<br/>[gravity_parser.c]"]
  node_semantic["Semantic analysis"]
  node_optimizer["Optimizer"]
  node_codegen["Code generation<br/>[gravity_codegen.c]"]
  node_compiler["Compiler API<br/>[gravity_compiler.h]"]
end

subgraph group_execute["Runtime"]
  node_vm["Virtual machine<br/>[gravity_vm.c]"]
  node_core["Core classes<br/>[gravity_core.c]"]
end

subgraph group_foundation["Runtime foundation"]
  node_values["Values and objects<br/>[gravity_value.c]"]
  node_memory["Memory and GC<br/>[gravity_memory.c]"]
  node_hash["Hash tables<br/>[gravity_hash.c]"]
  node_json["JSON support<br/>[gravity_json.c]"]
  node_utils["I/O and utilities<br/>[gravity_utils.c]"]
end

subgraph group_extensions["Optional modules"]
  node_optionals["Optional modules"]
  node_math["Math module<br/>[gravity_opt_math.c]"]
  node_file["File module<br/>[gravity_opt_file.c]"]
  node_jsonmod["JSON module<br/>[gravity_opt_json.c]"]
  node_env["Environment module<br/>[gravity_opt_env.c]"]
end

node_user(("Script author"))
node_host(("Embedding host"))

node_user -->|"runs script"| node_cli
node_host -->|"embeds language"| node_embed
node_cli -->|"compiles source"| node_compiler
node_cli -->|"executes bytecode"| node_vm
node_embed -->|"compiles source"| node_compiler
node_embed -->|"runs closure"| node_vm
node_compiler -.->|"compiles source"| node_parser
node_parser -->|"requests tokens"| node_lexer
node_parser -.->|"checks AST"| node_semantic
node_semantic -.->|"validates before optimization"| node_optimizer
node_optimizer -.->|"optimizes for codegen"| node_codegen
node_codegen -.->|"produces bytecode"| node_vm
node_vm -->|"uses core classes"| node_core
node_vm -->|"loads optional modules"| node_optionals
node_optionals -->|"exposes module"| node_math
node_optionals -->|"exposes module"| node_file
node_optionals -->|"exposes module"| node_jsonmod
node_optionals -->|"exposes module"| node_env
node_vm -->|"executes values"| node_values
node_vm -->|"uses allocation and GC"| node_memory
node_core -->|"defines built-in types"| node_values
node_core -->|"uses hash tables"| node_hash
node_jsonmod -->|"uses serializer"| node_json
node_file -->|"uses file utilities"| node_utils

click node_cli "https://github.com/marcobambini/gravity/blob/master/src/cli/gravity.c"
click node_embed "https://github.com/marcobambini/gravity/blob/master/api/exec_c.c"
click node_lexer "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_lexer.c"
click node_parser "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_parser.c"
click node_semantic "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_semacheck2.c"
click node_optimizer "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_optimizer.c"
click node_codegen "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_codegen.c"
click node_compiler "https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_compiler.h"
click node_vm "https://github.com/marcobambini/gravity/blob/master/src/runtime/gravity_vm.c"
click node_core "https://github.com/marcobambini/gravity/blob/master/src/runtime/gravity_core.c"
click node_values "https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_value.c"
click node_memory "https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_memory.c"
click node_hash "https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_hash.c"
click node_json "https://github.com/marcobambini/gravity/blob/master/src/utils/gravity_json.c"
click node_utils "https://github.com/marcobambini/gravity/blob/master/src/utils/gravity_utils.c"
click node_optionals "https://github.com/marcobambini/gravity/tree/master/src/optionals"
click node_math "https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_math.c"
click node_file "https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_file.c"
click node_jsonmod "https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_json.c"
click node_env "https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_env.c"

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,node_embed toneBlue
class node_lexer,node_parser,node_semantic,node_optimizer,node_codegen,node_compiler toneAmber
class node_vm,node_core toneMint
class node_values,node_memory,node_hash,node_json,node_utils toneRose
class node_optionals,node_math,node_file,node_jsonmod,node_env,node_user,node_host toneIndigo
```

## Components

### Entry points

- [Gravity CLI](https://github.com/marcobambini/gravity/blob/master/src/cli/gravity.c): `src/cli/gravity.c`
- [Embedding API](https://github.com/marcobambini/gravity/blob/master/api/exec_c.c): `api/exec_c.c`

### Compilation

- [Lexer](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_lexer.c): `src/compiler/gravity_lexer.c`
- [Parser and AST](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_parser.c): `src/compiler/gravity_parser.c`
- [Semantic analysis](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_semacheck2.c): `src/compiler/gravity_semacheck2.c`
- [Optimizer](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_optimizer.c): `src/compiler/gravity_optimizer.c`
- [Code generation](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_codegen.c): `src/compiler/gravity_codegen.c`
- [Compiler API](https://github.com/marcobambini/gravity/blob/master/src/compiler/gravity_compiler.h): `src/compiler/gravity_compiler.h`

### Runtime

- [Virtual machine](https://github.com/marcobambini/gravity/blob/master/src/runtime/gravity_vm.c): `src/runtime/gravity_vm.c`
- [Core classes](https://github.com/marcobambini/gravity/blob/master/src/runtime/gravity_core.c): `src/runtime/gravity_core.c`

### Runtime foundation

- [Values and objects](https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_value.c): `src/shared/gravity_value.c`
- [Memory and GC](https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_memory.c): `src/shared/gravity_memory.c`
- [Hash tables](https://github.com/marcobambini/gravity/blob/master/src/shared/gravity_hash.c): `src/shared/gravity_hash.c`
- [JSON support](https://github.com/marcobambini/gravity/blob/master/src/utils/gravity_json.c): `src/utils/gravity_json.c`
- [I/O and utilities](https://github.com/marcobambini/gravity/blob/master/src/utils/gravity_utils.c): `src/utils/gravity_utils.c`

### Optional modules

- [Optional modules](https://github.com/marcobambini/gravity/tree/master/src/optionals): `src/optionals`
- [Math module](https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_math.c): `src/optionals/gravity_opt_math.c`
- [File module](https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_file.c): `src/optionals/gravity_opt_file.c`
- [JSON module](https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_json.c): `src/optionals/gravity_opt_json.c`
- [Environment module](https://github.com/marcobambini/gravity/blob/master/src/optionals/gravity_opt_env.c): `src/optionals/gravity_opt_env.c`

### Other components

- **Script author**
- **Embedding host**

## Connections

- Script author → Gravity CLI: runs script
- Embedding host → Embedding API: embeds language
- Gravity CLI → Compiler API: compiles source (evidence: `src/cli/gravity.c`)
- Gravity CLI → Virtual machine: executes bytecode (evidence: `src/cli/gravity.c`)
- Embedding API → Compiler API: compiles source (evidence: `api/exec_c.c`)
- Embedding API → Virtual machine: runs closure (evidence: `api/exec_c.c`)
- Compiler API → Parser and AST: compiles source
- Parser and AST → Lexer: requests tokens (evidence: `src/compiler/gravity_parser.c`)
- Parser and AST → Semantic analysis: checks AST
- Semantic analysis → Optimizer: validates before optimization
- Optimizer → Code generation: optimizes for codegen
- Code generation → Virtual machine: produces bytecode
- Virtual machine → Core classes: uses core classes (evidence: `src/runtime/gravity_vm.c`)
- Virtual machine → Optional modules: loads optional modules (evidence: `src/runtime/gravity_vm.c`)
- Optional modules → Math module: exposes module (evidence: `src/optionals/gravity_optionals.h`)
- Optional modules → File module: exposes module (evidence: `src/optionals/gravity_optionals.h`)
- Optional modules → JSON module: exposes module (evidence: `src/optionals/gravity_optionals.h`)
- Optional modules → Environment module: exposes module (evidence: `src/optionals/gravity_optionals.h`)
- Virtual machine → Values and objects: executes values (evidence: `src/runtime/gravity_vm.c`)
- Virtual machine → Memory and GC: uses allocation and GC (evidence: `src/runtime/gravity_vm.c`)
- Core classes → Values and objects: defines built-in types (evidence: `src/runtime/gravity_core.c`)
- Core classes → Hash tables: uses hash tables (evidence: `src/runtime/gravity_core.c`)
- JSON module → JSON support: uses serializer (evidence: `src/optionals/gravity_opt_json.c`)
- File module → I/O and utilities: uses file utilities (evidence: `src/optionals/gravity_opt_file.c`)
