How nhat-tien/angi works
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