# santhosharulsamy/sandy architecture

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

- Interactive diagram: https://gitdiagram.com/santhosharulsamy/sandy
- Repository: https://github.com/santhosharulsamy/sandy

## Overview

Sandy is a Python-implemented scripting language. The main workflow is a user running a .sy program through the CLI: runtime processing lexes and parses source, optionally type-checks it, then executes it with the tree-walking interpreter or bytecode VM; typed programs can also be built with the C backend. Separate capabilities include modules and packages, built-ins and standard library, concurrency, formatting, and editor support. The README and source index establish the major engine and tooling relationships; unsampled subsystem connections are omitted where their callers are not shown.

Main entry points: [`sandy/runtime.py`](https://github.com/santhosharulsamy/sandy/blob/main/sandy/runtime.py) (Runtime Orchestrator), [`sandy/lsp.py`](https://github.com/santhosharulsamy/sandy/blob/main/sandy/lsp.py) (Language Server), [`sandy/cli.py`](https://github.com/santhosharulsamy/sandy/blob/main/sandy/cli.py) (CLI), [`sandy/interpreter.py`](https://github.com/santhosharulsamy/sandy/blob/main/sandy/interpreter.py) (Tree Interpreter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language Front End"]
  node_lexer["Lexer<br/>[lexer.py]"]
  node_tokens["Tokens<br/>[tokens.py]"]
  node_parser["Parser<br/>[parser.py]"]
  node_ast["AST Nodes<br/>[nodes.py]"]
  node_typecheck["Type Checker<br/>[typecheck.py]"]
end

subgraph group_engines["Execution Engines"]
  node_interpreter["Tree Interpreter<br/>[interpreter.py]"]
  node_compiler["Bytecode Compiler<br/>[compiler.py]"]
  node_bytecode["Bytecode<br/>[bytecode.py]"]
  node_vm["Bytecode VM<br/>[vm.py]"]
  node_cbackend["C Backend<br/>[cbackend.py]"]
  node_values["Runtime Values<br/>[values.py]"]
end

subgraph group_ecosystem["Language Ecosystem"]
  node_builtins["Built-ins<br/>[builtins.py]"]
  node_concurrency["Concurrency<br/>[concurrency.py]"]
  node_stdlib["Standard Library"]
  node_packages["Package System<br/>[packages.py]"]
  node_registry["Registry Server<br/>[registry_server.py]"]
end

subgraph group_tools["Developer Tools"]
  node_formatter["Formatter<br/>[formatter.py]"]
  node_lsp["Language Server<br/>[lsp.py]"]
  node_repl["Interactive REPL<br/>[repl.py]"]
  node_playground["Browser Playground<br/>[playground.html]"]
end

subgraph group_delivery["Program Entry"]
  node_cli["CLI<br/>[cli.py]"]
  node_runtime["Runtime Orchestrator<br/>[runtime.py]"]
end

node_user(("Program Author"))
node_ccompiler["C Compiler"]

node_user -->|"runs program"| node_cli
node_cli -->|"dispatches execution"| node_runtime
node_runtime -->|"tokenizes source"| node_lexer
node_lexer -->|"emits tokens"| node_tokens
node_runtime -->|"parses tokens"| node_parser
node_parser -->|"builds AST"| node_ast
node_runtime -->|"checks types"| node_typecheck
node_runtime -->|"runs AST"| node_interpreter
node_runtime -->|"compiles program"| node_compiler
node_compiler -->|"emits instructions"| node_bytecode
node_runtime -->|"executes bytecode"| node_vm
node_runtime -->|"generates native code"| node_cbackend
node_cbackend -->|"invokes compiler"| node_ccompiler
node_interpreter -->|"uses values"| node_values
node_interpreter -->|"dispatches built-ins"| node_builtins
node_builtins -->|"provides concurrency"| node_concurrency
node_vm -->|"reuses runtime behavior"| node_interpreter
node_vm -->|"uses values"| node_values
node_interpreter -->|"loads modules"| node_packages
node_packages -->|"serves packages"| node_registry
node_cli -->|"starts REPL"| node_repl
node_cli -->|"formats source"| node_formatter
node_cli -->|"starts language server"| node_lsp
node_lsp -->|"uses lexer"| node_lexer
node_lsp -->|"uses parser"| node_parser
node_lsp -->|"checks diagnostics"| node_typecheck
node_lsp -->|"formats documents"| node_formatter
node_user -.->|"tries language"| node_playground
node_playground -.->|"runs implementation"| node_runtime

click node_cli "https://github.com/santhosharulsamy/sandy/blob/main/sandy/cli.py"
click node_runtime "https://github.com/santhosharulsamy/sandy/blob/main/sandy/runtime.py"
click node_lexer "https://github.com/santhosharulsamy/sandy/blob/main/sandy/lexer.py"
click node_tokens "https://github.com/santhosharulsamy/sandy/blob/main/sandy/tokens.py"
click node_parser "https://github.com/santhosharulsamy/sandy/blob/main/sandy/parser.py"
click node_ast "https://github.com/santhosharulsamy/sandy/blob/main/sandy/nodes.py"
click node_typecheck "https://github.com/santhosharulsamy/sandy/blob/main/sandy/typecheck.py"
click node_interpreter "https://github.com/santhosharulsamy/sandy/blob/main/sandy/interpreter.py"
click node_compiler "https://github.com/santhosharulsamy/sandy/blob/main/sandy/compiler.py"
click node_bytecode "https://github.com/santhosharulsamy/sandy/blob/main/sandy/bytecode.py"
click node_vm "https://github.com/santhosharulsamy/sandy/blob/main/sandy/vm.py"
click node_cbackend "https://github.com/santhosharulsamy/sandy/blob/main/sandy/cbackend.py"
click node_values "https://github.com/santhosharulsamy/sandy/blob/main/sandy/values.py"
click node_builtins "https://github.com/santhosharulsamy/sandy/blob/main/sandy/builtins.py"
click node_concurrency "https://github.com/santhosharulsamy/sandy/blob/main/sandy/concurrency.py"
click node_stdlib "https://github.com/santhosharulsamy/sandy/tree/main/sandy/stdlib"
click node_packages "https://github.com/santhosharulsamy/sandy/blob/main/sandy/packages.py"
click node_registry "https://github.com/santhosharulsamy/sandy/blob/main/sandy/registry_server.py"
click node_formatter "https://github.com/santhosharulsamy/sandy/blob/main/sandy/formatter.py"
click node_lsp "https://github.com/santhosharulsamy/sandy/blob/main/sandy/lsp.py"
click node_repl "https://github.com/santhosharulsamy/sandy/blob/main/sandy/repl.py"
click node_playground "https://github.com/santhosharulsamy/sandy/blob/main/web/playground.html"

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_lexer,node_tokens,node_parser,node_ast,node_typecheck toneBlue
class node_interpreter,node_compiler,node_bytecode,node_vm,node_cbackend,node_values toneAmber
class node_builtins,node_concurrency,node_stdlib,node_packages,node_registry toneMint
class node_formatter,node_lsp,node_repl,node_playground toneRose
class node_cli,node_runtime,node_user,node_ccompiler toneIndigo
```

## Components

### Language Front End

- [Lexer](https://github.com/santhosharulsamy/sandy/blob/main/sandy/lexer.py): `sandy/lexer.py`
- [Tokens](https://github.com/santhosharulsamy/sandy/blob/main/sandy/tokens.py): `sandy/tokens.py`
- [Parser](https://github.com/santhosharulsamy/sandy/blob/main/sandy/parser.py): `sandy/parser.py`
- [AST Nodes](https://github.com/santhosharulsamy/sandy/blob/main/sandy/nodes.py): `sandy/nodes.py`
- [Type Checker](https://github.com/santhosharulsamy/sandy/blob/main/sandy/typecheck.py): `sandy/typecheck.py`

### Execution Engines

- [Tree Interpreter](https://github.com/santhosharulsamy/sandy/blob/main/sandy/interpreter.py): `sandy/interpreter.py`
- [Bytecode Compiler](https://github.com/santhosharulsamy/sandy/blob/main/sandy/compiler.py): `sandy/compiler.py`
- [Bytecode](https://github.com/santhosharulsamy/sandy/blob/main/sandy/bytecode.py): `sandy/bytecode.py`
- [Bytecode VM](https://github.com/santhosharulsamy/sandy/blob/main/sandy/vm.py): `sandy/vm.py`
- [C Backend](https://github.com/santhosharulsamy/sandy/blob/main/sandy/cbackend.py): `sandy/cbackend.py`
- [Runtime Values](https://github.com/santhosharulsamy/sandy/blob/main/sandy/values.py): `sandy/values.py`

### Language Ecosystem

- [Built-ins](https://github.com/santhosharulsamy/sandy/blob/main/sandy/builtins.py): `sandy/builtins.py`
- [Concurrency](https://github.com/santhosharulsamy/sandy/blob/main/sandy/concurrency.py): `sandy/concurrency.py`
- [Standard Library](https://github.com/santhosharulsamy/sandy/tree/main/sandy/stdlib): `sandy/stdlib`
- [Package System](https://github.com/santhosharulsamy/sandy/blob/main/sandy/packages.py): `sandy/packages.py`
- [Registry Server](https://github.com/santhosharulsamy/sandy/blob/main/sandy/registry_server.py): `sandy/registry_server.py`

### Developer Tools

- [Formatter](https://github.com/santhosharulsamy/sandy/blob/main/sandy/formatter.py): `sandy/formatter.py`
- [Language Server](https://github.com/santhosharulsamy/sandy/blob/main/sandy/lsp.py): `sandy/lsp.py`
- [Interactive REPL](https://github.com/santhosharulsamy/sandy/blob/main/sandy/repl.py): `sandy/repl.py`
- [Browser Playground](https://github.com/santhosharulsamy/sandy/blob/main/web/playground.html): `web/playground.html`

### Program Entry

- [CLI](https://github.com/santhosharulsamy/sandy/blob/main/sandy/cli.py): `sandy/cli.py`
- [Runtime Orchestrator](https://github.com/santhosharulsamy/sandy/blob/main/sandy/runtime.py): `sandy/runtime.py`

### Other components

- **Program Author**
- **C Compiler**

## Connections

- Program Author → CLI: runs program (evidence: `README.md`)
- CLI → Runtime Orchestrator: dispatches execution (evidence: `sandy/cli.py`)
- Runtime Orchestrator → Lexer: tokenizes source (evidence: `sandy/runtime.py`)
- Lexer → Tokens: emits tokens (evidence: `sandy/lexer.py`)
- Runtime Orchestrator → Parser: parses tokens (evidence: `sandy/runtime.py`)
- Parser → AST Nodes: builds AST (evidence: `sandy/parser.py`)
- Runtime Orchestrator → Type Checker: checks types (evidence: `sandy/runtime.py`)
- Runtime Orchestrator → Tree Interpreter: runs AST (evidence: `sandy/runtime.py`)
- Runtime Orchestrator → Bytecode Compiler: compiles program (evidence: `sandy/runtime.py`)
- Bytecode Compiler → Bytecode: emits instructions (evidence: `sandy/compiler.py`)
- Runtime Orchestrator → Bytecode VM: executes bytecode (evidence: `sandy/runtime.py`)
- Runtime Orchestrator → C Backend: generates native code (evidence: `sandy/runtime.py`)
- C Backend → C Compiler: invokes compiler
- Tree Interpreter → Runtime Values: uses values (evidence: `sandy/interpreter.py`)
- Tree Interpreter → Built-ins: dispatches built-ins (evidence: `sandy/interpreter.py`)
- Built-ins → Concurrency: provides concurrency (evidence: `sandy/builtins.py`)
- Bytecode VM → Tree Interpreter: reuses runtime behavior (evidence: `sandy/vm.py`)
- Bytecode VM → Runtime Values: uses values (evidence: `sandy/vm.py`)
- Tree Interpreter → Package System: loads modules (evidence: `sandy/interpreter.py`)
- Package System → Registry Server: serves packages (evidence: `sandy/packages.py`)
- CLI → Interactive REPL: starts REPL (evidence: `sandy/cli.py`)
- CLI → Formatter: formats source (evidence: `sandy/cli.py`)
- CLI → Language Server: starts language server (evidence: `sandy/cli.py`)
- Language Server → Lexer: uses lexer (evidence: `sandy/lsp.py`)
- Language Server → Parser: uses parser (evidence: `sandy/lsp.py`)
- Language Server → Type Checker: checks diagnostics (evidence: `sandy/lsp.py`)
- Language Server → Formatter: formats documents (evidence: `sandy/lsp.py`)
- Program Author → Browser Playground: tries language (evidence: `README.md`)
- Browser Playground → Runtime Orchestrator: runs implementation (evidence: `README.md`)
