# huhm-cc/russd-core architecture

> Architecture diagram of the GitHub repository huhm-cc/russd-core, 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/huhm-cc/russd-core
- Repository: https://github.com/huhm-cc/russd-core

## Overview

Russd is a statically typed, Rust-like language with an optimizing compiler and a safe bytecode VM; its documented workflow is to run, check, optimize, or inspect Russd source through the CLI. The graph also preserves the separate Next.js documentation site and its localized guides, configuration, core-download, and open-source pages. Core compilation calls are visible in the library façade; some CLI and bytecode-stage wiring is documented but not shown in the excerpts, so those links are marked unverified.

Main entry points: [`crates/russd-lang/src/loader.rs`](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/loader.rs) (Source loader), [`crates/russd-lang/src/check.rs`](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/check.rs) (Type and borrow checker), [`crates/russd-lang/src/interp.rs`](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/interp.rs) (VM and interpreter), [`crates/russd-lang/src/parser.rs`](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/parser.rs) (Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and loading"]
  node_cli["Command-line interface<br/>[main.rs]"]
  node_loader["Source loader<br/>[loader.rs]"]
end

subgraph group_language["Language front end"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_tokens["Token model<br/>[token.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_ast["Syntax tree<br/>[ast.rs]"]
  node_checker["Type and borrow checker<br/>[check.rs]"]
  node_types["Type definitions<br/>[types.rs]"]
  node_diagnostics["Diagnostics<br/>[diag.rs]"]
end

subgraph group_compiler["Compiler and runtime"]
  node_optimizer["AST optimizer<br/>[opt.rs]"]
  node_bytecode["Bytecode compiler<br/>[bytecode.rs]"]
  node_vm["VM and interpreter<br/>[interp.rs]"]
  node_sandbox["Runtime sandbox<br/>[sandbox.rs]"]
  node_http["Local HTTP server<br/>[http_server.rs]"]
end

subgraph group_site["Documentation site"]
  node_docs["Documentation pages<br/>[page.tsx]"]
  node_guidecontent["Guide content<br/>[howto-use.ts]"]
  node_configdoc["Configuration guide<br/>[page.tsx]"]
  node_download["Core download page<br/>[page.tsx]"]
  node_opensource["Open-source page<br/>[page.tsx]"]
  node_homepage["Site homepage<br/>[page.tsx]"]
  node_sitecontent["Site content model<br/>[site.ts]"]
end

node_author(("Russd author"))
node_host(("Host environment"))
node_webvisitor(("Documentation reader"))

node_author -->|"runs commands"| node_cli
node_cli -.->|"loads source"| node_loader
node_loader -->|"lexes source"| node_lexer
node_loader -->|"parses tokens"| node_parser
node_loader -->|"checks program"| node_checker
node_loader -->|"optimizes program"| node_optimizer
node_lexer -->|"produces tokens"| node_tokens
node_parser -->|"reads tokens"| node_tokens
node_parser -->|"builds AST"| node_ast
node_checker -->|"checks AST"| node_ast
node_checker -->|"resolves types"| node_types
node_checker -->|"reports errors"| node_diagnostics
node_loader -->|"returns errors"| node_diagnostics
node_optimizer -->|"rewrites AST"| node_ast
node_optimizer -.->|"emits bytecode"| node_bytecode
node_bytecode -->|"runs bytecode"| node_vm
node_vm -.->|"enforces limits"| node_sandbox
node_vm -->|"binds listener"| node_http
node_vm -.->|"uses host services"| node_host
node_webvisitor -->|"reads site"| node_homepage
node_webvisitor -->|"opens guides"| node_docs
node_webvisitor -->|"opens guide"| node_configdoc
node_webvisitor -->|"opens downloads"| node_download
node_webvisitor -->|"reads license"| node_opensource
node_docs -.->|"renders content"| node_guidecontent
node_homepage -.->|"uses site data"| node_sitecontent

click node_cli "https://github.com/huhm-cc/russd-core/blob/main/src/main.rs"
click node_loader "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/loader.rs"
click node_lexer "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/lexer.rs"
click node_tokens "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/token.rs"
click node_parser "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/parser.rs"
click node_ast "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/ast.rs"
click node_checker "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/check.rs"
click node_types "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/types.rs"
click node_diagnostics "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/diag.rs"
click node_optimizer "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/opt.rs"
click node_bytecode "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/bytecode.rs"
click node_vm "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/interp.rs"
click node_sandbox "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/sandbox.rs"
click node_http "https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/http_server.rs"
click node_docs "https://github.com/huhm-cc/russd-core/blob/main/web/src/app/howto-use/%5Blang%5D/page.tsx"
click node_guidecontent "https://github.com/huhm-cc/russd-core/blob/main/web/src/lib/howto-use.ts"
click node_configdoc "https://github.com/huhm-cc/russd-core/blob/main/web/src/app/howto-configuration/%5Blang%5D/page.tsx"
click node_download "https://github.com/huhm-cc/russd-core/blob/main/web/src/app/download-core/%5Blang%5D/page.tsx"
click node_opensource "https://github.com/huhm-cc/russd-core/blob/main/web/src/app/opensource/page.tsx"
click node_homepage "https://github.com/huhm-cc/russd-core/blob/main/web/src/app/page.tsx"
click node_sitecontent "https://github.com/huhm-cc/russd-core/blob/main/web/src/lib/site.ts"

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_loader toneBlue
class node_lexer,node_tokens,node_parser,node_ast,node_checker,node_types,node_diagnostics toneAmber
class node_optimizer,node_bytecode,node_vm,node_sandbox,node_http toneMint
class node_docs,node_guidecontent,node_configdoc,node_download,node_opensource,node_homepage,node_sitecontent toneRose
class node_author,node_host,node_webvisitor toneIndigo
```

## Components

### CLI and loading

- [Command-line interface](https://github.com/huhm-cc/russd-core/blob/main/src/main.rs): `src/main.rs`
- [Source loader](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/loader.rs): `crates/russd-lang/src/loader.rs`

### Language front end

- [Lexer](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/lexer.rs): `crates/russd-lang/src/lexer.rs`
- [Token model](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/token.rs): `crates/russd-lang/src/token.rs`
- [Parser](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/parser.rs): `crates/russd-lang/src/parser.rs`
- [Syntax tree](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/ast.rs): `crates/russd-lang/src/ast.rs`
- [Type and borrow checker](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/check.rs): `crates/russd-lang/src/check.rs`
- [Type definitions](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/types.rs): `crates/russd-lang/src/types.rs`
- [Diagnostics](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/diag.rs): `crates/russd-lang/src/diag.rs`

### Compiler and runtime

- [AST optimizer](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/opt.rs): `crates/russd-lang/src/opt.rs`
- [Bytecode compiler](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/bytecode.rs): `crates/russd-lang/src/bytecode.rs`
- [VM and interpreter](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/interp.rs): `crates/russd-lang/src/interp.rs`
- [Runtime sandbox](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/sandbox.rs): `crates/russd-lang/src/sandbox.rs`
- [Local HTTP server](https://github.com/huhm-cc/russd-core/blob/main/crates/russd-lang/src/http_server.rs): `crates/russd-lang/src/http_server.rs`

### Documentation site

- [Documentation pages](https://github.com/huhm-cc/russd-core/blob/main/web/src/app/howto-use/%5Blang%5D/page.tsx): `web/src/app/howto-use/[lang]/page.tsx`
- [Guide content](https://github.com/huhm-cc/russd-core/blob/main/web/src/lib/howto-use.ts): `web/src/lib/howto-use.ts`
- [Configuration guide](https://github.com/huhm-cc/russd-core/blob/main/web/src/app/howto-configuration/%5Blang%5D/page.tsx): `web/src/app/howto-configuration/[lang]/page.tsx`
- [Core download page](https://github.com/huhm-cc/russd-core/blob/main/web/src/app/download-core/%5Blang%5D/page.tsx): `web/src/app/download-core/[lang]/page.tsx`
- [Open-source page](https://github.com/huhm-cc/russd-core/blob/main/web/src/app/opensource/page.tsx): `web/src/app/opensource/page.tsx`
- [Site homepage](https://github.com/huhm-cc/russd-core/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`
- [Site content model](https://github.com/huhm-cc/russd-core/blob/main/web/src/lib/site.ts): `web/src/lib/site.ts`

### Other components

- **Russd author**
- **Host environment**
- **Documentation reader**

## Connections

- Russd author → Command-line interface: runs commands
- Command-line interface → Source loader: loads source
- Source loader → Lexer: lexes source (evidence: `crates/russd-lang/src/loader.rs`)
- Source loader → Parser: parses tokens (evidence: `crates/russd-lang/src/loader.rs`)
- Source loader → Type and borrow checker: checks program (evidence: `crates/russd-lang/src/loader.rs`)
- Source loader → AST optimizer: optimizes program (evidence: `crates/russd-lang/src/loader.rs`)
- Lexer → Token model: produces tokens (evidence: `crates/russd-lang/src/lexer.rs`)
- Parser → Token model: reads tokens (evidence: `crates/russd-lang/src/parser.rs`)
- Parser → Syntax tree: builds AST (evidence: `crates/russd-lang/src/parser.rs`)
- Type and borrow checker → Syntax tree: checks AST (evidence: `crates/russd-lang/src/check.rs`)
- Type and borrow checker → Type definitions: resolves types (evidence: `crates/russd-lang/src/check.rs`)
- Type and borrow checker → Diagnostics: reports errors (evidence: `crates/russd-lang/src/check.rs`)
- Source loader → Diagnostics: returns errors (evidence: `crates/russd-lang/src/loader.rs`)
- AST optimizer → Syntax tree: rewrites AST (evidence: `crates/russd-lang/src/opt.rs`)
- AST optimizer → Bytecode compiler: emits bytecode
- Bytecode compiler → VM and interpreter: runs bytecode (evidence: `crates/russd-lang/src/bytecode.rs`)
- VM and interpreter → Runtime sandbox: enforces limits (evidence: `crates/russd-lang/src/interp.rs`)
- VM and interpreter → Local HTTP server: binds listener (evidence: `crates/russd-lang/src/interp.rs`)
- VM and interpreter → Host environment: uses host services
- Documentation reader → Site homepage: reads site
- Documentation reader → Documentation pages: opens guides
- Documentation reader → Configuration guide: opens guide
- Documentation reader → Core download page: opens downloads
- Documentation reader → Open-source page: reads license
- Documentation pages → Guide content: renders content
- Site homepage → Site content model: uses site data
