# shrehanrajsingh/sharna architecture

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

- Interactive diagram: https://gitdiagram.com/shrehanrajsingh/sharna
- Repository: https://github.com/shrehanrajsingh/sharna

## Overview

##### Project type and purpose
- This is a language‐runtime project: a Virtual Machine (SVM) accompanied by an assembler and a small standard library for a custom instruction set (“Sharna”).
- The assembler (in the /assembler folder) processes `.sp` assembly source into bytecode. The VM (vm.c, cpu/, ram/, rom/, inst/) loads and interprets that bytecode. The lib/std folder provides built-in routines linked into bytecode.

##### File structure
- Top-level CMakeLists.txt drives the build of:
- assembler/ – tokenizer, parser (quickparser), AST, codegen, symbol context.
- cpu/ – core execution loop and CPU state.
- ram/ and rom/ – memory modules.
- inst/ – one source file per instruction implementing the CPU’s decode/execute.
- lib/std/ – Sharna standard library routines in assembly (.sp).
- vm.c/.h – top-level VM harness that binds CPU, memory, I/O.
- tests/ – sample `.sp` programs and a C example showing VM usage.
- Configuration: CMakeLists.txt in root and tests folder.

##### Extract insights from the README
- Assembler examples in tests show usage.
- Standard library is extendable.
- A C compiler targeting SVM bytecode is envisioned but not yet present.

a. Main components
1) CLI / User Interface (driver)
2) Assembler
- Lexer/Tokenizer (tok.c)
- Parser/AST (quickparser.c + ast.c)
- Semantic Context (ctx.c)
- Code generator (codegen.c)
- Output: .svm bytecode
3) Virtual Machine (vm.c)
- Loader (reads bytecode, populates ROM and/or RAM)
- CPU core (cpu.c): fetch‐decode‐execute loop
- Memory modules: ROM (rom.c) and RAM (ram.c)
- Registers (registers.h)
- Instruction implementations under inst/
4) Standard Library (lib/std/*.sp)
5) Tests / Examples (tests/*.sp, test.c)
b. Relationships and interactions
- The user invokes the assembler CLI, passing one or more .sp files.
- Assembler produces a bytecode file.
- VM loader takes bytecode and loads it into ROM (and possibly expands into RAM).
- CPU fetches instructions from memory, decodes via inst/ modules, executes by manipulating registers and memory, and possibly dispatching interrupts (interrupt.c).
- Standard library routines are assembled and linked into the bytecode before execution.
- Tests drive both the assembler and VM in automated runs.
c. Architectural patterns / design principles
- Modular segmentation: each instruction as a separate module in inst/
- Layered design: front-end (assembler) vs. back-end (VM)
- Separation of concerns: parsing vs. codegen vs. execution vs. memory
- Clear interface boundaries: assembler API vs. VM API vs. stdlib
d. Key technologies / frameworks
- C language with modular .c/.h files
- CMake build system
- Custom JSON file for interrupts (INTERRUPTS.json) to drive instruction metadata
- Standard library in assembly (.sp) that the assembler consumes

##### Detailed capture of architecture
- Inst/*.c under “Instruction Set Implementation,” perhaps with a note “one file per opcode.”
- JSON file as a configuration input for instruction metadata.
- Tests hooking into both the assembler CLI and the VM API (test.c uses vm.h).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source Input
    Source["Source (.sp files)"]:::tests

    %% Assembler Stage
    subgraph "Assembler" 
        direction TB
        CLI["CLI / User Interface"]:::assembler
        Lexer["Lexer / Tokenizer"]:::assembler
        Parser["Parser / AST"]:::assembler
        Context["Semantic Context"]:::assembler
        CodeGen["Code Generator"]:::assembler
        Utils["Utilities"]:::assembler
        Config["Configuration / Metadata"]:::config
    end

    %% Bytecode Output
    Bytecode["Bytecode (.svm)"]:::vm

    %% Standard Library
    StdLib["Standard Library (.sp routines)"]:::std

    %% VM Stage
    subgraph "Virtual Machine" 
        direction TB
        Harness["VM Harness"]:::vm
        Loader["Loader"]:::vm
        subgraph "Memory Modules"
            direction TB
            ROM["ROM"]:::memory
            RAM["RAM"]:::memory
        end
        CPU["CPU Core (Fetch-Decode-Execute)"]:::vm
        Registers["Registers Definition"]:::vm
        Inst["Instruction Implementations"]:::vm
    end

    %% Tests
    subgraph "Tests / Examples"
        direction TB
        TestSP["Test .sp Scripts"]:::tests
        TestC["Test Runner (test.c)"]:::tests
    end

    %% Data Flows
    Source -->|" .sp text"| Lexer
    Lexer -->|"tokens"| Parser
    Parser -->|"AST"| Context
    Context -->|"semantically checked AST"| CodeGen
    CodeGen -->|".svm bytecode"| Bytecode
    Config -->|"metadata"| CodeGen
    StdLib -->|"linked routines"| CodeGen

    Bytecode -->|"bytecode file"| Loader
    Loader --> ROM
    Loader --> RAM
    ROM -->|"instruction word"| CPU
    CPU --> Registers
    CPU -->|"execute opcode"| Inst
    Inst --> Registers
    Inst --> RAM

    TestSP -->|"input files"| CLI
    TestC -->|"calls VM API"| Harness

    Harness --> Loader
    Harness --> CPU

    %% Click Events
    click CLI "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/shasm.c"
    click Lexer "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/tok.c"
    click Parser "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/quickparser.c"
    click Context "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/ctx.c"
    click CodeGen "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/codegen.c"
    click Utils "https://github.com/shrehanrajsingh/sharna/blob/main/assembler/strutils.c"
    click Config "https://github.com/shrehanrajsingh/sharna/blob/main/INTERRUPTS.json"
    click Harness "https://github.com/shrehanrajsingh/sharna/blob/main/vm.c"
    click CPU "https://github.com/shrehanrajsingh/sharna/blob/main/cpu/cpu.c"
    click RAM "https://github.com/shrehanrajsingh/sharna/blob/main/ram/ram.c"
    click ROM "https://github.com/shrehanrajsingh/sharna/blob/main/rom/rom.c"
    click Registers "https://github.com/shrehanrajsingh/sharna/blob/main/registers.h"
    click Inst "https://github.com/shrehanrajsingh/sharna/blob/main/inst/add.c"
    click TestC "https://github.com/shrehanrajsingh/sharna/blob/main/tests/test.c"

    %% Styles
    classDef assembler fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef vm fill:#90EE90,stroke:#333,stroke-width:1px
    classDef memory fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef std fill:#FFA500,stroke:#333,stroke-width:1px
    classDef tests fill:#FFD700,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
