# coderscreative/calibre-lang architecture

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

- Interactive diagram: https://gitdiagram.com/coderscreative/calibre-lang
- Repository: https://github.com/coderscreative/calibre-lang

## Overview

Calibre is a statically typed language with a CLI/REPL, compiler pipeline, stackless bytecode VM, formatter, and language server. The primary workflow takes source through parsing, semantic analysis and type inference, LIR/bytecode preparation, then VM execution; CLI commands also expose checking, testing, and packaging. The README documents the pipeline and major language/runtime capabilities. Sampled excerpts confirm CLI dispatch, parser and formatter behavior, VM construction, and LSP document handling; unsampled subsystem links are limited to documented relationships.

Main entry points: [`calibre/src/lib.rs`](https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/lib.rs) (Engine API), [`crates/vm/src/lib.rs`](https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/lib.rs) (Bytecode VM), [`crates/parser/src/lib.rs`](https://github.com/coderscreative/calibre-lang/blob/master/crates/parser/src/lib.rs) (Lexer and parser), [`crates/mir/src/lib.rs`](https://github.com/coderscreative/calibre-lang/blob/master/crates/mir/src/lib.rs) (Semantic MIR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User tools"]
  node_cli["CLI and REPL<br/>[main.rs]"]
  node_commands["CLI commands<br/>[mod.rs]"]
  node_engine["Engine API<br/>[lib.rs]"]
  node_formatter["Formatter<br/>[lib.rs]"]
end

subgraph group_compiler["Compiler pipeline"]
  node_parser["Lexer and parser<br/>[lib.rs]"]
  node_ast["Syntax AST<br/>[mod.rs]"]
  node_mir["Semantic MIR<br/>[lib.rs]"]
  node_typing["Type inference<br/>[typing.rs]"]
  node_lir["LIR lowering<br/>[lib.rs]"]
end

subgraph group_runtime["Execution runtime"]
  node_vmconvert["Bytecode conversion<br/>[mod.rs]"]
  node_vm["Bytecode VM<br/>[lib.rs]"]
  node_native["Native runtime<br/>[mod.rs]"]
end

subgraph group_editor["Editor services"]
  node_lsp["Language server<br/>[main.rs]"]
  node_lsphandlers["Editor handlers<br/>[handlers.rs]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.rs]"]
end

subgraph group_language["Language support"]
  node_stdlib["Calibre stdlib<br/>[lib.rs]"]
  node_ffi["FFI bindings<br/>[mod.rs]"]
end

node_user(("Language user"))

node_user -->|"runs commands"| node_cli
node_user -->|"formats source"| node_formatter
node_user -->|"connects editor"| node_lsp
node_cli -->|"dispatches"| node_commands
node_commands -->|"runs engine"| node_engine
node_engine -->|"parses source"| node_parser
node_parser -->|"produces AST"| node_ast
node_ast -->|"lowers semantics"| node_mir
node_mir -->|"infers types"| node_typing
node_mir -->|"lowers to LIR"| node_lir
node_lir -->|"prepares bytecode"| node_vmconvert
node_vmconvert -->|"creates VM code"| node_vm
node_engine -->|"executes program"| node_vm
node_vm -->|"calls builtins"| node_native
node_vm -.->|"bridges externs"| node_ffi
node_engine -->|"loads standard library"| node_stdlib
node_formatter -->|"parses input"| node_parser
node_lsp -->|"routes requests"| node_lsphandlers
node_lsphandlers -->|"requests diagnostics"| node_diagnostics
node_lsphandlers -->|"parses documents"| node_parser

click node_cli "https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/main.rs"
click node_commands "https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/commands/mod.rs"
click node_engine "https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/lib.rs"
click node_parser "https://github.com/coderscreative/calibre-lang/blob/master/crates/parser/src/lib.rs"
click node_ast "https://github.com/coderscreative/calibre-lang/blob/master/crates/parser/src/ast/mod.rs"
click node_mir "https://github.com/coderscreative/calibre-lang/blob/master/crates/mir/src/lib.rs"
click node_typing "https://github.com/coderscreative/calibre-lang/blob/master/crates/mir/src/typing.rs"
click node_lir "https://github.com/coderscreative/calibre-lang/blob/master/crates/lir/src/lib.rs"
click node_vmconvert "https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/conversion/mod.rs"
click node_vm "https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/lib.rs"
click node_native "https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/native/stdlib/mod.rs"
click node_stdlib "https://github.com/coderscreative/calibre-lang/blob/master/crates/std/src/lib.rs"
click node_ffi "https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/value/ffi/mod.rs"
click node_formatter "https://github.com/coderscreative/calibre-lang/blob/master/fmt/src/lib.rs"
click node_lsp "https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/main.rs"
click node_lsphandlers "https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/features/handlers.rs"
click node_diagnostics "https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/features/diagnostics.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_cli,node_commands,node_engine,node_formatter,node_user toneBlue
class node_parser,node_ast,node_mir,node_typing,node_lir toneAmber
class node_vmconvert,node_vm,node_native toneMint
class node_lsp,node_lsphandlers,node_diagnostics toneRose
class node_stdlib,node_ffi toneIndigo
```

## Components

### User tools

- [CLI and REPL](https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/main.rs): `calibre/src/main.rs`
- [CLI commands](https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/commands/mod.rs): `calibre/src/commands/mod.rs`
- [Engine API](https://github.com/coderscreative/calibre-lang/blob/master/calibre/src/lib.rs): `calibre/src/lib.rs`
- [Formatter](https://github.com/coderscreative/calibre-lang/blob/master/fmt/src/lib.rs): `fmt/src/lib.rs`

### Compiler pipeline

- [Lexer and parser](https://github.com/coderscreative/calibre-lang/blob/master/crates/parser/src/lib.rs): `crates/parser/src/lib.rs`
- [Syntax AST](https://github.com/coderscreative/calibre-lang/blob/master/crates/parser/src/ast/mod.rs): `crates/parser/src/ast/mod.rs`
- [Semantic MIR](https://github.com/coderscreative/calibre-lang/blob/master/crates/mir/src/lib.rs): `crates/mir/src/lib.rs`
- [Type inference](https://github.com/coderscreative/calibre-lang/blob/master/crates/mir/src/typing.rs): `crates/mir/src/typing.rs`
- [LIR lowering](https://github.com/coderscreative/calibre-lang/blob/master/crates/lir/src/lib.rs): `crates/lir/src/lib.rs`

### Execution runtime

- [Bytecode conversion](https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/conversion/mod.rs): `crates/vm/src/conversion/mod.rs`
- [Bytecode VM](https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/lib.rs): `crates/vm/src/lib.rs`
- [Native runtime](https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/native/stdlib/mod.rs): `crates/vm/src/native/stdlib/mod.rs`

### Editor services

- [Language server](https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/main.rs): `lsp/src/main.rs`
- [Editor handlers](https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/features/handlers.rs): `lsp/src/features/handlers.rs`
- [Diagnostics](https://github.com/coderscreative/calibre-lang/blob/master/lsp/src/features/diagnostics.rs): `lsp/src/features/diagnostics.rs`

### Language support

- [Calibre stdlib](https://github.com/coderscreative/calibre-lang/blob/master/crates/std/src/lib.rs): `crates/std/src/lib.rs`
- [FFI bindings](https://github.com/coderscreative/calibre-lang/blob/master/crates/vm/src/value/ffi/mod.rs): `crates/vm/src/value/ffi/mod.rs`

### Other components

- **Language user**

## Connections

- Language user → CLI and REPL: runs commands
- Language user → Formatter: formats source
- Language user → Language server: connects editor
- CLI and REPL → CLI commands: dispatches
- CLI commands → Engine API: runs engine
- Engine API → Lexer and parser: parses source
- Lexer and parser → Syntax AST: produces AST
- Syntax AST → Semantic MIR: lowers semantics
- Semantic MIR → Type inference: infers types
- Semantic MIR → LIR lowering: lowers to LIR
- LIR lowering → Bytecode conversion: prepares bytecode
- Bytecode conversion → Bytecode VM: creates VM code
- Engine API → Bytecode VM: executes program
- Bytecode VM → Native runtime: calls builtins
- Bytecode VM → FFI bindings: bridges externs
- Engine API → Calibre stdlib: loads standard library
- Formatter → Lexer and parser: parses input
- Language server → Editor handlers: routes requests
- Editor handlers → Diagnostics: requests diagnostics
- Editor handlers → Lexer and parser: parses documents