# nhat-tien/angi architecture

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

- Interactive diagram: https://gitdiagram.com/nhat-tien/angi
- Repository: https://github.com/nhat-tien/angi

## Overview

##### Project type and purpose
- Angi is a custom, statically-typed scripting language + code-generation tool for backend services.
- It’s implemented as a Cargo workspace with four main crates:
- angi (CLI + compiler front-end)
- instructions (instruction-set definitions & macros)
- vm (Angi Virtual Machine runtime)
- server (binary builder & HTTP entrypoint)
- It takes `.ag` source files, compiles them to bytecode, embeds that bytecode into a Rust server binary (with VM), and outputs a production-ready executable.

##### File structure
- Top‐level folders:
- angi/ (Cli + compiler modules under `src/command` & `src/compiler`)
- instructions/ (macros, instruction definitions)
- vm/ (value representations, VM logic under `src/vm.rs`)
- server/ (`main.rs` that ties VM + HTTP routes together)
- examples/, book/, CI workflows, Cargo.toml workspaces
- Within `angi/src/compiler` you see a classic compiler pipeline:
lexer.rs → parser.rs → ast.rs → optimization.rs → code_gen.rs → emits `.bytecode`

##### README’s architecture section
- Confirms the two-stage build: compile `.ag` → bytecode → inject into prebuilt binary → final executable

##### Main components & interactions (to include
a. Components
- Client input: `.ag` source file
- CLI & Compiler front-end (`angi` crate)
- Instruction definitions (`instructions` crate)
- Bytecode artifact (`.bytecode`)
- VM runtime (`vm` crate / AVM)
- Server scaffold (`server` crate)
- Final production binary
b. Relationships / Data flow
1. `.ag` → CLI (`build` or `debug` command)
2. CLI invokes compiler submodules in order:
– lexer → parser → AST → optimizer → code generator
3. Compiler emits `.bytecode`
4. Server crate + VM crate + bytecode are linked/injected into a pre-built Rust binary
5. Result: `binary_output` ready to run HTTP routes defined in `.ag`
c. Architectural patterns
– Pipeline architecture for compiler stages
– Clear compile-time vs run-time separation
– Cargo workspace for modular crates
– Plugin-style instruction definitions shared by compiler & VM
– AOT bytecode injection into server binary
d. Key technologies / libs
– Rust & Cargo workspaces
– Mer modules in `angi/src/command` for CLI commands
– `instructions::macros` to define VM opcodes
– `vm::vm.rs` for register-based VM execution
– `server::main.rs` to wire up HTTP & VM

- Source → Compiler → Bytecode → Linker → Final Binary
- Compile-time crates (e.g., blue rectangles)
- Run-time crates (e.g., green rectangles)

##### Capturing essential details
- Don’t omit the `instructions` crate—its macro definitions are critical glue
- Compiler submodules (lexer, parser, AST, optimizer, codegen) to reflect internal structure
- Call out the `server` crate’s role in bootstrapping HTTP routes

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compile-time phase
    subgraph "Compile-time" 
        direction TB
        Source[".ag Source File"]:::artifact
        CLI["CLI Entry (main.rs)"]:::compileTime
        Command["Command Router (command.rs)"]:::compileTime
        BuildCmd["Build Command"]:::compileTime
        DebugCmd["Debug Command"]:::compileTime
        subgraph "Compiler Pipeline"
            direction TB
            Lexer["Lexer"]:::compileTime
            Parser["Parser"]:::compileTime
            AST["AST"]:::compileTime
            Optimizer["Optimizer"]:::compileTime
            CodeGen["Code Generator"]:::compileTime
        end
        Source -->|"invoke"| CLI
        CLI --> Command
        Command --> BuildCmd
        Command --> DebugCmd
        BuildCmd --> Lexer
        DebugCmd --> Lexer
        Lexer --> Parser
        Parser --> AST
        AST --> Optimizer
        Optimizer --> CodeGen
        CodeGen --> Bytecode
    end

    %% Instruction Definitions shared
    subgraph "Instruction Definitions" 
        direction TB
        InstrLib["instructions::lib"]:::compileTime
        InstrMacros["instructions::macros"]:::compileTime
    end
    CodeGen --> InstrLib
    InstrLib --> InstrMacros
    InstrLib ----> VM
    InstrLib ----> CodeGen

    %% Artifact
    Bytecode[".bytecode (Bytecode Artifact)"]:::artifact
    click Bytecode "https://github.com/nhat-tien/angi/blob/main/examples/main.bc"

    %% Linking phase
    subgraph "Link & Build"
        direction TB
        Linker["AOT Bytecode Injection"]:::compileTime
        FinalBinary["Final Server Binary"]:::artifact
    end
    Bytecode --> Linker
    Linker --> FinalBinary

    %% Run-time phase
    subgraph "Run-time"
        direction TB
        subgraph "VM Runtime"
            direction TB
            VM["VM Core (vm.rs)"]:::runtime
            Register["Register"]:::runtime
            Value["Value"]:::runtime
            VList["Value List"]:::runtime
            VTable["Value Table"]:::runtime
            Constant["Constant"]:::runtime
            Error["Error"]:::runtime
            Metadata["Metadata"]:::runtime
            Tree["Tree"]:::runtime
            Utils["Utils"]:::runtime
        end
        subgraph "Server"
            direction TB
            ServerMain["Server Entrypoint"]:::runtime
        end
        FinalBinary --> ServerMain
        ServerMain --> VM
    end

    %% Click events for CLI & Compiler Front-end
    click CLI "https://github.com/nhat-tien/angi/blob/main/angi/src/main.rs"
    click Command "https://github.com/nhat-tien/angi/blob/main/angi/src/command.rs"
    click BuildCmd "https://github.com/nhat-tien/angi/blob/main/angi/src/command/build.rs"
    click DebugCmd "https://github.com/nhat-tien/angi/blob/main/angi/src/command/debug.rs"
    click Lexer "https://github.com/nhat-tien/angi/blob/main/angi/src/compiler/lexer.rs"
    click Parser "https://github.com/nhat-tien/angi/blob/main/angi/src/compiler/parser.rs"
    click AST "https://github.com/nhat-tien/angi/blob/main/angi/src/compiler/ast.rs"
    click Optimizer "https://github.com/nhat-tien/angi/blob/main/angi/src/compiler/optimization.rs"
    click CodeGen "https://github.com/nhat-tien/angi/blob/main/angi/src/compiler/code_gen.rs"
    click InstrLib "https://github.com/nhat-tien/angi/blob/main/instructions/src/lib.rs"
    click InstrMacros "https://github.com/nhat-tien/angi/blob/main/instructions/src/macros.rs"
    click VM "https://github.com/nhat-tien/angi/blob/main/vm/src/vm.rs"
    click Register "https://github.com/nhat-tien/angi/blob/main/vm/src/register.rs"
    click Value "https://github.com/nhat-tien/angi/blob/main/vm/src/value.rs"
    click VList "https://github.com/nhat-tien/angi/blob/main/vm/src/value/list.rs"
    click VTable "https://github.com/nhat-tien/angi/blob/main/vm/src/value/table.rs"
    click Constant "https://github.com/nhat-tien/angi/blob/main/vm/src/constant.rs"
    click Error "https://github.com/nhat-tien/angi/blob/main/vm/src/error.rs"
    click Metadata "https://github.com/nhat-tien/angi/blob/main/vm/src/metadata.rs"
    click Tree "https://github.com/nhat-tien/angi/blob/main/vm/src/tree.rs"
    click Utils "https://github.com/nhat-tien/angi/blob/main/vm/src/utils.rs"
    click ServerMain "https://github.com/nhat-tien/angi/blob/main/server/src/main.rs"
    click ServerMain "https://github.com/nhat-tien/angi/blob/main/server/Cargo.toml"

    %% Styles
    classDef compileTime fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef runtime fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef artifact fill:#fff3cd,stroke:#333,stroke-width:1px;
```
