# pocketpy/pocketpy architecture

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

- Interactive diagram: https://gitdiagram.com/pocketpy/pocketpy
- Repository: https://github.com/pocketpy/pocketpy

## Overview

##### Project Type and Purpose
- Project Type: This is a high-performance, embeddable Python interpreter implemented in C11.
- Purpose: It is designed to be an alternative to Lua for game scripting and other embedded environments. It provides both a C API and pybind11-compatible bindings and boasts minimal dependencies (only the C standard library) for easy integration into host projects.

##### File Structure
- Core Source Directories:
– The “src” folder holds the implementation of the interpreter:
- "src/common": Common utility functions needed by various components.
- "src/compiler": Contains the lexer and compiler components.
- "src/interpreter": Implements the virtual machine (VM), execution engine, and registers stack/frame management.
- "src/modules": Built-in Python modules (e.g., math, json, os) and language features.
- "src/objects": Implementation of Python objects, code objects, and related data structures.
- "src/public": C API functions for external code to execute Python code, inspect runtime values, etc.
- "src2": Contains example programs and alternative usage demos.
- API Headers:
– The “include” folder contains all necessary headers for integrating pocketpy, including C API definitions, compiler interfaces, and the pybind11 binding files.
- Third-Party and Build Related:
– The “3rd” directory includes third-party libraries (like libhv for networking and lz4 for compression) that are integrated into the system.
– Various CMake and build scripts (CMakeLists.txt, build_*.sh) indicate multi-platform build support (Android, iOS, web via Emscripten, etc.).
– “tests”, “benchmarks”, and “docs” directories also provide test suites, performance benchmarks, and documentation on API and architecture.

##### Main Components and Their Interactions
- Interpreter Core:
– Compiler & Lexer (in src/compiler): Parses Python source code into tokens and builds executable code objects.
– Virtual Machine (in src/interpreter): Executes bytecode, manages the execution frame, garbage collection (in src/modules or underlying interpreter/objects).
– Built-In Objects and Modules (in src/modules and src/objects): Provide the standard Python functionality such as arithmetic, list/dict operations, and exception handling.
- External APIs:
– C API (src/public and include/pocketpy): Exposes API functions for initializing the interpreter, executing code, embedding into C/C++ applications.
– Bindings with pybind11 (include/pybind11 and related workflows): Allow native C++ integration and embedding within a C++ context.
- Third-party Integrations and Plugins:
– The “3rd” libraries (libhv, lz4) are integrated for network communication and fast compression.
– The “plugins/flutter” directory and subfolders provide cross-platform mobile integrations (Android, iOS, macOS, Windows, Linux) via Flutter, which interface with the core interpreter.
- Build and Testing Infrastructure:
– CMake configuration files and various build scripts support cross-platform compilation.
– “tests” and “benchmarks” directories represent integration tests and performance evaluations to ensure interpreter correctness and efficiency.

##### Recommended Elements
- Use clear labels for each component (for example, “Lexer”, “Compiler”, “Virtual Machine”, “Built-in Modules”, “C API Interface”, “pybind11 Bindings”, “Third-Party Libs”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compiler & Parser
    subgraph "Compiler & Parser"
        LEXER["Lexer"]:::internal
        COMPILER["Compiler"]:::internal
    end

    %% Interpreter Core
    subgraph "Interpreter Core"
        VM["Virtual Machine & Execution Engine"]:::internal
        FRAME["Frame & Stack Management"]:::internal
    end

    %% Built-In Modules & Object System
    subgraph "Built-In Modules & Object System"
        MODULES["Standard Library Modules"]:::internal
        OBJECTS["Python Objects"]:::internal
        COMMON["Common Utilities"]:::internal
    end

    %% External API Interfaces
    subgraph "External API Interfaces"
        CAPI["C API Interface"]:::external
        APIHEAD["API Headers"]:::external
        PYBIND["pybind11 Bindings"]:::external
    end

    %% Third-Party Libraries
    subgraph "Third-Party Libraries"
        LIBHV["libhv (Networking)"]:::external
        LZ4["lz4 (Compression)"]:::external
    end

    %% Integration/Plugin Layer
    subgraph "Integration/Plugin Layer"
        FLUTTER["Flutter Integration"]:::external
        WEB["Web Front-end"]:::external
    end

    %% Build & Testing Infrastructure
    subgraph "Build & Testing"
        BUILD["Build Scripts & CMake"]:::build
        TESTS["Test Suites"]:::build
        BENCH["Benchmarks"]:::build
    end

    %% Data Flow and Dependencies
    LEXER -->|"produces tokens"| COMPILER
    COMPILER -->|"generates bytecode"| VM
    VM -->|"manages"| FRAME

    VM -->|"executes builtins"| MODULES
    VM -->|"manages objects"| OBJECTS
    VM -->|"utilizes utilities"| COMMON

    CAPI -->|"initializes"| VM
    APIHEAD -->|"defines API"| CAPI
    PYBIND -->|"exposes bindings"| CAPI

    LIBHV -->|"integrates networking"| MODULES
    LZ4 -->|"provides compression"| MODULES

    FLUTTER -->|"interfaces via API"| CAPI
    WEB -->|"communicates with"| CAPI

    BUILD --- LEXER
    BUILD --- COMPILER
    BUILD --- VM
    BUILD --- MODULES
    BUILD --- CAPI

    TESTS --- VM
    BENCH --- VM

    %% Styling Classes
    classDef internal fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef external fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef build fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;

    %% Click Events
    click LEXER "https://github.com/pocketpy/pocketpy/blob/main/src/compiler/lexer.c"
    click COMPILER "https://github.com/pocketpy/pocketpy/blob/main/src/compiler/compiler.c"
    click VM "https://github.com/pocketpy/pocketpy/tree/main/src/interpreter"
    click MODULES "https://github.com/pocketpy/pocketpy/tree/main/src/modules"
    click OBJECTS "https://github.com/pocketpy/pocketpy/tree/main/src/objects"
    click COMMON "https://github.com/pocketpy/pocketpy/tree/main/src/common"
    click CAPI "https://github.com/pocketpy/pocketpy/tree/main/src/public"
    click APIHEAD "https://github.com/pocketpy/pocketpy/tree/main/include/pocketpy"
    click PYBIND "https://github.com/pocketpy/pocketpy/tree/main/include/pybind11"
    click LIBHV "https://github.com/pocketpy/pocketpy/tree/main/3rd/libhv"
    click LZ4 "https://github.com/pocketpy/pocketpy/tree/main/3rd/lz4"
    click FLUTTER "https://github.com/pocketpy/pocketpy/tree/main/plugins/flutter/pocketpy"
    click BUILD "https://github.com/pocketpy/pocketpy/blob/main/CMakeLists.txt"
    click TESTS "https://github.com/pocketpy/pocketpy/tree/main/tests"
    click BENCH "https://github.com/pocketpy/pocketpy/tree/main/benchmarks"
```
