# rampyaaryans/rampyaaryan architecture

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

- Interactive diagram: https://gitdiagram.com/rampyaaryans/rampyaaryan
- Repository: https://github.com/rampyaaryans/rampyaaryan

## Overview

1. **What this repo is**
   Rampyaaryan is a standalone **C99 interpreter/runtime** for a Hinglish programming language. The core product is a single native executable that can run `.ram` scripts or start an interactive REPL.

2. **Core runtime boundary**
   The architecture is centered in `src/`, which contains the full language engine: `main.c` for process entry, `lexer.c` for tokenizing, `compiler.c` for translating source into bytecode, and `vm.c` for executing that bytecode.

3. **Execution pipeline**
   Source code flows through a classic compiler-to-VM pipeline: **`.ram` source → lexer → compiler → bytecode chunk → virtual machine**. The README’s architecture diagrams and the presence of `chunk.*`, `debug.*`, and `vm.*` confirm this is a bytecode-based interpreter rather than a tree-walking interpreter.

4. **Language runtime model**
   The runtime is split across `value.*`, `object.*`, `table.*`, and `chunk.*`. That suggests a dynamically typed object model with heap-allocated runtime objects, hash-table-backed data structures, and a bytecode container for compiled functions/scripts. `debug.*` supports inspection/disassembly of compiled chunks.

5. **Memory management**
   `memory.*` and the README’s GC description indicate the interpreter manages its own heap with an automatic garbage collector. This is a major architectural boundary: language objects are owned by the VM and reclaimed internally, rather than relying on external runtimes like Python or Node.

6. **Native/builtin function layer**
   `native.*` is the bridge between the language and host capabilities. The README emphasizes a large built-in library covering strings, math, lists, maps, files, types, date/time, system utilities, and higher-order helpers. Architecturally, these are host-side native functions exposed to bytecode as part of the runtime environment.

7. **User-facing language features**
   The language surface is intentionally local-language oriented: keywords like `maano`, `likho`, `agar`, `jab tak`, and `kaam`. The examples and tests show support for variables, control flow, functions, closures, lists, maps, exceptions, classes, enums, file I/O, bitwise ops, and higher-order functions.

8. **Validation and behavioral coverage**
   `tests/e2e/` contains end-to-end `.ram` programs that exercise the language from the outside in. These tests are important because they validate the integrated compiler/VM behavior, not just isolated C modules. The `examples/` directory serves as runnable documentation and regression coverage for common language features.

9. **Documentation subsystem**
   `docs/` is a full static documentation site, including language spec, tutorial, API reference, examples, and changelog. The HTML/CSS/JS files show that documentation is published as GitHub Pages content and is part of the project’s delivery story, not just an afterthought.

10. **Editor and developer tooling**
   `vscode-extension/` packages syntax highlighting, theme files, language configuration, and an extension entrypoint. This is a separate integration layer that improves authoring experience but does not participate in runtime execution.

11. **Packaging and distribution**
   The repo includes multiple installer/distribution channels: `homebrew/`, `scoop/`, `snap/`, `winget/`, `npm/`, and platform install scripts under `scripts/`. Architecturally, this means the same native runtime is packaged for several ecosystems rather than being deployed as a hosted service.

12. **Build and CI**
   `Makefile`, `CMakeLists.txt`, and `.github/workflows/build.yml` define the build/release pipeline. The project is built from source on CI and distributed as platform-specific artifacts, reinforcing that the main deliverable is a compiled binary plus ecosystem packaging.

13. **How to draw the diagram**
   A useful architecture diagram would show: **language source and examples/tests on the left**, the **compiler pipeline and VM in the center**, the **native function layer and GC beneath**, and **docs/editor/package distribution** as supporting subsystems around the core runtime. The key boundary is between **user `.ram` programs** and the **self-contained C runtime** that parses, compiles, executes, and manages memory internally.

Main entry points: [`src/vm.c`](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/vm.c) (VM), [`src/main.c`](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/main.c) (Entry point), [`src/compiler.c`](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/compiler.c) (Compiler), [`src/object.c`](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/object.c) (Objects)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_src_main["Entry point<br/>runtime entry<br/>[main.c]"]
  node_src_lexer["Lexer<br/>tokenizer<br/>[lexer.c]"]
  node_src_compiler["Compiler<br/>[compiler.c]"]
  node_src_chunk["Chunk<br/>bytecode container<br/>[chunk.c]"]
  node_src_vm["VM<br/>bytecode runtime<br/>[vm.c]"]
  node_src_value["Values<br/>dynamic types<br/>[value.c]"]
  node_src_object["Objects<br/>[object.c]"]
  node_src_table["Tables<br/>[table.c]"]
  node_src_memory["Memory<br/>gc allocator<br/>[memory.c]"]
  node_src_native["Builtins<br/>native bridge<br/>[native.c]"]
  node_src_debug["Debug<br/>disassembler<br/>[debug.c]"]
end

subgraph group_content["Language content"]
  node_tests_e2e["E2E tests<br/>integration suite"]
  node_examples_showcase["Examples<br/>sample programs"]
end

subgraph group_delivery["Docs and delivery"]
  node_docs_site["Docs site<br/>static docs<br/>[index.html]"]
  node_vscode_ext["VS Code<br/>editor extension<br/>[extension.js]"]
  node_build_ci["Build CI<br/>build pipeline<br/>[build.yml]"]
  node_cmake_build["CMake<br/>build config<br/>[CMakeLists.txt]"]
  node_packaging["Packaging<br/>distribution<br/>[rampyaaryan.rb]"]
end

node_src_main -->|"loads source"| node_src_lexer
node_src_main -->|"drives compile"| node_src_compiler
node_src_main -->|"runs VM"| node_src_vm
node_src_lexer -->|"tokens"| node_src_compiler
node_src_compiler -->|"emits"| node_src_chunk
node_src_vm -->|"executes"| node_src_chunk
node_src_vm -->|"uses"| node_src_value
node_src_vm -->|"allocates"| node_src_object
node_src_vm -->|"stores"| node_src_table
node_src_vm -->|"gc"| node_src_memory
node_src_vm -->|"calls"| node_src_native
node_src_debug -->|"inspects"| node_src_chunk
node_src_value -->|"wraps"| node_src_object
node_src_object -->|"contains"| node_src_table
node_src_memory -->|"manages"| node_src_object
node_src_memory -->|"tracks"| node_src_value
node_tests_e2e -->|"validates"| node_src_vm
node_examples_showcase -->|"demonstrates"| node_src_vm
node_docs_site -->|"documents"| node_src_compiler
node_docs_site -->|"documents"| node_src_vm
node_vscode_ext -.->|"supports"| node_examples_showcase
node_build_ci -->|"orchestrates"| node_cmake_build
node_cmake_build -->|"builds"| node_src_main
node_packaging -->|"packages"| node_src_main
node_packaging -.->|"released by"| node_build_ci

click node_src_main "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/main.c"
click node_src_lexer "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/lexer.c"
click node_src_compiler "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/compiler.c"
click node_src_chunk "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/chunk.c"
click node_src_vm "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/vm.c"
click node_src_value "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/value.c"
click node_src_object "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/object.c"
click node_src_table "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/table.c"
click node_src_memory "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/memory.c"
click node_src_native "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/native.c"
click node_src_debug "https://github.com/rampyaaryans/rampyaaryan/blob/main/src/debug.c"
click node_tests_e2e "https://github.com/rampyaaryans/rampyaaryan/blob/main/tests/e2e/17_comprehensive.ram"
click node_examples_showcase "https://github.com/rampyaaryans/rampyaaryan/blob/main/examples/20_feature_showcase.ram"
click node_docs_site "https://github.com/rampyaaryans/rampyaaryan/blob/main/docs/index.html"
click node_vscode_ext "https://github.com/rampyaaryans/rampyaaryan/blob/main/vscode-extension/extension.js"
click node_build_ci "https://github.com/rampyaaryans/rampyaaryan/blob/main/.github/workflows/build.yml"
click node_cmake_build "https://github.com/rampyaaryans/rampyaaryan/blob/main/CMakeLists.txt"
click node_packaging "https://github.com/rampyaaryans/rampyaaryan/blob/main/homebrew/rampyaaryan.rb"

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_src_main,node_src_lexer,node_src_compiler,node_src_chunk,node_src_vm,node_src_value,node_src_object,node_src_table,node_src_memory,node_src_native,node_src_debug toneBlue
class node_tests_e2e,node_examples_showcase toneAmber
class node_docs_site,node_vscode_ext,node_build_ci,node_cmake_build,node_packaging toneMint
```

## Components

### Core runtime

C99 language engine and execution pipeline.

- [Entry point](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/main.c): runtime entry · Process startup, CLI handling, and REPL/script dispatch. · `src/main.c`
- [Lexer](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/lexer.c): tokenizer · Converts source text into tokens for the compiler. · `src/lexer.c`
- [Compiler](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/compiler.c): bytecode compiler · Translates parsed language constructs into bytecode chunks. · `src/compiler.c`
- [Chunk](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/chunk.c): bytecode container · Stores compiled bytecode and related constants. · `src/chunk.c`
- [VM](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/vm.c): bytecode runtime · Executes bytecode and drives language behavior. · `src/vm.c`
- [Values](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/value.c): dynamic types · Tagged runtime values used throughout execution. · `src/value.c`
- [Objects](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/object.c): heap objects · Heap-allocated language objects and closures/classes. · `src/object.c`
- [Tables](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/table.c): hash tables · Associative storage for globals, instances, and collections. · `src/table.c`
- [Memory](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/memory.c): gc allocator · Heap allocation and garbage collection management. · `src/memory.c`
- [Builtins](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/native.c): native bridge · Host-side functions exposed to the language runtime. · `src/native.c`
- [Debug](https://github.com/rampyaaryans/rampyaaryan/blob/main/src/debug.c): disassembler · Inspection and disassembly support for bytecode chunks. · `src/debug.c`

### Language content

Runnable programs used to exercise and demonstrate the language.

- [E2E tests](https://github.com/rampyaaryans/rampyaaryan/blob/main/tests/e2e/17_comprehensive.ram): integration suite · End-to-end .ram programs that validate compiler and VM behavior. · `tests/e2e/17_comprehensive.ram`
- [Examples](https://github.com/rampyaaryans/rampyaaryan/blob/main/examples/20_feature_showcase.ram): sample programs · Runnable language examples and feature demonstrations. · `examples/20_feature_showcase.ram`

### Docs and delivery

Documentation, editor integration, packaging, and build/release tooling.

- [Docs site](https://github.com/rampyaaryans/rampyaaryan/blob/main/docs/index.html): static docs · Published documentation site for spec, tutorial, API, and changelog. · `docs/index.html`
- [VS Code](https://github.com/rampyaaryans/rampyaaryan/blob/main/vscode-extension/extension.js): editor extension · Syntax highlighting, themes, and language configuration for the editor. · `vscode-extension/extension.js`
- [Build CI](https://github.com/rampyaaryans/rampyaaryan/blob/main/.github/workflows/build.yml): build pipeline · Source build and release automation for the native runtime. · `.github/workflows/build.yml`
- [CMake](https://github.com/rampyaaryans/rampyaaryan/blob/main/CMakeLists.txt): build config · Cross-platform build configuration for compiling the executable. · `CMakeLists.txt`
- [Packaging](https://github.com/rampyaaryans/rampyaaryan/blob/main/homebrew/rampyaaryan.rb): distribution · Installer and package definitions for multiple ecosystems. · `homebrew/rampyaaryan.rb`

## Connections

- Entry point → Lexer: loads source · Main entry point feeds source into the lexer.
- Entry point → Compiler: drives compile · Main coordinates compilation of script input.
- Entry point → VM: runs VM · Main hands execution over to the virtual machine.
- Lexer → Compiler: tokens · Lexer output is consumed by the compiler.
- Compiler → Chunk: emits · Compiler produces bytecode chunks.
- VM → Chunk: executes · VM reads bytecode from chunks.
- VM → Values: uses · VM manipulates dynamic runtime values.
- VM → Objects: allocates · VM creates and manages heap objects.
- VM → Tables: stores · VM uses hash tables for globals and runtime structures.
- VM → Memory: gc · VM relies on the internal memory manager and collector.
- VM → Builtins: calls · VM exposes native/builtin functionality to programs.
- Debug → Chunk: inspects · Debug utilities disassemble compiled chunks.
- Values → Objects: wraps · Values reference heap objects when needed.
- Objects → Tables: contains · Objects use tables for fields, methods, and maps.
- Memory → Objects: manages · Allocator and GC manage heap objects.
- Memory → Values: tracks · Memory subsystem participates in value/object lifecycle management.
- E2E tests → VM: validates · Integration tests exercise the full compile-and-run pipeline.
- Examples → VM: demonstrates · Examples are runnable programs for the runtime.
- Docs site → Compiler: documents · Docs explain language semantics and usage.
- Docs site → VM: documents · Docs cover execution model and runtime behavior.
- VS Code → Examples: supports · Editor tooling helps author and run sample language code.
- Build CI → CMake: orchestrates · CI uses the build configuration to compile artifacts.
- CMake → Entry point: builds · Build config compiles the native executable from src/.
- Packaging → Entry point: packages · Packaging definitions distribute the compiled runtime.
- Packaging → Build CI: released by · Distribution artifacts are produced through the build pipeline.
