# code-payments/code-vm architecture

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

- Interactive diagram: https://gitdiagram.com/code-payments/code-vm
- Repository: https://github.com/code-payments/code-vm

## Overview

##### Project Type & Purpose
- The project is an on-chain virtual machine specifically built for the Solana blockchain. Its primary goal is to optimize payments by drastically reducing transaction fees and account rent. It does this by “virtualizing” accounts and allowing dormant accounts to be compressed off-chain.
- The README clearly states that this is tailored for use by the Code and Flipchat mobile apps to provide seamless payment functionality on Solana.
- The design is highly specialized: it abstracts the VM complexity so that mobile apps behave as if they were interacting with standard Solana accounts.

##### File Structure
- The repository separates code into three main areas:
- The “program” directory: Contains on-chain program code, including instruction handlers (deposit, init, withdraw, etc.) and opcode definitions. This clearly represents the entrypoints and execution logic that runs on-chain.
- The “idl” directory: Contains interface definitions and configuration files (e.g., Anchor.toml, JSON definitions) that are used for generating client libraries and ensuring proper integration with the Solana ecosystem.
- There are additional directories (like “docs” for documentation and audit reports) that provide context on security and quality, but the core architecture lies in “api”, “program”, and “idl”.

##### Main Components & Their Relationships
- External Clients:
- Not part of this repo but critical to note. The Code and Flipchat mobile apps are the consumers and will interface with the system via backend services.
- Backend Services / API Layer:
- Although the mobile app is not included in the codebase, the “api” section serves as the abstraction layer. It encapsulates the VM’s internal operations. It includes modules for managing different account types, message handling (transfers, airdrops, withdrawals), state management (memory, storage, relays), and utility functions.
- On-chain Program:
- Located under “program”, this component implements the actual Solana program using instruction handlers. It routes operations like initializing various account states, depositing funds, compressing/decompressing accounts, and executing opcodes.
- Interface Definition (IDL):
- This part of the project (in the “idl” directory) defines the API contract in a machine-readable form so that client apps can interact with the on-chain program correctly. The IDL provides a bridge between the off-chain world and what is deployed on-chain.

##### Architectural Patterns & Design Principles
- Modularity: The separation between the “api” and “program” directories indicates a clear separation of the VM’s backend logic from its on-chain execution logic.
- Layered Design: There is a distinct layering – where lower-level VM functionalities (memory, state, utilities) are abstracted in “cvm” sub-modules, and higher-level functions (instructions and opcodes) are handled in the “program” directory.
- Interface Abstraction: The presence of IDL configuration indicates a design that values contract-based interaction, making integration with external clients (like the mobile apps) as seamless as possible.

##### Final Assembly
- The flow of transaction requests from clients to the backend service.
- The invocation of on-chain instructions from the API layer.
- The connection between the IDL specifications and the on-chain program.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top level components
    A["Mobile App Clients"]:::client
    subgraph "Backend API (Code VM Core)"
        B1["Account Management"]:::api
        B2["Message Handling"]:::api
        B3["State Management"]:::api
        B4["Utilities & Types"]:::api
        B5["External Interactions"]:::api
    end
    subgraph "On-Chain Program (Instructions & Opcodes)"
        C1["Instruction Handlers"]:::program
        C2["Opcode Processing"]:::program
    end
    D["Interface Definition (IDL)"]:::idl

    %% Connections between top level components
    A -->|"sends transaction requests"| B1
    %% Internal API flows (for illustration; these represent internal module interactions)
    B1 -->|"invokes"| B2
    B2 -->|"triggers"| B3
    B3 -->|"utilizes"| B4
    B4 -->|"coordinates with"| B5
    %% API to On-Chain Program connections
    B2 -->|"calls on-chain instruction"| C1
    B3 -->|"executes opcode operations"| C2
    %% IDL integration connections
    A -->|"retrieves API contract from"| D
    D -->|"defines contract for"| C1

    %% Click Events for Backend API Components
    click B1 "https://github.com/code-payments/code-vm/tree/main/api/src/cvm/account"
    click B2 "https://github.com/code-payments/code-vm/tree/main/api/src/cvm/messages"
    click B3 "https://github.com/code-payments/code-vm/tree/main/api/src/cvm/state"
    click B4 "https://github.com/code-payments/code-vm/tree/main/api/src/types"
    click B5 "https://github.com/code-payments/code-vm/tree/main/api/src/external"
    
    %% Click Events for On-Chain Program Components
    click C1 "https://github.com/code-payments/code-vm/tree/main/program/src/instruction"
    click C2 "https://github.com/code-payments/code-vm/tree/main/program/src/opcode"
    
    %% Click Event for Interface Definition (IDL)
    click D "https://github.com/code-payments/code-vm/tree/main/idl"

    %% Styles
    classDef client fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef program fill:#FFCCCB,stroke:#333,stroke-width:2px;
    classDef idl fill:#D8BFD8,stroke:#333,stroke-width:2px;
```
