# solaeus/dust architecture

> Architecture diagram of the GitHub repository solaeus/dust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/solaeus/dust
- Repository: https://github.com/solaeus/dust

## Overview

##### Main Components

a) Frontend (Source Processing):
- Lexer (dust-lang/src/lexer.rs)
- Compiler (dust-lang/src/compiler.rs)
- Type System (dust-lang/src/type.rs)

b) Intermediate Representation:
- Chunk (dust-lang/src/chunk.rs)
- Instructions (dust-lang/src/instruction/)
- Constants and Locals

c) Backend (Execution):
- Virtual Machine (dust-lang/src/vm.rs)
- Value System (dust-lang/src/value/)
- Native Functions (dust-lang/src/native_function/)

##### Component Relationships

**Source Code → Lexer → Tokens → Compiler → Chunk → VM → Program Output**

With additional relationships:
- Compiler ↔ Type System (for type checking)
- Compiler → Optimizer (for instruction optimization)
- VM ↔ Native Functions
- VM ↔ Value System

##### Detailed Component Descriptions

a) Lexer Section:
- Zero-copy token generation
- Source code reference preservation

b) Compiler Section:
- Pratt parser component
- Type checking flow
- Optimization phase
- Chunk generation with:
- Bytecode instructions
- Constants list
- Locals list

c) Virtual Machine Section:
- Register stack
- Instruction execution loop
- Value/pointer handling
- Native function integration

**[0-8: OpCode][9-10: Flags][11-13: Local Flags][17-32: Arg1][33-48: Arg2][49-63: Arg3]**

##### Implementation Details to Highlight
- Register-based VM architecture
- Static type checking during compilation
- Zero-copy optimization strategies
- Function compilation into separate chunks

##### Notes Section
A small notes section mentioning:
- Maximum register count (2^16)
- Constant/local limitations
- Type system constraints
- Performance characteristics

Remember to emphasize the three main processing stages (lexing/parsing, compilation, and execution) while showing how the supporting systems (type checking, optimization, native functions) integrate with these primary components.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Main Components
    subgraph Frontend["Source Processing Layer"]
        SRC[Source Code]
        LEX[Lexer]:::frontend
        TOK[Token Handler]:::frontend
        COMP[Compiler]:::frontend
        TYPE[Type System]:::support
        OPT[Optimizer]:::support
        ERR[Error Handler]:::support
        SCOPE[Scope Manager]:::support
    end

    subgraph IR["Intermediate Representation"]
        CHUNK[Chunk]:::ir
        INSTR[Instructions]:::ir
        CONST[Constants]:::ir
        LOCALS[Local Variables]:::ir
    end

    subgraph Backend["Execution Layer"]
        VM[Virtual Machine]:::backend
        VAL[Value System]:::backend
        NATIVE[Native Functions]:::backend
        DIS[Disassembler]:::backend
    end

    %% Relationships
    SRC --> LEX
    LEX --> TOK
    TOK --> COMP
    COMP --> CHUNK
    CHUNK --> VM
    
    %% Frontend Relationships
    COMP <--> TYPE
    COMP --> OPT
    OPT --> CHUNK
    COMP <--> SCOPE
    COMP <--> ERR
    
    %% IR Relationships
    CHUNK --> INSTR
    CHUNK --> CONST
    CHUNK --> LOCALS
    
    %% Backend Relationships
    VM <--> VAL
    VM <--> NATIVE
    VM --> DIS
    
    %% Instruction Format
    subgraph INST_FMT["64-bit Instruction Format"]
        direction TB
        OPCODE["OpCode<br/>(0-8)"]:::fmt
        FLAGS["Flags<br/>(9-10)"]:::fmt
        LFLAGS["Local Flags<br/>(11-13)"]:::fmt
        ARG1["Arg1<br/>(17-32)"]:::fmt
        ARG2["Arg2<br/>(33-48)"]:::fmt
        ARG3["Arg3<br/>(49-63)"]:::fmt
    end

    %% Legend
    subgraph Legend
        L1[Frontend Component]:::frontend
        L2[IR Component]:::ir
        L3[Backend Component]:::backend
        L4[Support System]:::support
        L5[Format Spec]:::fmt
    end

    %% Styles
    classDef frontend fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef ir fill:#90EE90,stroke:#333,stroke-width:2px
    classDef backend fill:#FFE5B4,stroke:#333,stroke-width:2px
    classDef support fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef fmt fill:#F0F0F0,stroke:#333,stroke-width:1px

    %% Click Events
    click LEX "https://github.com/solaeus/dust/blob/dev/dust-lang/src/lexer.rs"
    click COMP "https://github.com/solaeus/dust/blob/dev/dust-lang/src/compiler.rs"
    click TYPE "https://github.com/solaeus/dust/blob/dev/dust-lang/src/type.rs"
    click CHUNK "https://github.com/solaeus/dust/blob/dev/dust-lang/src/chunk.rs"
    click INSTR "https://github.com/solaeus/dust/tree/dev/dust-lang/src/instruction/"
    click VM "https://github.com/solaeus/dust/blob/dev/dust-lang/src/vm.rs"
    click VAL "https://github.com/solaeus/dust/tree/dev/dust-lang/src/value/"
    click NATIVE "https://github.com/solaeus/dust/tree/dev/dust-lang/src/native_function/"
    click OPT "https://github.com/solaeus/dust/blob/dev/dust-lang/src/optimize.rs"
    click TOK "https://github.com/solaeus/dust/blob/dev/dust-lang/src/token.rs"
    click LOCALS "https://github.com/solaeus/dust/blob/dev/dust-lang/src/instruction/define_local.rs"
    click SCOPE "https://github.com/solaeus/dust/blob/dev/dust-lang/src/scope.rs"
    click ERR "https://github.com/solaeus/dust/blob/dev/dust-lang/src/dust_error.rs"
    click DIS "https://github.com/solaeus/dust/blob/dev/dust-lang/src/disassembler.rs"
```
