# cococopi/corros architecture

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

- Interactive diagram: https://gitdiagram.com/cococopi/corros
- Repository: https://github.com/cococopi/corros

## Overview

#### Purpose and Entry Points
Corros is a dependency-free Rust implementation of a bytecode-compiled scripting language, plus a self-hosted implementation written in Corros. The native CLI runs scripts, starts an interactive REPL, dumps bytecode, and executes serialized bytecode. Primary entry points are `src/main.rs` (CLI), `src/lib.rs` (crate API), and `src/repl.rs` (interactive mode).

#### Source Loading and Module Boundary
Programs are read and expanded before compilation. `adopt` imports are resolved relative to source files, spliced into the token stream, and guarded against cycles by `src/loader.rs`. The language prelude is injected ahead of user code from `lib/prelude.cor`, making much of the standard library ordinary Corros source rather than Rust runtime code.

#### Front End: Lexing and Single-Pass Compilation
`src/lexer.rs` scans source into Corros tokens, including language-specific keywords, literals, operators, and comments. `src/compiler.rs` combines recursive-descent parsing with immediate bytecode emission: it manages scopes, globals/locals, assignment expressions, control-flow jumps, functions, closures, and upvalue capture. Compilation errors are represented and source-located through `src/error.rs`.

#### Bytecode Representation
`src/chunk.rs` defines executable chunks: instructions, constant pools, and bytecode disassembly used by `--dump`. `src/bc.rs` supports bytecode-oriented execution and is the boundary used by the self-hosting bootstrap flow (`--run-bc`). Compiler output is therefore independent of the source parser at runtime.

#### Runtime Model and VM
`src/vm.rs` is a stack-machine interpreter that executes chunks, manages call frames, globals, closures/upvalues, collection operations, and runtime traceback generation. Runtime objects and their semantics—numbers, strings, lists, maps, ranges, functions, closures, and native functions—are centralized in `src/value.rs`. This is the main host-language boundary: Rust owns memory/runtime representation while Corros code supplies higher-level behavior.

#### Native and Corros Standard Libraries
`src/stdlib.rs` registers host builtins for I/O, conversion, math, timing, assertions/errors, and primitives that require native access. `lib/prelude.cor` layers Corros-defined list, string, map, and range behavior above those primitives, including method dispatch. Thus method-heavy user programs generally flow through prelude code, with Rust as fallback for irreducible host operations.

#### Self-Hosting Bootstrap
The self-hosted compiler and VM are Corros programs at `selfhost/compiler.cor` and `selfhost/vm.cor`. `selfhost/demo.sh` uses the Rust implementation to compile both, then runs the compiled VM/compiler chain and compares produced bytecode for byte-identical results. This validates compatibility between the native compiler/VM and the language-level implementation.

#### Runtime and Infrastructure
The project is one Rust crate (`Cargo.toml`) requiring Rust 1.70+ for source builds and has no external dependencies. Distribution is via release binaries with source-build fallback in `install.sh`; there are no databases, network services, or web infrastructure in the runtime architecture.

Main entry points: [`src/main.rs`](https://github.com/cococopi/corros/blob/main/src/main.rs) (Native CLI), [`src/loader.rs`](https://github.com/cococopi/corros/blob/main/src/loader.rs) (Source loader), [`src/chunk.rs`](https://github.com/cococopi/corros/blob/main/src/chunk.rs) (Bytecode chunks), [`src/vm.rs`](https://github.com/cococopi/corros/blob/main/src/vm.rs) (Native VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native Rust runtime"]
  node_cli["Native CLI<br/>Rust entry point<br/>[main.rs]"]
  node_crate_api["Crate API<br/>Rust API<br/>[lib.rs]"]
  node_repl["Interactive REPL<br/>interactive mode<br/>[repl.rs]"]
  node_loader["Source loader<br/>import expansion<br/>[loader.rs]"]
  node_lexer["Lexer<br/>tokenizer<br/>[lexer.rs]"]
  node_compiler["Native compiler<br/>parser + emitter<br/>[compiler.rs]"]
  node_errors["Source errors<br/>diagnostics<br/>[error.rs]"]
  node_chunk["Bytecode chunks<br/>IR / serialization<br/>[chunk.rs]"]
  node_bytecode_runner["Bytecode execution boundary<br/>bytecode mode<br/>[bc.rs]"]
  node_vm["Native VM<br/>stack interpreter<br/>[vm.rs]"]
  node_values["Runtime values<br/>object model<br/>[value.rs]"]
  node_native_stdlib["Native standard library<br/>host builtins<br/>[stdlib.rs]"]
  node_crate{{"Corros crate<br/>Rust package<br/>[Cargo.toml]"}}
end

subgraph group_language["Corros language library"]
  node_prelude["Language prelude<br/>Corros standard library<br/>[prelude.cor]"]
end

subgraph group_bootstrap["Self-hosting bootstrap"]
  node_selfhost_compiler["Self-hosted compiler<br/>Corros compiler<br/>[compiler.cor]"]
  node_selfhost_vm["Self-hosted VM<br/>Corros VM<br/>[vm.cor]"]
  node_bootstrap_demo["Bootstrap verifier<br/>compatibility workflow<br/>[demo.sh]"]
end

node_crate -->|"builds"| node_cli
node_cli -->|"interactive mode"| node_repl
node_cli -->|"loads source"| node_loader
node_cli -->|"--run-bc"| node_bytecode_runner
node_repl -->|"submits source"| node_loader
node_loader -->|"injects"| node_prelude
node_loader -->|"expanded source"| node_lexer
node_lexer -->|"tokens"| node_compiler
node_compiler -->|"emits"| node_chunk
node_compiler -.->|"reports"| node_errors
node_chunk -->|"serialized bytecode"| node_bytecode_runner
node_chunk -->|"executable chunk"| node_vm
node_bytecode_runner -->|"dispatches"| node_vm
node_vm -->|"operates on"| node_values
node_vm -->|"calls builtins"| node_native_stdlib
node_prelude -->|"uses primitives"| node_native_stdlib
node_bootstrap_demo -->|"compiles"| node_selfhost_compiler
node_bootstrap_demo -->|"compiles and runs"| node_selfhost_vm
node_bootstrap_demo -->|"uses native implementation"| node_cli
node_selfhost_compiler -->|"produces bytecode for"| node_selfhost_vm
node_selfhost_vm -.->|"compatibility target"| node_chunk

click node_cli "https://github.com/cococopi/corros/blob/main/src/main.rs"
click node_crate_api "https://github.com/cococopi/corros/blob/main/src/lib.rs"
click node_repl "https://github.com/cococopi/corros/blob/main/src/repl.rs"
click node_loader "https://github.com/cococopi/corros/blob/main/src/loader.rs"
click node_lexer "https://github.com/cococopi/corros/blob/main/src/lexer.rs"
click node_compiler "https://github.com/cococopi/corros/blob/main/src/compiler.rs"
click node_errors "https://github.com/cococopi/corros/blob/main/src/error.rs"
click node_chunk "https://github.com/cococopi/corros/blob/main/src/chunk.rs"
click node_bytecode_runner "https://github.com/cococopi/corros/blob/main/src/bc.rs"
click node_vm "https://github.com/cococopi/corros/blob/main/src/vm.rs"
click node_values "https://github.com/cococopi/corros/blob/main/src/value.rs"
click node_native_stdlib "https://github.com/cococopi/corros/blob/main/src/stdlib.rs"
click node_prelude "https://github.com/cococopi/corros/blob/main/lib/prelude.cor"
click node_selfhost_compiler "https://github.com/cococopi/corros/blob/main/selfhost/compiler.cor"
click node_selfhost_vm "https://github.com/cococopi/corros/blob/main/selfhost/vm.cor"
click node_bootstrap_demo "https://github.com/cococopi/corros/blob/main/selfhost/demo.sh"
click node_crate "https://github.com/cococopi/corros/blob/main/Cargo.toml"

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_crate_api,node_repl,node_loader,node_lexer,node_compiler,node_errors,node_chunk,node_bytecode_runner,node_vm,node_values,node_native_stdlib,node_crate toneBlue
class node_prelude toneAmber
class node_selfhost_compiler,node_selfhost_vm,node_bootstrap_demo toneMint
```

## Components

### Native Rust runtime

- [Native CLI](https://github.com/cococopi/corros/blob/main/src/main.rs): Rust entry point · Runs source, REPL, dumps, and serialized bytecode. · `src/main.rs`
- [Crate API](https://github.com/cococopi/corros/blob/main/src/lib.rs): Rust API · `src/lib.rs`
- [Interactive REPL](https://github.com/cococopi/corros/blob/main/src/repl.rs): interactive mode · `src/repl.rs`
- [Source loader](https://github.com/cococopi/corros/blob/main/src/loader.rs): import expansion · Resolves adopt imports, injects the prelude, and rejects cycles. · `src/loader.rs`
- [Lexer](https://github.com/cococopi/corros/blob/main/src/lexer.rs): tokenizer · `src/lexer.rs`
- [Native compiler](https://github.com/cococopi/corros/blob/main/src/compiler.rs): parser + emitter · Single-pass recursive-descent compiler with scope and closure handling. · `src/compiler.rs`
- [Source errors](https://github.com/cococopi/corros/blob/main/src/error.rs): diagnostics · `src/error.rs`
- [Bytecode chunks](https://github.com/cococopi/corros/blob/main/src/chunk.rs): IR / serialization · Instructions, constants, and disassembly representation. · `src/chunk.rs`
- [Bytecode execution boundary](https://github.com/cococopi/corros/blob/main/src/bc.rs): bytecode mode · Supports --run-bc and bootstrap bytecode execution. · `src/bc.rs`
- [Native VM](https://github.com/cococopi/corros/blob/main/src/vm.rs): stack interpreter · Executes chunks with frames, globals, closures, and tracebacks. · `src/vm.rs`
- [Runtime values](https://github.com/cococopi/corros/blob/main/src/value.rs): object model · Rust representations and semantics for language objects. · `src/value.rs`
- [Native standard library](https://github.com/cococopi/corros/blob/main/src/stdlib.rs): host builtins · Registers I/O, conversion, math, timing, and primitive operations. · `src/stdlib.rs`
- [Corros crate](https://github.com/cococopi/corros/blob/main/Cargo.toml): Rust package · Dependency-free Rust crate requiring Rust 1.70+. · `Cargo.toml`

### Corros language library

- [Language prelude](https://github.com/cococopi/corros/blob/main/lib/prelude.cor): Corros standard library · Defines collection behavior and method dispatch over native primitives. · `lib/prelude.cor`

### Self-hosting bootstrap

- [Self-hosted compiler](https://github.com/cococopi/corros/blob/main/selfhost/compiler.cor): Corros compiler · `selfhost/compiler.cor`
- [Self-hosted VM](https://github.com/cococopi/corros/blob/main/selfhost/vm.cor): Corros VM · `selfhost/vm.cor`
- [Bootstrap verifier](https://github.com/cococopi/corros/blob/main/selfhost/demo.sh): compatibility workflow · Compiles and runs the self-hosted chain, comparing bytecode exactly. · `selfhost/demo.sh`

## Connections

- Corros crate → Native CLI: builds
- Native CLI → Interactive REPL: interactive mode
- Native CLI → Source loader: loads source
- Native CLI → Bytecode execution boundary: --run-bc
- Interactive REPL → Source loader: submits source
- Source loader → Language prelude: injects
- Source loader → Lexer: expanded source
- Lexer → Native compiler: tokens
- Native compiler → Bytecode chunks: emits
- Native compiler → Source errors: reports
- Bytecode chunks → Bytecode execution boundary: serialized bytecode
- Bytecode chunks → Native VM: executable chunk
- Bytecode execution boundary → Native VM: dispatches
- Native VM → Runtime values: operates on
- Native VM → Native standard library: calls builtins
- Language prelude → Native standard library: uses primitives
- Bootstrap verifier → Self-hosted compiler: compiles
- Bootstrap verifier → Self-hosted VM: compiles and runs
- Bootstrap verifier → Native CLI: uses native implementation
- Self-hosted compiler → Self-hosted VM: produces bytecode for
- Self-hosted VM → Bytecode chunks: compatibility target