# fus3n/pyle architecture

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

- Interactive diagram: https://gitdiagram.com/fus3n/pyle
- Repository: https://github.com/fus3n/pyle

## Overview

Pyle is an embeddable C++ scripting language. Its principal workflow takes script text through lexing, parsing and bytecode compilation, then executes it in a stack-based VM with native bindings and standard modules. The repository also provides a CLI, a language server and a VS Code extension. The README documents these product capabilities; sampled source supports some internal calls, while unsampled modules are represented by their exact tree paths and their connections are omitted or marked unverified.

Main entry points: [`pyle/src/main.cpp`](https://github.com/fus3n/pyle/blob/main/pyle/src/main.cpp) (Pyle CLI), [`libpyle/src/std/std_core.cpp`](https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_core.cpp) (Core functions), [`pyle-lsp/src/lsp_server.hpp`](https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_server.hpp) (Language server), [`libpyle/src/parser.cpp`](https://github.com/fus3n/pyle/blob/main/libpyle/src/parser.cpp) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_language["Language Runtime"]
  node_api["Embedding API<br/>[pyle.cpp]"]
  node_lexer["Lexer<br/>[lexer.cpp]"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_ast["Syntax tree<br/>[ast.hpp]"]
  node_compiler["Bytecode compiler<br/>[compiler.cpp]"]
  node_bytecode["Bytecode format<br/>[bytecode.hpp]"]
  node_vm["Virtual machine<br/>[vm.cpp]"]
  node_values["Values and heap<br/>[value.hpp]"]
  node_binder["Native bindings<br/>[binder.hpp]"]
end

subgraph group_stdlib["Native Capabilities"]
  node_core["Core functions<br/>[std_core.cpp]"]
  node_collections["Collections<br/>[std_array.cpp]"]
  node_async["Coroutines and futures<br/>[std_future.cpp]"]
  node_process["Process support<br/>[std_proc.cpp]"]
  node_http["HTTP module"]
  node_jsoncrypto["JSON and crypto"]
end

subgraph group_tools["Developer Tools"]
  node_cli["Pyle CLI<br/>[main.cpp]"]
  node_lsp["Language server<br/>[lsp_server.hpp]"]
  node_resolver["Document resolver<br/>[lsp_resolver.hpp]"]
  node_analyzer["Language analyzer<br/>[lsp_analyzer.hpp]"]
  node_transport["LSP transport<br/>[lsp_transport.hpp]"]
end

subgraph group_editor["Editor Integration"]
  node_vscode["VS Code extension<br/>[extension.js]"]
end

node_developer(("Script author"))

node_developer -->|"runs script"| node_cli
node_cli -.->|"executes source"| node_api
node_api -.->|"tokenizes"| node_lexer
node_lexer -.->|"supplies tokens"| node_parser
node_parser -->|"builds tree"| node_ast
node_parser -.->|"provides syntax"| node_compiler
node_compiler -->|"emits instructions"| node_bytecode
node_compiler -.->|"loads executable code"| node_vm
node_vm -->|"manages values"| node_values
node_cli -->|"registers natives"| node_core
node_cli -->|"registers module"| node_http
node_cli -->|"registers modules"| node_jsoncrypto
node_core -->|"binds host functions"| node_binder
node_core -->|"uses futures"| node_async
node_core -.->|"provides collections"| node_collections
node_cli -->|"initializes workers"| node_process
node_developer -->|"edits scripts"| node_vscode
node_vscode -->|"uses language services"| node_lsp
node_lsp -->|"exchanges messages"| node_transport
node_lsp -->|"loads documents"| node_resolver
node_lsp -->|"analyzes documents"| node_analyzer
node_resolver -->|"uses analysis"| node_analyzer

click node_cli "https://github.com/fus3n/pyle/blob/main/pyle/src/main.cpp"
click node_api "https://github.com/fus3n/pyle/blob/main/libpyle/src/pyle.cpp"
click node_lexer "https://github.com/fus3n/pyle/blob/main/libpyle/src/lexer.cpp"
click node_parser "https://github.com/fus3n/pyle/blob/main/libpyle/src/parser.cpp"
click node_ast "https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/ast.hpp"
click node_compiler "https://github.com/fus3n/pyle/blob/main/libpyle/src/compiler.cpp"
click node_bytecode "https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/bytecode.hpp"
click node_vm "https://github.com/fus3n/pyle/blob/main/libpyle/src/vm.cpp"
click node_values "https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/value.hpp"
click node_binder "https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/binder.hpp"
click node_core "https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_core.cpp"
click node_collections "https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_array.cpp"
click node_async "https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_future.cpp"
click node_process "https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_proc.cpp"
click node_http "https://github.com/fus3n/pyle/tree/main/pyle/src/std/http"
click node_jsoncrypto "https://github.com/fus3n/pyle/tree/main/pyle/src/std"
click node_lsp "https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_server.hpp"
click node_resolver "https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_resolver.hpp"
click node_analyzer "https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_analyzer.hpp"
click node_transport "https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_transport.hpp"
click node_vscode "https://github.com/fus3n/pyle/blob/main/editors/vscode/src/extension.js"

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_api,node_lexer,node_parser,node_ast,node_compiler,node_bytecode,node_vm,node_values,node_binder toneBlue
class node_core,node_collections,node_async,node_process,node_http,node_jsoncrypto toneAmber
class node_cli,node_lsp,node_resolver,node_analyzer,node_transport toneMint
class node_vscode toneRose
class node_developer toneIndigo
```

## Components

### Language Runtime

- [Embedding API](https://github.com/fus3n/pyle/blob/main/libpyle/src/pyle.cpp): `libpyle/src/pyle.cpp`
- [Lexer](https://github.com/fus3n/pyle/blob/main/libpyle/src/lexer.cpp): `libpyle/src/lexer.cpp`
- [Parser](https://github.com/fus3n/pyle/blob/main/libpyle/src/parser.cpp): `libpyle/src/parser.cpp`
- [Syntax tree](https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/ast.hpp): `libpyle/include/pyle/ast.hpp`
- [Bytecode compiler](https://github.com/fus3n/pyle/blob/main/libpyle/src/compiler.cpp): `libpyle/src/compiler.cpp`
- [Bytecode format](https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/bytecode.hpp): `libpyle/include/pyle/bytecode.hpp`
- [Virtual machine](https://github.com/fus3n/pyle/blob/main/libpyle/src/vm.cpp): `libpyle/src/vm.cpp`
- [Values and heap](https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/value.hpp): `libpyle/include/pyle/value.hpp`
- [Native bindings](https://github.com/fus3n/pyle/blob/main/libpyle/include/pyle/binder.hpp): `libpyle/include/pyle/binder.hpp`

### Native Capabilities

- [Core functions](https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_core.cpp): `libpyle/src/std/std_core.cpp`
- [Collections](https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_array.cpp): `libpyle/src/std/std_array.cpp`
- [Coroutines and futures](https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_future.cpp): `libpyle/src/std/std_future.cpp`
- [Process support](https://github.com/fus3n/pyle/blob/main/libpyle/src/std/std_proc.cpp): `libpyle/src/std/std_proc.cpp`
- [HTTP module](https://github.com/fus3n/pyle/tree/main/pyle/src/std/http): `pyle/src/std/http`
- [JSON and crypto](https://github.com/fus3n/pyle/tree/main/pyle/src/std): `pyle/src/std`

### Developer Tools

- [Pyle CLI](https://github.com/fus3n/pyle/blob/main/pyle/src/main.cpp): `pyle/src/main.cpp`
- [Language server](https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_server.hpp): `pyle-lsp/src/lsp_server.hpp`
- [Document resolver](https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_resolver.hpp): `pyle-lsp/src/lsp_resolver.hpp`
- [Language analyzer](https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_analyzer.hpp): `pyle-lsp/src/lsp_analyzer.hpp`
- [LSP transport](https://github.com/fus3n/pyle/blob/main/pyle-lsp/src/lsp_transport.hpp): `pyle-lsp/src/lsp_transport.hpp`

### Editor Integration

- [VS Code extension](https://github.com/fus3n/pyle/blob/main/editors/vscode/src/extension.js): `editors/vscode/src/extension.js`

### Other components

- **Script author**

## Connections

- Script author → Pyle CLI: runs script
- Pyle CLI → Embedding API: executes source
- Embedding API → Lexer: tokenizes
- Lexer → Parser: supplies tokens
- Parser → Syntax tree: builds tree (evidence: `libpyle/src/parser.cpp`)
- Parser → Bytecode compiler: provides syntax
- Bytecode compiler → Bytecode format: emits instructions (evidence: `libpyle/src/compiler.cpp`)
- Bytecode compiler → Virtual machine: loads executable code
- Virtual machine → Values and heap: manages values (evidence: `libpyle/src/vm.cpp`)
- Pyle CLI → Core functions: registers natives (evidence: `pyle/src/main.cpp`)
- Pyle CLI → HTTP module: registers module (evidence: `pyle/src/main.cpp`)
- Pyle CLI → JSON and crypto: registers modules (evidence: `pyle/src/main.cpp`)
- Core functions → Native bindings: binds host functions (evidence: `libpyle/src/std/std_core.cpp`)
- Core functions → Coroutines and futures: uses futures (evidence: `libpyle/src/std/std_core.cpp`)
- Core functions → Collections: provides collections
- Pyle CLI → Process support: initializes workers (evidence: `pyle/src/main.cpp`)
- Script author → VS Code extension: edits scripts
- VS Code extension → Language server: uses language services
- Language server → LSP transport: exchanges messages (evidence: `pyle-lsp/src/lsp_server.hpp`)
- Language server → Document resolver: loads documents (evidence: `pyle-lsp/src/lsp_server.hpp`)
- Language server → Language analyzer: analyzes documents (evidence: `pyle-lsp/src/lsp_server.hpp`)
- Document resolver → Language analyzer: uses analysis (evidence: `pyle-lsp/src/lsp_resolver.hpp`)