# jamsocket/forevervm architecture

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

- Interactive diagram: https://gitdiagram.com/jamsocket/forevervm
- Repository: https://github.com/jamsocket/forevervm

## Overview

##### Project type and purpose
- From the README and file tree, this is an open-source, polyglot SDK + CLI toolset (“foreverVM”) for running stateful Python code via a remote API.
- It provides:
- Language-specific CLI clients (JavaScript, Rust)
- Language-specific SDKs (JavaScript, Python, Rust)
- Example apps (JS example, JS “mcp-server”)
- CI/CD & publishing scripts

##### File structure
- Top-level directories by language:
- javascript/ ← contains a CLI (forevervm), an SDK (@forevervm/sdk), an example client, a “mcp-server” sample microservice
- python/ ← contains a forevervm CLI wrapper and an SDK package (forevervm_sdk) + tests
- rust/ ← contains two crates: forevervm (CLI) and forevervm-sdk (library)
- scripts/ ← bump-version & publish tooling (TypeScript)
- .github/workflows/ ← per-language build/test/publish pipelines
- Root publishing.md, LICENSE, README

##### README for architectural insights
- Core concepts: Machines (stateful Python processes), Instructions (code you send, one at a time)
- The user interacts via CLI or SDK -> sends REST/WebSocket calls to a remote foreverVM API.
- The API manages machine lifecycle, memory limits, tags, swap to disk, etc.

##### Main components to capture
a. Developer’s workspace / Monorepo
– Code modules: JS SDK, JS CLI, Rust SDK, Rust CLI, Python SDK, Python CLI, Example, mcp-server, Publish scripts
– CI/CD pipelines (GitHub Actions)
b. Package registries & distribution
– npm registry (forevervm, @forevervm/sdk)
– PyPI (forevervm)
– crates.io (forevervm, forevervm-sdk)
c. End user applications
– CLI commands (e.g. `npx forevervm`, `forevervm repl`)
– Embedded SDK code in user apps
– Example apps (JS example, mcp-server)
d. External foreverVM API service (hosted)
– Authentication (API token)
– REST or WebSocket endpoints: createMachine, listMachines, exec instr, stream output
– Backend sub-system (not in this repo): machine manager, container/Python process pool, swap-to-disk store

##### Relationships and interactions
- Developers push code → GitHub Actions → run per-language tests → on success → scripts/publish → push packages to registries
- End users install CLI/SDK from registries → instantiate ForeverVM client → authenticate → connect to remote foreverVM API
- foreverVM API orchestrates machines & returns results over HTTP/WebSocket

##### Architectural patterns & design principles
- Monorepo with language-specific packages, shared version bump/publish scripts
- Single logical API boundary, multiple SDK adapters (Adapter pattern)
- CI/CD pipeline per language, unified publishing flow

##### Detail level
- Every language implementation as its own module if space allows
- Don’t overthink—break system into as many logical components as makes the flow clear

A) Developer/Repo Layer: Monorepo → language packages + scripts + CI/CD
B) Distribution Layer: npm, PyPI, crates.io registries
C) Runtime Layer: End-user apps (CLI/SDK) → foreverVM API → machine management backend

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Developer / Repo Layer
    subgraph "Monorepo"
        direction TB
        subgraph "Code Modules"
            direction TB
            JS_CLI["JS CLI (javascript/forevervm)"]:::code
            JS_SDK["JS SDK (@forevervm/sdk)"]:::code
            JS_Example["JS Example App"]:::code
            JS_MCP["JS mcp-server"]:::code
            Py_CLI["Python CLI (python/forevervm)"]:::code
            Py_SDK["Python SDK (forevervm_sdk)"]:::code
            Rust_CLI["Rust CLI (rust/forevervm)"]:::code
            Rust_SDK["Rust SDK (forevervm-sdk)"]:::code
        end
        subgraph "CI/CD Pipelines"
            direction TB
            JS_CI["GitHub Actions JS Checks"]:::infra
            Py_CI["GitHub Actions Python Checks"]:::infra
            Rust_CI["GitHub Actions Rust Checks"]:::infra
            Release_CI["GitHub Actions Release"]:::infra
        end
        subgraph "Publish Scripts"
            direction TB
            Scripts_Bump["Version Bump Script"]:::infra
            Scripts_Publish["Publish Script"]:::infra
        end
        subgraph "Documentation"
            direction TB
            Docs_README["README.md"]:::infra
            Docs_PUB["publishing.md"]:::infra
        end
    end

    %% Distribution Layer
    subgraph "Package Registries"
        direction TB
        NPM["npm registry"]:::infra
        PyPI["PyPI"]:::infra
        Crates["crates.io"]:::infra
    end

    %% Runtime Layer
    subgraph "End-User Applications"
        direction TB
        CLI_Usage["CLI Usage"]:::code
        SDK_Usage["Embedded SDK"]:::code
    end

    API["foreverVM API Service"]:::external
    Backend["Machine Manager & Swap Store"]:::external

    %% Relationships
    JS_CLI -->|"depends on"| JS_SDK
    JS_CI -->|"on success"| Release_CI
    Py_CI -->|"on success"| Release_CI
    Rust_CI -->|"on success"| Release_CI
    Release_CI -->|"run"| Scripts_Bump
    Scripts_Bump -->|"then"| Scripts_Publish
    Scripts_Publish -->|"publish to"| NPM
    Scripts_Publish -->|"publish to"| PyPI
    Scripts_Publish -->|"publish to"| Crates

    NPM -->|install| CLI_Usage
    NPM -->|install| SDK_Usage
    PyPI -->|install| CLI_Usage
    PyPI -->|install| SDK_Usage
    Crates -->|install| CLI_Usage
    Crates -->|install| SDK_Usage

    CLI_Usage -->|"API calls"| API
    SDK_Usage -->|"API calls"| API
    API -->|"orchestrates"| Backend

    %% Click Events
    click JS_CLI "https://github.com/jamsocket/forevervm/tree/main/javascript/forevervm/"
    click JS_SDK "https://github.com/jamsocket/forevervm/tree/main/javascript/sdk/"
    click JS_Example "https://github.com/jamsocket/forevervm/tree/main/javascript/example/"
    click JS_MCP "https://github.com/jamsocket/forevervm/tree/main/javascript/mcp-server/"
    click Py_CLI "https://github.com/jamsocket/forevervm/tree/main/python/forevervm/"
    click Py_SDK "https://github.com/jamsocket/forevervm/tree/main/python/sdk/forevervm_sdk/"
    click Rust_CLI "https://github.com/jamsocket/forevervm/tree/main/rust/forevervm/"
    click Rust_SDK "https://github.com/jamsocket/forevervm/tree/main/rust/forevervm-sdk/"
    click JS_CI "https://github.com/jamsocket/forevervm/blob/main/.github/workflows/javascript-checks.yml"
    click Py_CI "https://github.com/jamsocket/forevervm/blob/main/.github/workflows/python-checks.yml"
    click Rust_CI "https://github.com/jamsocket/forevervm/blob/main/.github/workflows/rust-checks.yml"
    click Release_CI "https://github.com/jamsocket/forevervm/blob/main/.github/workflows/release.yml"
    click Scripts_Bump "https://github.com/jamsocket/forevervm/blob/main/scripts/bump-versions.ts"
    click Scripts_Publish "https://github.com/jamsocket/forevervm/blob/main/scripts/publish.ts"
    click Docs_README "https://github.com/jamsocket/forevervm/blob/main/README.md"
    click Docs_PUB "https://github.com/jamsocket/forevervm/blob/main/publishing.md"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef infra fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
