# soham-metha/virex architecture

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

- Interactive diagram: https://gitdiagram.com/soham-metha/virex
- Repository: https://github.com/soham-metha/virex

## Overview

##### Project type and purpose
- VIREX is neither a simple web app nor a database-backed service. It’s a **toolchain platform** comprising:
- A **compiler front-end** (OCC) for high-level languages (e.g., ORIN) → SASM
- A **SASM assembler** (reads/writes human-readable assembly)
- A **virtual machine (VM)** runtime (VIREX) with a text-UI
- Supporting **core libraries** (univ_*) for file I/O, memory, errors, etc.
- README.md confirms: “any language can compile to SASM” → “runs anywhere VIREX runs.”

##### File structure
- Top-level directories:
- **src/**
– **OCC/** (parser, lexer, AST, codegen, optimizer for ORIN and other front-ends)
– **SASM/** (lexer, parser, AST, binding, expression eval, assembler driver)
– **VM/** (core interpreter loop, UI, vmcalls, assembler integration)
– **libs/** (univ_defs, univ_fileops, univ_hashmap, etc.)
- **include/** (public headers matching each src/*)
- **tools/** (editor themes for syntax highlighting in VS Code, Kitty)
- **examples/** & **tests/** (sample SASM/OCC code, SM binaries)
- **build/** releases of SASM and VIREX binaries
- Config/build scripts: Makefile, install.sh, .github/ci.yml, requirements.txt (Graphviz).

##### README for architectural hints
- README includes three architecture images under **docs/assets/Architecture/**. These show:
- VIREX overall flow
- SASM assembler internals
- SASM components breakdown
- Tech stack: C, GNU Make, Graphviz for AST viz.

##### Main components and interactions
a. **Compiler Front-End (OCC)**
– Sub-components: Lexer → Parser → AST → Inter-code optimizer → Code Generator → SASM output
– Uses “univ_*” core libs for memory, strings, error handling
b. **SASM Assembler**
– Tokenizer → Parser → AST → Binding/Expression Eval → Instruction Encoder → SM binary output
c. **Virtual Machine (VIREX)**
– Loader (reads SM binary) → Fetch-Decode-Execute loop → VM Call dispatch → Host runtime (via univ_fileops, univ_errors, etc.)
– UI Layer: Curses-style TUI windows (CreateWindows(), percent-based layout)
d. **Core Libraries** (shared by OCC, SASM, VM)
e. **Developer Tooling**
– VS Code syntax highlighter (tools/themes/vs_code…)
– AST Visualizer (Graphviz)
f. **External environment**
– User’s shell/terminal (fonts, themes)
– OS (file system, console I/O)

1. **User/Editor** (VS Code, terminal UI)
2. **Tooling** (syntax highlighter plugin, AST viz)
3. **Compilation Pipeline** (OCC → SASM assembler)
4. **Runtime** (VIREX VM)
5. **Shared Libraries** (univ_*)
6. **Host OS**
- Source code (ORIN/SASM) → OCC → SASM file → Assembler → SM binary → VM Loader → VM core
- VM core → vmcalls → Core libs → OS
- User keys in menu → VM UI → VM core
- Blue for Compiler
- Green for Assembler
- Orange for VM runtime
- Gray for shared libs
- Yellow for tooling/editor

##### Architectural patterns & design principles
- **Pipeline architecture**: sequential phases in compiler & assembler
- **Modular layering**: clear separation of front-end, back-end, runtime, and tooling
- **Reusability**: core “univ_” libraries shared by all components
- **Extensibility**: open SASM instruction set and plugin points for new languages (ORIN)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User / Editor Layer
    subgraph "User / Editor"
        VSCode["VS Code"]:::yellow
        Shell["Shell / Terminal"]:::yellow
    end

    %% Tooling Layer
    subgraph "Developer Tooling"
        Syntax["Syntax Highlighter (VS Code)"]:::yellow
        ASTViz["AST Visualizer (Graphviz)"]:::yellow
    end

    %% Compilation Pipeline
    subgraph "Compilation Pipeline"
        subgraph "Compiler Front-End (OCC)"
            O_Lexer["OCC Lexer"]:::blue
            O_Parser["OCC Parser"]:::blue
            O_AST["OCC AST"]:::blue
            O_Opt["Inter-Code Optimizer"]:::blue
            O_CodeGen["Code Generator"]:::blue
            SASMOut["SASM Output"]:::blue
        end
        subgraph "SASM Assembler"
            S_Token["SASM Tokenizer"]:::green
            S_Parser["SASM Parser"]:::green
            S_AST["SASM AST"]:::green
            S_Bind["Binding / Expression Eval"]:::green
            S_Encode["Instruction Encoder"]:::green
            SMBin["SM Binary Output"]:::green
        end
    end

    %% VM Runtime Layer
    subgraph "VM Runtime (VIREX)"
        Loader["Loader"]:::orange
        FDE["Fetch-Decode-Execute Loop"]:::orange
        VMCalls["VM Call Dispatch"]:::orange
        UI["TUI UI Layer"]:::orange
        VMCore["VM Core"]:::orange
    end

    %% Shared Libraries and Host OS
    CoreLibs["Core Libraries (univ_*)"]:::gray
    OS["Host OS"]:::external

    %% Build & CI
    Build["Build & CI"]:::external

    %% Connections
    VSCode -->|"writes source code"| Syntax
    VSCode -->|"edits code"| ASTViz
    Shell -->|"launches VM"| UI

    Syntax -->|"highlights ORIN/SASM"| O_Lexer
    ASTViz -->|"generates DOT AST"| O_AST

    O_Lexer -->|"tokens"| O_Parser
    O_Parser -->|"parse tree"| O_AST
    O_AST -->|"optimize"| O_Opt
    O_Opt -->|"inter-code"| O_CodeGen
    O_CodeGen -->|"SASM file"| SASMOut

    SASMOut -->|"assembly input"| S_Token
    S_Token -->|"tokens"| S_Parser
    S_Parser -->|"AST"| S_AST
    S_AST -->|"bind/eval"| S_Bind
    S_Bind -->|"encode"| S_Encode
    S_Encode -->|"SM binary"| SMBin

    SMBin -->|"load binary"| Loader
    Loader -->|"executes"| FDE
    FDE -->|"dispatch"| VMCalls
    VMCalls -->|"core logic"| VMCore
    VMCore -->|"render"| UI
    VMCore -->|"calls"| CoreLibs
    CoreLibs -->|"system calls"| OS

    Build -->|"build scripts"| SASMOut
    Build -->|"build scripts"| VMCore

    %% Click Events - OCC
    click O_Lexer "https://github.com/soham-metha/virex/blob/main/src/OCC/O_lexer.c"
    click O_Parser "https://github.com/soham-metha/virex/blob/main/src/OCC/O_parser.c"
    click O_AST "https://github.com/soham-metha/virex/blob/main/src/OCC/O_parse_tree.c"
    click O_Opt "https://github.com/soham-metha/virex/blob/main/src/OCC/O_inter_code_optimizer.c"
    click O_CodeGen "https://github.com/soham-metha/virex/blob/main/src/OCC/O_codegenerator.c"
    click SASMOut "https://github.com/soham-metha/virex/blob/main/src/OCC/O_main.c"

    %% Click Events - SASM
    click S_Token "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_tokenizer.c"
    click S_Parser "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_parser.c"
    click S_AST "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_ast.c"
    click S_Bind "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_binding.c"
    click S_Encode "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_instructions.c"
    click SMBin "https://github.com/soham-metha/virex/blob/main/src/SASM/sasm_assembler.c"

    %% Click Events - VM
    click Loader "https://github.com/soham-metha/virex/blob/main/src/VM/virex.c"
    click FDE "https://github.com/soham-metha/virex/blob/main/src/VM/virex.c"
    click VMCalls "https://github.com/soham-metha/virex/blob/main/src/VM/virex_vmcalls.c"
    click UI "https://github.com/soham-metha/virex/blob/main/src/VM/virex_ui.c"
    click VMCore "https://github.com/soham-metha/virex/blob/main/src/VM/virex.c"

    %% Click Events - Core Libs
    click CoreLibs "https://github.com/soham-metha/virex/tree/main/src/libs/"

    %% Click Events - Tooling
    click Syntax "https://github.com/soham-metha/virex/tree/main/tools/themes/vs_code/sasm_syntax_highlight/"
    click ASTViz "https://github.com/soham-metha/virex/blob/main/requirements.txt"

    %% Click Events - Build & CI
    click Build "https://github.com/soham-metha/virex/tree/main/Makefile"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef green fill:#DFF7D8,stroke:#28a745,color:#28a745
    classDef orange fill:#FFE0B2,stroke:#ff8c00,color:#ff8c00
    classDef gray fill:#E0E0E0,stroke:#666,color:#333
    classDef yellow fill:#FFF59D,stroke:#fbc02d,color:#fbc02d
    classDef external fill:#FFFFFF,stroke:#999,color:#555,stroke-dasharray: 5 5
```
