# trueagi-io/hyperon-experimental architecture

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

- Interactive diagram: https://gitdiagram.com/trueagi-io/hyperon-experimental
- Repository: https://github.com/trueagi-io/hyperon-experimental

## Overview

##### Main Components

a. Core Components:
- Rust Core Library (libhyperon.rlib)
- C API Layer (libhyperonc)
- Python Bindings (libhyperonpy)
- Python Library (hyperon)
- REPL Interfaces (Rust and Python)

b. Key Subsystems:
- MeTTa Interpreter
- Atom System
- Space System
- Runner System
- Standard Library
- Package Management System

##### Component Relationships

**Top Layer (User Interfaces):**
- MeTTa REPL (Rust)
- MeTTa REPL (Python)
- Python Applications

**Middle Layer (Language Bindings):**
- Python Library (hyperon)
- Python Bindings (libhyperonpy)
- C API (libhyperonc)

**Core Layer (Rust Implementation):**
- MeTTa Interpreter
- Atom System
- Space System
- Runner System

##### Specific Implementation Details

a. Core Components (Rectangle, Blue):
- Atom System (/lib/src/atom/)
- Space System (/lib/src/space/)
- MeTTa System (/lib/src/metta/)

b. Extension Points (Hexagon, Green):
- Python Extensions (/python/hyperon/exts/)
- Built-in Modules (/lib/src/metta/runner/builtin_mods/)
- Standard Library (/lib/src/metta/runner/stdlib/)

- Package Management (/lib/src/metta/runner/pkg_mgmt/)
- Common Utilities (/lib/src/common/)

- Bidirectional communication between Python bindings and C API
- How the REPL interfaces interact with the core system
- Demonstrate package management flow
- Module loading paths

##### Implementation Notes

- The layered architecture approach
- Clear separation between core functionality and language bindings
- Extension mechanisms for both Rust and Python
- Test infrastructure integration

##### Additional Elements

- Version information
- Build system integration (CMake, Cargo)
- Test framework integration
- Documentation generation flow

Remember to use the existing structure.plantuml file in the docs/assets directory as a reference point, but expand it to include the detailed architecture described above.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef core fill:#b3d1ff,stroke:#333
    classDef extension fill:#90EE90,stroke:#333
    classDef infrastructure fill:#D3D3D3,stroke:#333
    classDef interface fill:#FFE4B5,stroke:#333
    classDef binding fill:#DDA0DD,stroke:#333

    %% User Interface Layer
    subgraph UI
        REPL_Rust["Rust REPL"]:::interface
        REPL_Python["Python REPL"]:::interface
        PythonApps["Python Applications"]:::interface
    end

    %% Language Bindings Layer
    subgraph Bindings
        PythonLib["Python Library"]:::binding
        PythonBindings["Python Bindings"]:::binding
        CAPI["C API Layer"]:::binding
    end

    %% Core Layer
    subgraph Core
        RustCore["Rust Core Library"]:::core
        
        subgraph Interpreter
            MeTTa["MeTTa Interpreter"]:::core
            AtomSystem["Atom System"]:::core
            SpaceSystem["Space System"]:::core
            RunnerSystem["Runner System"]:::core
        end
        
        subgraph Extensions
            StdLib["Standard Library"]:::extension
            BuiltinMods["Built-in Modules"]:::extension
            PythonExts["Python Extensions"]:::extension
        end
        
        subgraph Infrastructure
            PkgMgmt["Package Management"]:::infrastructure
            CommonUtils["Common Utilities"]:::infrastructure
            TestInfra["Test Infrastructure"]:::infrastructure
        end
    end

    %% Relationships
    REPL_Rust --> RustCore
    REPL_Python --> PythonLib
    PythonApps --> PythonLib
    PythonLib --> PythonBindings
    PythonBindings --> CAPI
    CAPI --> RustCore
    
    RustCore --> MeTTa
    MeTTa --> AtomSystem
    MeTTa --> SpaceSystem
    MeTTa --> RunnerSystem
    
    RunnerSystem --> StdLib
    RunnerSystem --> BuiltinMods
    RunnerSystem --> PkgMgmt
    
    PythonLib --> PythonExts
    
    %% Click Events
    click RustCore "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/"
    click CAPI "https://github.com/trueagi-io/hyperon-experimental/tree/main//c/"
    click PythonBindings "https://github.com/trueagi-io/hyperon-experimental/blob/main//python/hyperonpy.cpp"
    click PythonLib "https://github.com/trueagi-io/hyperon-experimental/tree/main//python/hyperon/"
    click REPL_Rust "https://github.com/trueagi-io/hyperon-experimental/tree/main//repl/"
    click MeTTa "https://github.com/trueagi-io/hyperon-experimental/blob/main//lib/src/metta/interpreter.rs"
    click AtomSystem "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/atom/"
    click SpaceSystem "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/space/"
    click RunnerSystem "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/metta/runner/"
    click StdLib "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/metta/runner/stdlib/"
    click PkgMgmt "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/metta/runner/pkg_mgmt/"
    click BuiltinMods "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/metta/runner/builtin_mods/"
    click CommonUtils "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/src/common/"
    click PythonExts "https://github.com/trueagi-io/hyperon-experimental/tree/main//python/hyperon/exts/"
    click TestInfra "https://github.com/trueagi-io/hyperon-experimental/tree/main//lib/tests/"
```
