# andrealaforgia/magic-lisp architecture

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

- Interactive diagram: https://gitdiagram.com/andrealaforgia/magic-lisp
- Repository: https://github.com/andrealaforgia/magic-lisp

## Overview

MagicLisp is a Rust implementation of a Scheme-family Lisp, exposed as a single CLI. Its principal workflow is source input → reading → compilation to bytecode → VM execution and output; the CLI also supports saving/loading bytecode, disassembly, and an interactive REPL. The VM uses runtime values for language data and execution. The README documents closures, macros, tail calls, cycle-safe cleanup, and rich data types, but the excerpts do not expose their internal wiring, so those capabilities are represented within the compiler/VM rather than as speculative components.

Main entry points: [`src/cli.rs`](https://github.com/andrealaforgia/magic-lisp/blob/main/src/cli.rs) (CLI dispatch), [`src/repl.rs`](https://github.com/andrealaforgia/magic-lisp/blob/main/src/repl.rs) (Interactive REPL), [`src/bytecode.rs`](https://github.com/andrealaforgia/magic-lisp/blob/main/src/bytecode.rs) (Bytecode format), [`src/compiler.rs`](https://github.com/andrealaforgia/magic-lisp/blob/main/src/compiler.rs) (Compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_cli["CLI dispatch<br/>[cli.rs]"]
  node_repl["Interactive REPL<br/>[repl.rs]"]
  node_exitcodes["Exit codes<br/>[exitcode.rs]"]
end

subgraph group_language["Language processing"]
  node_reader["Source reader<br/>[reader.rs]"]
  node_compiler["Compiler<br/>[compiler.rs]"]
end

subgraph group_runtime["Execution runtime"]
  node_vm["Virtual machine<br/>[vm.rs]"]
  node_values["Runtime values<br/>[value.rs]"]
end

subgraph group_tools["Bytecode tools"]
  node_bytecode["Bytecode format<br/>[bytecode.rs]"]
  node_disasm["Disassembler<br/>[disasm.rs]"]
end

node_user(("Programmer"))

node_user -->|"selects command"| node_cli
node_cli -->|"reads source"| node_reader
node_cli -->|"compiles source"| node_compiler
node_compiler -->|"consumes forms"| node_reader
node_compiler -->|"emits instructions"| node_bytecode
node_cli -->|"runs program"| node_vm
node_vm -->|"executes instructions"| node_bytecode
node_vm -->|"manipulates values"| node_values
node_cli -->|"encodes artifact"| node_bytecode
node_cli -->|"decodes artifact"| node_bytecode
node_cli -->|"disassembles artifact"| node_disasm
node_disasm -->|"inspects instructions"| node_bytecode
node_user -->|"enters session"| node_repl
node_cli -->|"starts REPL"| node_repl
node_repl -->|"reads entries"| node_reader
node_repl -->|"compiles entries"| node_compiler
node_repl -->|"executes entries"| node_vm
node_cli -->|"reports status"| node_exitcodes

click node_cli "https://github.com/andrealaforgia/magic-lisp/blob/main/src/cli.rs"
click node_repl "https://github.com/andrealaforgia/magic-lisp/blob/main/src/repl.rs"
click node_reader "https://github.com/andrealaforgia/magic-lisp/blob/main/src/reader.rs"
click node_compiler "https://github.com/andrealaforgia/magic-lisp/blob/main/src/compiler.rs"
click node_bytecode "https://github.com/andrealaforgia/magic-lisp/blob/main/src/bytecode.rs"
click node_vm "https://github.com/andrealaforgia/magic-lisp/blob/main/src/vm.rs"
click node_values "https://github.com/andrealaforgia/magic-lisp/blob/main/src/value.rs"
click node_disasm "https://github.com/andrealaforgia/magic-lisp/blob/main/src/disasm.rs"
click node_exitcodes "https://github.com/andrealaforgia/magic-lisp/blob/main/src/exitcode.rs"

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_repl,node_exitcodes toneBlue
class node_reader,node_compiler toneAmber
class node_vm,node_values toneMint
class node_bytecode,node_disasm toneRose
class node_user toneIndigo
```

## Components

### User interfaces

- [CLI dispatch](https://github.com/andrealaforgia/magic-lisp/blob/main/src/cli.rs): `src/cli.rs`
- [Interactive REPL](https://github.com/andrealaforgia/magic-lisp/blob/main/src/repl.rs): `src/repl.rs`
- [Exit codes](https://github.com/andrealaforgia/magic-lisp/blob/main/src/exitcode.rs): `src/exitcode.rs`

### Language processing

- [Source reader](https://github.com/andrealaforgia/magic-lisp/blob/main/src/reader.rs): `src/reader.rs`
- [Compiler](https://github.com/andrealaforgia/magic-lisp/blob/main/src/compiler.rs): `src/compiler.rs`

### Execution runtime

- [Virtual machine](https://github.com/andrealaforgia/magic-lisp/blob/main/src/vm.rs): `src/vm.rs`
- [Runtime values](https://github.com/andrealaforgia/magic-lisp/blob/main/src/value.rs): `src/value.rs`

### Bytecode tools

- [Bytecode format](https://github.com/andrealaforgia/magic-lisp/blob/main/src/bytecode.rs): `src/bytecode.rs`
- [Disassembler](https://github.com/andrealaforgia/magic-lisp/blob/main/src/disasm.rs): `src/disasm.rs`

### Other components

- **Programmer**

## Connections

- Programmer → CLI dispatch: selects command (evidence: `README.md`)
- CLI dispatch → Source reader: reads source (evidence: `src/cli.rs`)
- CLI dispatch → Compiler: compiles source (evidence: `src/cli.rs`)
- Compiler → Source reader: consumes forms (evidence: `src/compiler.rs`)
- Compiler → Bytecode format: emits instructions (evidence: `src/compiler.rs`)
- CLI dispatch → Virtual machine: runs program (evidence: `src/cli.rs`)
- Virtual machine → Bytecode format: executes instructions (evidence: `src/vm.rs`)
- Virtual machine → Runtime values: manipulates values (evidence: `src/vm.rs`)
- CLI dispatch → Bytecode format: encodes artifact (evidence: `src/cli.rs`)
- CLI dispatch → Bytecode format: decodes artifact (evidence: `src/cli.rs`)
- CLI dispatch → Disassembler: disassembles artifact (evidence: `src/cli.rs`)
- Disassembler → Bytecode format: inspects instructions (evidence: `src/disasm.rs`)
- Programmer → Interactive REPL: enters session (evidence: `README.md`)
- CLI dispatch → Interactive REPL: starts REPL (evidence: `src/cli.rs`)
- Interactive REPL → Source reader: reads entries (evidence: `src/repl.rs`)
- Interactive REPL → Compiler: compiles entries (evidence: `src/repl.rs`)
- Interactive REPL → Virtual machine: executes entries (evidence: `src/repl.rs`)
- CLI dispatch → Exit codes: reports status (evidence: `src/cli.rs`)
