# thepeilin/fakelisp architecture

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

- Interactive diagram: https://gitdiagram.com/thepeilin/fakelisp
- Repository: https://github.com/thepeilin/fakelisp

## Overview

fakeLisp is an embeddable C implementation of a Lisp interpreter. Its principal workflow is to read source, parse expressions, generate executable code, and run it in a virtual machine; the sampled parser supports the parsing stage, while the remaining links in that workflow are not verified in the excerpts. The product also includes compiler and bytecode tools, macro and grammar facilities, module support, a libuv binding, threading, and a debugger. Several connections are documented capabilities rather than inspected call sites.

Main entry points: [`src/vmrun.c`](https://github.com/thepeilin/fakelisp/blob/master/src/vmrun.c) (Virtual Machine), [`main/fakeLisp.c`](https://github.com/thepeilin/fakelisp/blob/master/main/fakeLisp.c) (Interpreter CLI), [`src/parser.c`](https://github.com/thepeilin/fakelisp/blob/master/src/parser.c) (Source Reader), [`src/code_gen.c`](https://github.com/thepeilin/fakelisp/blob/master/src/code_gen.c) (Code Generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Language Frontend"]
  node_reader["Source Reader<br/>[parser.c]"]
  node_grammar["Grammar Parser<br/>[parser_grammer.c]"]
  node_grammar_model["Grammar Model<br/>[grammer.h]"]
  node_codegen["Code Generation<br/>[code_gen.c]"]
  node_optimizer["Code Optimizer<br/>[optimizer.c]"]
end

subgraph group_runtime["Execution Runtime"]
  node_vm["Virtual Machine<br/>[vmrun.c]"]
  node_vm_values["VM Values<br/>[vmvalue.c]"]
  node_gc["Memory Management<br/>[vmgc.c]"]
end

subgraph group_extensions["Language Extensions"]
  node_builtins["Builtin Functions<br/>[builtin.c]"]
  node_macros["Grammar Builtins<br/>[builtin.c]"]
  node_modules["Module Support<br/>[fs.c]"]
  node_fuv["libuv Binding<br/>[main.c]"]
  node_libuv["libuv Runtime<br/>[uv.h]"]
  node_threads["Thread Support<br/>[sync.c]"]
end

subgraph group_interfaces["Tools and Integrations"]
  node_compiler["Compiler CLI<br/>[fakeLispc.c]"]
  node_bytecode_tool["Bytecode Printer<br/>[fakeLispp.c]"]
  node_interpreter["Interpreter CLI<br/>[fakeLisp.c]"]
  node_debugger["Debugger Module<br/>[main.c]"]
  node_debug_core["Debugger Core<br/>[bdb.c]"]
end

node_user(("Lisp Source User"))

node_user -->|"runs source"| node_interpreter
node_interpreter -.->|"reads source"| node_reader
node_reader -->|"parses with"| node_grammar_model
node_reader -.->|"supplies expressions"| node_codegen
node_grammar -.->|"uses grammar"| node_grammar_model
node_compiler -.->|"reads source"| node_reader
node_compiler -.->|"compiles"| node_codegen
node_codegen -.->|"optimizes code"| node_optimizer
node_interpreter -.->|"runs program"| node_vm
node_vm -.->|"operates on"| node_vm_values
node_vm -.->|"manages memory"| node_gc
node_vm -.->|"dispatches builtins"| node_builtins
node_vm -.->|"supports macros"| node_macros
node_interpreter -.->|"supports modules"| node_modules
node_vm -.->|"loads binding"| node_fuv
node_fuv -->|"calls API"| node_libuv
node_vm -.->|"supports threads"| node_threads
node_interpreter -.->|"loads debugger"| node_debugger
node_debugger -->|"uses core"| node_debug_core
node_bytecode_tool -.->|"prints bytecode"| node_vm

click node_reader "https://github.com/thepeilin/fakelisp/blob/master/src/parser.c"
click node_grammar "https://github.com/thepeilin/fakelisp/blob/master/src/parser_grammer.c"
click node_grammar_model "https://github.com/thepeilin/fakelisp/blob/master/include/fakeLisp/grammer.h"
click node_codegen "https://github.com/thepeilin/fakelisp/blob/master/src/code_gen.c"
click node_optimizer "https://github.com/thepeilin/fakelisp/blob/master/src/optimizer.c"
click node_compiler "https://github.com/thepeilin/fakelisp/blob/master/main/fakeLispc.c"
click node_bytecode_tool "https://github.com/thepeilin/fakelisp/blob/master/main/fakeLispp.c"
click node_interpreter "https://github.com/thepeilin/fakelisp/blob/master/main/fakeLisp.c"
click node_vm "https://github.com/thepeilin/fakelisp/blob/master/src/vmrun.c"
click node_vm_values "https://github.com/thepeilin/fakelisp/blob/master/src/vmvalue.c"
click node_gc "https://github.com/thepeilin/fakelisp/blob/master/src/vmgc.c"
click node_builtins "https://github.com/thepeilin/fakelisp/blob/master/src/builtin.c"
click node_macros "https://github.com/thepeilin/fakelisp/blob/master/src/grammer/builtin.c"
click node_modules "https://github.com/thepeilin/fakelisp/blob/master/src/fs/fs.c"
click node_fuv "https://github.com/thepeilin/fakelisp/blob/master/src/fuv/main.c"
click node_libuv "https://github.com/thepeilin/fakelisp/blob/master/3rd/libuv/include/uv.h"
click node_threads "https://github.com/thepeilin/fakelisp/blob/master/src/sync/sync.c"
click node_debugger "https://github.com/thepeilin/fakelisp/blob/master/src/bdb/main.c"
click node_debug_core "https://github.com/thepeilin/fakelisp/blob/master/src/bdb/bdb.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_reader,node_grammar,node_grammar_model,node_codegen,node_optimizer,node_user toneBlue
class node_vm,node_vm_values,node_gc toneAmber
class node_builtins,node_macros,node_modules,node_fuv,node_libuv,node_threads toneMint
class node_compiler,node_bytecode_tool,node_interpreter,node_debugger,node_debug_core toneRose
```

## Components

### Language Frontend

- [Source Reader](https://github.com/thepeilin/fakelisp/blob/master/src/parser.c): `src/parser.c`
- [Grammar Parser](https://github.com/thepeilin/fakelisp/blob/master/src/parser_grammer.c): `src/parser_grammer.c`
- [Grammar Model](https://github.com/thepeilin/fakelisp/blob/master/include/fakeLisp/grammer.h): `include/fakeLisp/grammer.h`
- [Code Generation](https://github.com/thepeilin/fakelisp/blob/master/src/code_gen.c): `src/code_gen.c`
- [Code Optimizer](https://github.com/thepeilin/fakelisp/blob/master/src/optimizer.c): `src/optimizer.c`

### Execution Runtime

- [Virtual Machine](https://github.com/thepeilin/fakelisp/blob/master/src/vmrun.c): `src/vmrun.c`
- [VM Values](https://github.com/thepeilin/fakelisp/blob/master/src/vmvalue.c): `src/vmvalue.c`
- [Memory Management](https://github.com/thepeilin/fakelisp/blob/master/src/vmgc.c): `src/vmgc.c`

### Language Extensions

- [Builtin Functions](https://github.com/thepeilin/fakelisp/blob/master/src/builtin.c): `src/builtin.c`
- [Grammar Builtins](https://github.com/thepeilin/fakelisp/blob/master/src/grammer/builtin.c): `src/grammer/builtin.c`
- [Module Support](https://github.com/thepeilin/fakelisp/blob/master/src/fs/fs.c): `src/fs/fs.c`
- [libuv Binding](https://github.com/thepeilin/fakelisp/blob/master/src/fuv/main.c): `src/fuv/main.c`
- [libuv Runtime](https://github.com/thepeilin/fakelisp/blob/master/3rd/libuv/include/uv.h): `3rd/libuv/include/uv.h`
- [Thread Support](https://github.com/thepeilin/fakelisp/blob/master/src/sync/sync.c): `src/sync/sync.c`

### Tools and Integrations

- [Compiler CLI](https://github.com/thepeilin/fakelisp/blob/master/main/fakeLispc.c): `main/fakeLispc.c`
- [Bytecode Printer](https://github.com/thepeilin/fakelisp/blob/master/main/fakeLispp.c): `main/fakeLispp.c`
- [Interpreter CLI](https://github.com/thepeilin/fakelisp/blob/master/main/fakeLisp.c): `main/fakeLisp.c`
- [Debugger Module](https://github.com/thepeilin/fakelisp/blob/master/src/bdb/main.c): `src/bdb/main.c`
- [Debugger Core](https://github.com/thepeilin/fakelisp/blob/master/src/bdb/bdb.c): `src/bdb/bdb.c`

### Other components

- **Lisp Source User**

## Connections

- Lisp Source User → Interpreter CLI: runs source (evidence: `README.md`)
- Interpreter CLI → Source Reader: reads source
- Source Reader → Grammar Model: parses with (evidence: `src/parser.c`)
- Source Reader → Code Generation: supplies expressions
- Grammar Parser → Grammar Model: uses grammar
- Compiler CLI → Source Reader: reads source
- Compiler CLI → Code Generation: compiles
- Code Generation → Code Optimizer: optimizes code
- Interpreter CLI → Virtual Machine: runs program
- Virtual Machine → VM Values: operates on
- Virtual Machine → Memory Management: manages memory
- Virtual Machine → Builtin Functions: dispatches builtins
- Virtual Machine → Grammar Builtins: supports macros
- Interpreter CLI → Module Support: supports modules
- Virtual Machine → libuv Binding: loads binding
- libuv Binding → libuv Runtime: calls API (evidence: `src/fuv/main.c`)
- Virtual Machine → Thread Support: supports threads
- Interpreter CLI → Debugger Module: loads debugger
- Debugger Module → Debugger Core: uses core (evidence: `src/bdb/main.c`)
- Bytecode Printer → Virtual Machine: prints bytecode
