# cryptofamilynft/oobe-protocol architecture

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

- Interactive diagram: https://gitdiagram.com/cryptofamilynft/oobe-protocol
- Repository: https://github.com/cryptofamilynft/oobe-protocol

## Overview

##### Project type and purpose
- This is an open-source, monorepo-style Node.js SDK (library) designed to build and manage Solana-based AI agents.
- It provides core abstractions (ConfigManager, OobeCore), a registry of Actions/Operations, on-chain agent personality modules, memory layers (Merkle trees, DB), and tool-creation helpers for DEXes, RPCs, and AI services.

##### File structure
- Top-level:
- pnpm-workspace.yaml / package.json – monorepo config
- packages/core – the main TypeScript SDK (src + dist)
- packages/system – a minimal “system” wrapper or example
- packages/core/src organizes by feature:
- actions/ – discrete on-chain or AI “actions” (agent, IQ, JUP, Orca, Ray, Solana, etc.)
- agent-personality/ – engine, logic, state & on-chain personality modules
- agent/ – core Agent classes and Persona abstractions
- config/ – ConfigManager, default config, tool configuration templates
- operations/ – “higher-level” operations built atop actions (e.g., dex.operation, merkle.operation)
- utils/ – RPC, Solana helpers, Merkle, logger, SmartRoundRobinRPC, etc.
- types/ – all interfaces for DI, plugin contracts, proofs, DEX, DB, agent, etc.
- packages/system is a thin layer that re-exports core or provides a CLI.

##### README for additional insights
- Core classes: ConfigManager, OobeCore, AgentExecution
- External dependencies: Solana RPC clusters, OpenAI API, MongoDB/Redis for history
- Key workflows: initialize config → start OobeCore → register actions/tools → execute agent logic → memory persistence → on-chain inscription

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration Layer
    subgraph "Configuration Layer"
        PDAManager["PDAManager"]:::core
        ZeroCombineFetcher["ZeroCombineFetcher"]:::core
        Defaults["defaultConfig"]:::core
    end

    %% Core Engine
    subgraph "Core Engine"
        OobeCore["OobeCore Engine"]:::core
        Bootstrap["Bootstrap (index.ts)"]:::core
    end

    %% Agent & Persona
    subgraph "Agent & Execution"
        AgentExecution["AgentExecution"]:::domain
        Agent["Agent"]:::domain
        Persona["Persona"]:::domain
    end

    %% Personality Modules
    subgraph "Personality Modules"
        PersonalityCore["PersonalityCore"]:::domain
        EvolutionEngine["EvolutionEngine"]:::domain
        FusionEngine["FusionEngine"]:::domain
        DecisionOracle["DecisionOracle"]:::domain
        TraitTransformer["TraitTransformer"]:::domain
        AgentPersonality["AgentPersonality (On-chain)"]:::domain
        PDAEncoder["PDAEncoder (On-chain)"]:::domain
    end

    %% Action Registry
    subgraph "Action Registry"
        ActionsIndex["Actions Index"]:::domain
        AgentAction["agent.action"]:::domain
        SolBalance["solana.balance.action"]:::domain
        SolBalanceAll["solana.balanceAll.action"]:::domain
        CheckRugs["solana.checkRugs"]:::domain
        JupBuy["jupiter_buy.action"]:::domain
        JupSell["jupiter_sell.action"]:::domain
        OrcaCreate["orca_create_clmm.action"]:::domain
        OrcaFetch["orca_fetch_position.action"]:::domain
        RayBuy["ray_buy.action"]:::domain
    end

    %% Operations Registry
    subgraph "Operations Registry"
        DexOp["dex.operation"]:::domain
        IQOp["iq.operation"]:::domain
        JupOp["jup.operation"]:::domain
        MerkleOp["merkle.operation"]:::domain
        SolOp["solana.operation"]:::domain
    end

    %% Tools Factory
    subgraph "Tools Factory"
        CreateTools["createSolanaTools"]:::domain
    end

    %% Memory & Persistence
    subgraph "Memory & Persistence"
        VectorMemory["OobeVectorMemory"]:::infra
        ZeroFormat["ZeroFormatRecord"]:::infra
        MerkleValidator["MerkleValidator"]:::infra
        DB["Database (Mongo/Redis)"]:::infra
        MerkleTree["Merkle Tree"]:::infra
    end

    %% Utilities
    subgraph "Utilities"
        RPC["SmartRoundRobinRPC"]:::infra
        Logger["Logger"]:::infra
        Hubble["HubbleService"]:::infra
    end

    %% External Services
    subgraph "External Services"
        SolRPC["Solana RPC Cluster"]:::infra
        OpenAI["OpenAI API"]:::infra
    end

    %% Relationships
    PDAManager -->|injects config| OobeCore
    ZeroCombineFetcher -->|fetch fallback| ConfigManager
    Defaults -->|default settings| PDAManager
    Bootstrap -->|start| OobeCore
    OobeCore -->|initialize| AgentExecution
    AgentExecution -->|bootstraps| Agent
    Agent -->|loads| ActionsIndex
    Agent -->|registers| AgentAction
    Agent -->|uses| SolBalance
    Agent -->|uses| SolBalanceAll
    Agent -->|uses| CheckRugs
    Agent -->|uses| JupBuy
    Agent -->|uses| JupSell
    Agent -->|uses| OrcaCreate
    Agent -->|uses| OrcaFetch
    Agent -->|uses| RayBuy
    Agent -->|executes| DexOp
    Agent -->|executes| IQOp
    Agent -->|executes| JupOp
    Agent -->|executes| MerkleOp
    Agent -->|executes| SolOp
    Agent -->|builds tools| CreateTools
    Agent -->|logs memory| VectorMemory
    Agent -->|formats records| ZeroFormat
    VectorMemory -->|writes| DB
    ZeroFormat -->|writes| DB
    MerkleValidator -->|validates| MerkleTree
    AgentAction -->|calls| RPC
    AgentAction -->|calls| OpenAI
    RPC -->|round-robin| SolRPC
    OpenAI -->|API calls| OpenAI

    %% Click Events
    click PDAManager "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/config/PDAManager.ts"
    click ZeroCombineFetcher "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/config/ZeroCombineFetcher.ts"
    click Defaults "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/config/default.ts"
    click OobeCore "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/core.ts"
    click Bootstrap "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/index.ts"
    click AgentExecution "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent/Agents.ts"
    click Persona "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent/persona/Persona.ts"
    click PersonalityCore "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/engine/PersonalityCore.ts"
    click EvolutionEngine "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/engine/EvolutionEngine.ts"
    click FusionEngine "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/engine/FusionEngine.ts"
    click DecisionOracle "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/logic/DecisionOracle.ts"
    click TraitTransformer "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/logic/TraitTransformer.ts"
    click AgentPersonality "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/onchain/AgentPersonality.ts"
    click PDAEncoder "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/agent-personality/onchain/PDAEncoder.ts"
    click ActionsIndex "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/index.ts"
    click AgentAction "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/agent/agent.action.ts"
    click SolBalance "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/solana/balance.action.ts"
    click SolBalanceAll "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/solana/balanceAll.action.ts"
    click CheckRugs "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/solana/checkRugs.ts"
    click JupBuy "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/jup/jupiter_buy.action.ts"
    click JupSell "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/jup/jupiter_sell.action.ts"
    click OrcaCreate "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/orca/orca_create_clmm.action.ts"
    click OrcaFetch "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/orca/orca_fetch_position.action.ts"
    click RayBuy "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/actions/ray/r_buy.action.ts"
    click DexOp "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/operations/dex/dex.operation.ts"
    click IQOp "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/operations/iq/iq.operation.ts"
    click JupOp "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/operations/jup/jup.operation.ts"
    click MerkleOp "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/operations/merkle.operation.ts"
    click SolOp "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/operations/solana.operation.ts"
    click CreateTools "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/createTools.ts"
    click VectorMemory "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/oobe/OobeVectorMemory.ts"
    click ZeroFormat "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/oobe/ZeroFormatRecord.ts"
    click MerkleValidator "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/merkleValidator.ts"
    click RPC "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/SmartRoundRobinRPC.ts"
    click Logger "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/logger/logger.ts"
    click Hubble "https://github.com/cryptofamilynft/oobe-protocol/blob/main/packages/core/src/utils/hubble/HubbleService.ts"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085;
    classDef domain fill:#d4edda,stroke:#155724;
    classDef infra fill:#fff3cd,stroke:#856404;
```
