# elfrask/cls architecture

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

- Interactive diagram: https://gitdiagram.com/elfrask/cls
- Repository: https://github.com/elfrask/cls

## Overview

#### Purpose and Entrypoints
CLS 2.0 is a Rust workspace implementing a modular CLS language toolchain: parse/type-check source, interpret it, package applications, and provide editor integration. User-facing binaries are `clx` (development CLI, including LSP) and `clxr` (runtime executor): `nodos/clx/src/main.rs`, `nodos/clxr/src/main.rs`.

#### Language Core: Frontend and AST
`cls-core` is the pure language layer, deliberately separated from host filesystem/I/O. Source text is tokenized, parsed, and represented as an AST by `cls-core/src/frontend/lexer.rs`, `cls-core/src/frontend/parser.rs`, and `cls-core/src/frontend/ast.rs`. Shared diagnostics and source-span reporting are defined under `cls-core/src/error/diagnostic.rs`.

#### Semantic Middleware Pipeline
Parsed ASTs pass through name resolution, static type checking, and optimization before execution or output generation. These stages are `cls-core/src/middleware/resolver.rs`, `cls-core/src/middleware/typeck.rs`, and `cls-core/src/middleware/optimizer.rs`. This establishes the central control flow: `.clsx` source → frontend AST → semantic passes → runtime interpreter or backend.

#### Backends and Build Outputs
The core exposes alternate AST consumers: JSON serialization/dumps and a planned WASM compilation target, rooted at `cls-core/src/backend/json.rs` and `cls-core/src/backend/wasm.rs`. CLI build behavior is hosted in `nodos/clx/src/subcommands/build.rs`; WASM/.clbin generation is explicitly future-facing rather than the primary current execution path.

#### Runtime Execution Model
`cls-runtime` executes ASTs with a tree-walking interpreter. Runtime values, lexical/scoped bindings, garbage collection, intrinsics, and error reporting are separated into `cls-runtime/src/interpreter.rs`, `cls-runtime/src/value.rs`, and `cls-runtime/src/environment.rs`. The runtime does not own direct host I/O; host capabilities are supplied through its API/FFI boundary in `cls-runtime/src/host_api.rs` and `cls-runtime/src/ffi.rs`.

#### Modules, Standard Library, and Security
Imports resolve through runtime module resolution and bundled CLS interface definitions: `cls-runtime/src/resolver.rs`, `cls-runtime/src/modules.rs`, and `cls-runtime/clsi/`. Built-in math, JSON, async, and primitive functionality live under `cls-runtime/src/stdlib/`. Sandbox policy and protocol-based virtual filesystem access are runtime boundaries in `cls-runtime/src/sandbox.rs`, `cls-runtime/src/vfs/resolver.rs`, and `cls-runtime/src/vfs/security.rs`.

#### Host Nodes and External Services
`clx` supplies desktop integrations that core/runtime intentionally exclude: command dispatch, filesystem and HTTP modules, package actions, and LSP. Key boundaries are `nodos/clx/src/subcommands/run.rs`, `nodos/clx/src/modules/fs.rs`, `nodos/clx/src/modules/http.rs`, and `nodos/clx/src/lsp.rs`. The LSP communicates over stdio or TCP; filesystem and network access are mediated by these node-provided modules and runtime sandbox permissions. Project manifests/configuration are parsed by `cls-core/src/config/manifest.rs`, with `cls.json` serving as the project entry/configuration contract.

Main entry points: [`cls-runtime/src/interpreter.rs`](https://github.com/elfrask/cls/blob/master/cls-runtime/src/interpreter.rs) (Tree-walking interpreter), [`cls-core/src/middleware/resolver.rs`](https://github.com/elfrask/cls/blob/master/cls-core/src/middleware/resolver.rs) (Semantic pipeline), [`nodos/clx/src/main.rs`](https://github.com/elfrask/cls/blob/master/nodos/clx/src/main.rs) (clx development CLI), [`cls-core/src/frontend/parser.rs`](https://github.com/elfrask/cls/blob/master/cls-core/src/frontend/parser.rs) (Lexer, parser & AST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Language Core"]
  node_manifest["Project manifest<br/>configuration parser<br/>[manifest.rs]"]
  node_frontend["Lexer, parser &amp; AST<br/>frontend<br/>[parser.rs]"]
  node_diagnostics["Diagnostics<br/>error reporting<br/>[diagnostic.rs]"]
  node_semantic["Semantic pipeline<br/>[resolver.rs]"]
  node_json_backend["JSON backend<br/>AST serializer<br/>[json.rs]"]
  node_wasm_backend["WASM backend<br/>planned compiler target<br/>[wasm.rs]"]
end

subgraph group_runtime["Runtime"]
  node_interpreter["Tree-walking interpreter<br/>AST executor<br/>[interpreter.rs]"]
  node_runtime_state["Values &amp; environments<br/>runtime state<br/>[environment.rs]"]
  node_host_boundary["Host API &amp; FFI<br/>capability boundary<br/>[host_api.rs]"]
  node_module_system["Modules &amp; CLS interfaces<br/>module resolution<br/>[resolver.rs]"]
  node_stdlib["Standard library<br/>built-ins"]
  node_sandbox["Sandboxed VFS<br/>security boundary<br/>[sandbox.rs]"]
end

subgraph group_hosts["Host Nodes"]
  node_clx{{"clx development CLI<br/>user-facing binary<br/>[main.rs]"}}
  node_run_command["Run command<br/>CLI subcommand<br/>[run.rs]"]
  node_build_command["Build command<br/>CLI subcommand<br/>[build.rs]"]
  node_host_modules["Filesystem &amp; HTTP modules<br/>desktop integrations<br/>[fs.rs]"]
  node_lsp["Language server<br/>editor integration<br/>[lsp.rs]"]
  node_clxr{{"clxr runtime executor<br/>user-facing binary<br/>[main.rs]"}}
end

node_source[".clsx source<br/>language input"]

node_source -->|"tokenize / parse"| node_frontend
node_frontend -->|"source errors"| node_diagnostics
node_frontend -->|"AST"| node_semantic
node_semantic -->|"semantic errors"| node_diagnostics
node_semantic -->|"checked AST"| node_interpreter
node_semantic -->|"serialize"| node_json_backend
node_semantic -.->|"compile target"| node_wasm_backend
node_interpreter -->|"evaluates with"| node_runtime_state
node_interpreter -->|"resolves imports"| node_module_system
node_module_system -->|"loads built-ins"| node_stdlib
node_interpreter -->|"requests capabilities"| node_host_boundary
node_host_boundary -->|"permission-controlled access"| node_sandbox
node_clx -->|"dispatches"| node_run_command
node_clx -->|"dispatches"| node_build_command
node_clx -->|"serves"| node_lsp
node_run_command -->|"loads source"| node_frontend
node_run_command -->|"runs"| node_interpreter
node_build_command -->|"emits"| node_json_backend
node_build_command -.->|"future output"| node_wasm_backend
node_host_modules -->|"implements host API"| node_host_boundary
node_clx -->|"provides"| node_host_modules
node_clxr -->|"executes"| node_interpreter
node_manifest -->|"project configuration"| node_clx

click node_manifest "https://github.com/elfrask/cls/blob/master/cls-core/src/config/manifest.rs"
click node_frontend "https://github.com/elfrask/cls/blob/master/cls-core/src/frontend/parser.rs"
click node_diagnostics "https://github.com/elfrask/cls/blob/master/cls-core/src/error/diagnostic.rs"
click node_semantic "https://github.com/elfrask/cls/blob/master/cls-core/src/middleware/resolver.rs"
click node_json_backend "https://github.com/elfrask/cls/blob/master/cls-core/src/backend/json.rs"
click node_wasm_backend "https://github.com/elfrask/cls/blob/master/cls-core/src/backend/wasm.rs"
click node_interpreter "https://github.com/elfrask/cls/blob/master/cls-runtime/src/interpreter.rs"
click node_runtime_state "https://github.com/elfrask/cls/blob/master/cls-runtime/src/environment.rs"
click node_host_boundary "https://github.com/elfrask/cls/blob/master/cls-runtime/src/host_api.rs"
click node_module_system "https://github.com/elfrask/cls/blob/master/cls-runtime/src/resolver.rs"
click node_sandbox "https://github.com/elfrask/cls/blob/master/cls-runtime/src/sandbox.rs"
click node_clx "https://github.com/elfrask/cls/blob/master/nodos/clx/src/main.rs"
click node_run_command "https://github.com/elfrask/cls/blob/master/nodos/clx/src/subcommands/run.rs"
click node_build_command "https://github.com/elfrask/cls/blob/master/nodos/clx/src/subcommands/build.rs"
click node_host_modules "https://github.com/elfrask/cls/blob/master/nodos/clx/src/modules/fs.rs"
click node_lsp "https://github.com/elfrask/cls/blob/master/nodos/clx/src/lsp.rs"
click node_clxr "https://github.com/elfrask/cls/blob/master/nodos/clxr/src/main.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_manifest,node_frontend,node_diagnostics,node_semantic,node_json_backend,node_wasm_backend toneBlue
class node_interpreter,node_runtime_state,node_host_boundary,node_module_system,node_stdlib,node_sandbox toneAmber
class node_clx,node_run_command,node_build_command,node_host_modules,node_lsp,node_clxr toneMint
class node_source toneNeutral
```

## Components

### Language Core

Pure parsing, diagnostics, and semantic processing.

- [Project manifest](https://github.com/elfrask/cls/blob/master/cls-core/src/config/manifest.rs): configuration parser · Parses the cls.json project contract. · `cls-core/src/config/manifest.rs`
- [Lexer, parser & AST](https://github.com/elfrask/cls/blob/master/cls-core/src/frontend/parser.rs): frontend · Converts source text into an AST. · `cls-core/src/frontend/parser.rs`
- [Diagnostics](https://github.com/elfrask/cls/blob/master/cls-core/src/error/diagnostic.rs): error reporting · Shared source spans and diagnostics. · `cls-core/src/error/diagnostic.rs`
- [Semantic pipeline](https://github.com/elfrask/cls/blob/master/cls-core/src/middleware/resolver.rs): resolver / type checker / optimizer · Resolves names, checks types, and optimizes ASTs. · `cls-core/src/middleware/resolver.rs`
- [JSON backend](https://github.com/elfrask/cls/blob/master/cls-core/src/backend/json.rs): AST serializer · `cls-core/src/backend/json.rs`
- [WASM backend](https://github.com/elfrask/cls/blob/master/cls-core/src/backend/wasm.rs): planned compiler target · Future-facing WASM and .clbin output path. · `cls-core/src/backend/wasm.rs`

### Runtime

AST execution and controlled host capabilities.

- [Tree-walking interpreter](https://github.com/elfrask/cls/blob/master/cls-runtime/src/interpreter.rs): AST executor · `cls-runtime/src/interpreter.rs`
- [Values & environments](https://github.com/elfrask/cls/blob/master/cls-runtime/src/environment.rs): runtime state · Runtime values and lexical scoped bindings. · `cls-runtime/src/environment.rs`
- [Host API & FFI](https://github.com/elfrask/cls/blob/master/cls-runtime/src/host_api.rs): capability boundary · Supplies host capabilities without direct runtime I/O. · `cls-runtime/src/host_api.rs`
- [Modules & CLS interfaces](https://github.com/elfrask/cls/blob/master/cls-runtime/src/resolver.rs): module resolution · Resolves imports and bundled interface definitions. · `cls-runtime/src/resolver.rs`
- **Standard library**: built-ins · Math, JSON, async, and primitive functionality.
- [Sandboxed VFS](https://github.com/elfrask/cls/blob/master/cls-runtime/src/sandbox.rs): security boundary · Enforces policy for protocol-based filesystem access. · `cls-runtime/src/sandbox.rs`

### Host Nodes

User-facing CLI, runtime launcher, and editor integration.

- [clx development CLI](https://github.com/elfrask/cls/blob/master/nodos/clx/src/main.rs): user-facing binary · Dispatches development commands, packages, and host modules. · `nodos/clx/src/main.rs`
- [Run command](https://github.com/elfrask/cls/blob/master/nodos/clx/src/subcommands/run.rs): CLI subcommand · `nodos/clx/src/subcommands/run.rs`
- [Build command](https://github.com/elfrask/cls/blob/master/nodos/clx/src/subcommands/build.rs): CLI subcommand · Drives alternate build outputs. · `nodos/clx/src/subcommands/build.rs`
- [Filesystem & HTTP modules](https://github.com/elfrask/cls/blob/master/nodos/clx/src/modules/fs.rs): desktop integrations · Host-provided filesystem and network capabilities. · `nodos/clx/src/modules/fs.rs`
- [Language server](https://github.com/elfrask/cls/blob/master/nodos/clx/src/lsp.rs): editor integration · Serves LSP over stdio or TCP. · `nodos/clx/src/lsp.rs`
- [clxr runtime executor](https://github.com/elfrask/cls/blob/master/nodos/clxr/src/main.rs): user-facing binary · `nodos/clxr/src/main.rs`

### Other components

- **.clsx source**: language input

## Connections

- .clsx source → Lexer, parser & AST: tokenize / parse
- Lexer, parser & AST → Diagnostics: source errors
- Lexer, parser & AST → Semantic pipeline: AST
- Semantic pipeline → Diagnostics: semantic errors
- Semantic pipeline → Tree-walking interpreter: checked AST
- Semantic pipeline → JSON backend: serialize
- Semantic pipeline → WASM backend: compile target
- Tree-walking interpreter → Values & environments: evaluates with
- Tree-walking interpreter → Modules & CLS interfaces: resolves imports
- Modules & CLS interfaces → Standard library: loads built-ins
- Tree-walking interpreter → Host API & FFI: requests capabilities
- Host API & FFI → Sandboxed VFS: permission-controlled access
- clx development CLI → Run command: dispatches
- clx development CLI → Build command: dispatches
- clx development CLI → Language server: serves
- Run command → Lexer, parser & AST: loads source
- Run command → Tree-walking interpreter: runs
- Build command → JSON backend: emits
- Build command → WASM backend: future output
- Filesystem & HTTP modules → Host API & FFI: implements host API
- clx development CLI → Filesystem & HTTP modules: provides
- clxr runtime executor → Tree-walking interpreter: executes
- Project manifest → clx development CLI: project configuration