# matz/spinel architecture

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

- Interactive diagram: https://gitdiagram.com/matz/spinel
- Repository: https://github.com/matz/spinel

## Overview

Spinel turns Ruby source into a standalone native executable: it parses the program, builds an in-memory AST model, infers types, generates C, then compiles and links that C with the runtime. The `spin` project tool adds project scaffolding, dependency management, and build/run/test workflows around the compiler. The README documents the main pipeline; source excerpts and the index support the compiler entry point and runtime/package boundaries. Some implementation details are unsampled, so uncertain internal calls are omitted.

Main entry points: [`src/main.c`](https://github.com/matz/spinel/blob/master/src/main.c) (spinel Compiler), [`tools/spin.rb`](https://github.com/matz/spinel/blob/master/tools/spin.rb) (spin CLI), [`lib/spinel/runtime.h`](https://github.com/matz/spinel/blob/master/lib/spinel/runtime.h) (Spinel Runtime), [`src/node_table.h`](https://github.com/matz/spinel/blob/master/src/node_table.h) (Node Table)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compiler["Compiler"]
  node_compiler_cli["spinel Compiler<br/>[main.c]"]
  node_prism["Prism Parser"]
  node_ast[("Node Table<br/>[node_table.h]")]
  node_analysis["Type Analysis<br/>[analyze_infer.c]"]
  node_rbs["RBS Extraction"]
  node_codegen["C Generation<br/>[codegen_expr.c]"]
end

subgraph group_project["Project Tool"]
  node_spin["spin CLI<br/>[spin.rb]"]
  node_output["Project Build Output"]
end

subgraph group_runtime["Runtime"]
  node_runtime["Spinel Runtime<br/>[runtime.h]"]
  node_runtime_helpers["Runtime Helpers<br/>[sp_cold.c]"]
  node_regexp["Regexp Engine<br/>[re_compile.c]"]
end

subgraph group_packages["Packages"]
  node_package_sources["Package Sources"]
  node_json["JSON Package<br/>[sp_json.c]"]
  node_openssl["OpenSSL Package<br/>[sp_openssl.c]"]
end

node_developer(("Ruby Developer"))
node_ruby["Ruby Source"]
node_c_source["Generated C"]
node_cc["System C Compiler"]
node_native["Native Executable"]

node_developer -->|"uses"| node_spin
node_developer -->|"invokes"| node_compiler_cli
node_ruby -->|"compiles"| node_compiler_cli
node_spin -->|"drives"| node_compiler_cli
node_compiler_cli -->|"parses with"| node_prism
node_prism -->|"produces AST"| node_ast
node_compiler_cli -->|"loads AST"| node_ast
node_ast -->|"analyzes"| node_analysis
node_rbs -.->|"seeds types"| node_analysis
node_analysis -->|"shares inferred types"| node_codegen
node_codegen -->|"emits C"| node_c_source
node_compiler_cli -->|"invokes"| node_cc
node_cc -->|"compiles and links"| node_native
node_cc -->|"links"| node_runtime
node_package_sources -->|"compiled into"| node_native
node_json -->|"uses ABI"| node_runtime
node_openssl -->|"uses ABI"| node_runtime
node_runtime_helpers -.->|"implements helpers"| node_runtime
node_spin -->|"builds projects"| node_output
node_spin -->|"resolves dependencies"| node_package_sources

click node_spin "https://github.com/matz/spinel/blob/master/tools/spin.rb"
click node_compiler_cli "https://github.com/matz/spinel/blob/master/src/main.c"
click node_ast "https://github.com/matz/spinel/blob/master/src/node_table.h"
click node_analysis "https://github.com/matz/spinel/blob/master/src/analyze_infer.c"
click node_rbs "https://github.com/matz/spinel/blob/master/tools/spinel_rbs_extract.c"
click node_codegen "https://github.com/matz/spinel/blob/master/src/codegen_expr.c"
click node_runtime "https://github.com/matz/spinel/blob/master/lib/spinel/runtime.h"
click node_runtime_helpers "https://github.com/matz/spinel/blob/master/lib/sp_cold.c"
click node_regexp "https://github.com/matz/spinel/blob/master/lib/regexp/re_compile.c"
click node_package_sources "https://github.com/matz/spinel/tree/master/packages"
click node_json "https://github.com/matz/spinel/blob/master/packages/json/sp_json.c"
click node_openssl "https://github.com/matz/spinel/blob/master/packages/openssl/sp_openssl.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_compiler_cli,node_prism,node_ast,node_analysis,node_rbs,node_codegen toneBlue
class node_spin,node_output toneAmber
class node_runtime,node_runtime_helpers,node_regexp toneMint
class node_package_sources,node_json,node_openssl toneRose
class node_developer,node_ruby,node_c_source,node_cc,node_native toneIndigo
```

## Components

### Compiler

- [spinel Compiler](https://github.com/matz/spinel/blob/master/src/main.c): `src/main.c`
- **Prism Parser**
- [Node Table](https://github.com/matz/spinel/blob/master/src/node_table.h): `src/node_table.h`
- [Type Analysis](https://github.com/matz/spinel/blob/master/src/analyze_infer.c): `src/analyze_infer.c`
- [RBS Extraction](https://github.com/matz/spinel/blob/master/tools/spinel_rbs_extract.c): `tools/spinel_rbs_extract.c`
- [C Generation](https://github.com/matz/spinel/blob/master/src/codegen_expr.c): `src/codegen_expr.c`

### Project Tool

- [spin CLI](https://github.com/matz/spinel/blob/master/tools/spin.rb): `tools/spin.rb`
- **Project Build Output**

### Runtime

- [Spinel Runtime](https://github.com/matz/spinel/blob/master/lib/spinel/runtime.h): `lib/spinel/runtime.h`
- [Runtime Helpers](https://github.com/matz/spinel/blob/master/lib/sp_cold.c): `lib/sp_cold.c`
- [Regexp Engine](https://github.com/matz/spinel/blob/master/lib/regexp/re_compile.c): `lib/regexp/re_compile.c`

### Packages

- [Package Sources](https://github.com/matz/spinel/tree/master/packages): `packages`
- [JSON Package](https://github.com/matz/spinel/blob/master/packages/json/sp_json.c): `packages/json/sp_json.c`
- [OpenSSL Package](https://github.com/matz/spinel/blob/master/packages/openssl/sp_openssl.c): `packages/openssl/sp_openssl.c`

### Other components

- **Ruby Developer**
- **Ruby Source**
- **Generated C**
- **System C Compiler**
- **Native Executable**

## Connections

- Ruby Developer → spin CLI: uses
- Ruby Developer → spinel Compiler: invokes
- Ruby Source → spinel Compiler: compiles
- spin CLI → spinel Compiler: drives
- spinel Compiler → Prism Parser: parses with
- Prism Parser → Node Table: produces AST
- spinel Compiler → Node Table: loads AST (evidence: `src/main.c`)
- Node Table → Type Analysis: analyzes
- RBS Extraction → Type Analysis: seeds types
- Type Analysis → C Generation: shares inferred types
- C Generation → Generated C: emits C
- spinel Compiler → System C Compiler: invokes
- System C Compiler → Native Executable: compiles and links
- System C Compiler → Spinel Runtime: links
- Package Sources → Native Executable: compiled into
- JSON Package → Spinel Runtime: uses ABI (evidence: `packages/json/sp_json.c`)
- OpenSSL Package → Spinel Runtime: uses ABI (evidence: `packages/openssl/sp_openssl.c`)
- Runtime Helpers → Spinel Runtime: implements helpers
- spin CLI → Project Build Output: builds projects
- spin CLI → Package Sources: resolves dependencies
