# s-mv/smvm architecture

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

- Interactive diagram: https://gitdiagram.com/s-mv/smvm
- Repository: https://github.com/s-mv/smvm

## Overview

##### Project type and purpose
- This repository implements “smvm,” a register-based bytecode virtual machine written in C.
- It’s both a standalone CLI tool (main.c + asmv,dsmv front-ends) and an embeddable C library (src/smvm.{c,h}, util, functions).

##### File structure
- Top-level:
- main.c – CLI entrypoint
- src/asmv.{c,h} – assembler frontend
- src/dsmv.{c,h} – disassembler frontend
- src/smvm.{c,h} – VM core and public API
- src/functions.c/.h – built-in host functions (puts, puti, etc.)
- src/util.c/.h – support routines (memory, string, I/O helpers)
- examples/ – sample assembly and C embedding use-cases
- docs/ – bytecode and instruction-set specifications
- Makefile, .github/workflows – build and CI scripts

##### README for additional insights
- Confirms dual usage: standalone CLI vs. embedded C library
- Describes core workflow: assemble text → bytecode → execute on VM → host I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    ExternalUser["External User"]:::external
    HostCProgram["Host C Program"]:::external

    %% Frontend Layer
    subgraph "CLI Frontends"
        direction TB
        CLI["CLI Frontend\n(main.c)"]:::cli
        Asm["Assembler Frontend\n(src/asmv.c/.h)"]:::cli
        Dsm["Disassembler Frontend\n(src/dsmv.c/.h)"]:::cli
    end

    %% Public API Layer
    PubAPI["VM Public API\n(src/smvm.h/.c)"]:::public

    %% Core VM Internals
    subgraph "VM Core Module"
        direction TB
        Loader["Bytecode Loader/Parser\n(src/all.h)"]:::core
        FetchDecode["Instruction Fetch & Decode"]:::core
        ExecEngine["Execution Engine"]:::core
        RegMem["Register File & Memory Model"]:::core
        Util["Utility Module\n(src/util.c/.h)"]:::util
    end

    %% Host Functions and I/O
    HostFuncs["Built-in Host Functions\n(src/functions.c/.h)"]:::core
    HostIO["Host I/O / Stdout"]:::external

    %% Build & CI
    subgraph "Build & CI"
        direction TB
        Make["Makefile"]:::build
        CI["GitHub Actions\n(.github/workflows/release.yml)"]:::build
        Tests["Tests\n(tests/tests.c,\nmini_catch2.h)"]:::build
        Docs["Documentation\n(BYTECODE.md,\nINSTRUCTIONSET.md)"]:::docs
    end

    %% Relationships
    ExternalUser -->|"CLI invocation"| CLI
    ExternalUser -->|"C API calls"| PubAPI
    HostCProgram -->|"C API calls"| PubAPI

    CLI -->|"uses asm/dsm"| Asm
    CLI -->|"uses asm/dsm"| Dsm
    Asm -->|"bytecode"| PubAPI
    Dsm -->|"bytecode"| PubAPI

    PubAPI -->|"loads bytecode"| Loader
    Loader --> FetchDecode
    FetchDecode --> ExecEngine
    ExecEngine --> RegMem
    ExecEngine --> HostFuncs
    RegMem --> HostFuncs
    HostFuncs --> HostIO
    ExecEngine --> Util
    Loader --> Util

    Make --> CLI
    Make --> PubAPI
    Make --> HostFuncs
    Make --> Tests
    Make --> Docs
    CI --> Make

    %% Click Events
    click CLI "https://github.com/s-mv/smvm/blob/main/main.c"
    click Asm "https://github.com/s-mv/smvm/blob/main/src/asmv.c"
    click Dsm "https://github.com/s-mv/smvm/blob/main/src/dsmv.c"
    click PubAPI "https://github.com/s-mv/smvm/blob/main/src/smvm.c"
    click Loader "https://github.com/s-mv/smvm/blob/main/src/all.h"
    click HostFuncs "https://github.com/s-mv/smvm/blob/main/src/functions.c"
    click Util "https://github.com/s-mv/smvm/blob/main/src/util.c"
    click Make "https://github.com/s-mv/smvm/tree/main/Makefile"
    click CI "https://github.com/s-mv/smvm/blob/main/.github/workflows/release.yml"
    click Tests "https://github.com/s-mv/smvm/blob/main/tests/tests.c"
    click Docs "https://github.com/s-mv/smvm/blob/main/docs/BYTECODE.md"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#999
    classDef cli fill:#ffd2a6,stroke:#e67e22
    classDef public fill:#aaffaa,stroke:#27ae60
    classDef core fill:#aaaaff,stroke:#2980b9
    classDef util fill:#dddddd,stroke:#7f8c8d
    classDef build fill:#fffa90,stroke:#f1c40f
    classDef docs fill:#e1bbee,stroke:#9b59b6
```
