# vessl-ai/hyperpocket architecture

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

- Interactive diagram: https://gitdiagram.com/vessl-ai/hyperpocket
- Repository: https://github.com/vessl-ai/hyperpocket

## Overview

##### Main components
- Core Engine: Represent the central Hyperpocket core (located in libs/hyperpocket). This module handles key functions like configuration management, session handling (in-memory or Redis), and central authentication logic for various providers.
- Extensions/Plugins: Include the extension packages (found in libs/extensions) that tailor Hyperpocket to work with specific platforms or agent frameworks such as Langchain, Anthropic, Gemini, Langgraph, and Llamaindex.
- Docks Integration: Note the existence of “docks” modules (e.g., in libs/docks like hyperdock-container, hyperdock-fileio, hyperdock-langchain, and hyperdock-llamaindex) that isolate tool execution environments (often based on WebAssembly) and encapsulate runtime and file operations.
- Tools Repository: Represent the many tools available in the tools/ directory. These are standalone utilities (with their own configuration files, build scripts, and even some written in Go) that cover functions like Slack message retrieval, calendly event creation, or GitHub operations.
- Examples & Scripts: Indicate the example integrations and scripts which demonstrate how to instantiate agents that bind tools and use them in typical workflows.
- CI/CD and Documentation: Include support components such as GitHub workflows (for testing, publishing, and deployment) and the docs directory, which provide user guides and internal documentation.

##### Relationships and interactions
- Extension Integration: Connect the core engine to the various extension modules which adapt the core functionality to different agent frameworks. These modules abstract the details of tool calling and authentication for that specific integration.
- Tool Invocation: Show the core engine “fetching” or “binding” tools from the remote tools repository (for instance using URLs as seen in the README) and executing them in an isolated environment (illustrated by a “dock” container).
- Authentication: Represent the auth flow with separate components for OAuth and token-based processes. Point out that configuration and secret management is externally available via settings.toml and .secrets.toml.

##### Design patterns and technologies
- Modularity & Plugin Architecture: Emphasize the decoupled design – the core engine is extended via multiple plugins and docks.
- Isolation Pattern: Indicate that each tool runs within an isolated environment (leveraging WebAssembly) to prevent dependency “spaghetti.”
- CI/CD & Build Tools: Add a note on the use of GitHub workflows in the .github folder and build scripts (like in docs and tools) that help automate testing, deployment, and documentation generation.

##### Relevant technologies and frameworks
- Python as the main programming language.
- Tools integration via WebAssembly and containerized docks.
- Support for various agent frameworks (Langchain, Llamaindex, etc.) and integration with LLM APIs (from OpenAI, Anthropic, etc.).
- OAuth and token strategies for authentication, interfacing with external services (e.g., Slack, GitHub, Calendly).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client/Agent Layer
    subgraph "Client/Agent Layer"
        UA["User Agent (CLI/Examples)"]:::client
        AF["Agent Framework (Langchain, Llamaindex, etc.)"]:::client
    end

    %% Core Service Layer
    subgraph "Core Service Layer"
        HC["Hyperpocket Core"]:::core
        CS["Session Store (In-memory/Redis)"]:::core
        CONF["Configuration (settings.toml, .secrets.toml)"]:::core
        AUTH["Authentication (OAuth,Token)"]:::core
    end

    %% Plugin & Tools Layer
    subgraph "Plugin & Tools Layer"
        EXT["Extensions/Plugins"]:::extension
        DOCK["Docks Integration (WASM Isolation)"]:::dock
        TOOL["Tools Repository"]:::tool
    end

    %% Ancillary Services
    subgraph "Ancillary Services"
        CICD["CI/CD Pipeline (GitHub Actions)"]:::ancillary
        DOC["Documentation"]:::ancillary
        EX["Examples & Scripts"]:::ancillary
    end

    %% Data Flow Connections
    UA -->|"initiates"| AF
    AF -->|"calls"| HC
    HC -->|"integrates"| EXT
    HC -->|"binds"| DOCK
    DOCK -->|"executes"| TOOL
    HC -->|"reads"| CONF
    HC -->|"manages"| CS
    HC -->|"performs"| AUTH
    EXT -->|"utilizes"| AUTH
    AF -->|"demonstrates"| EX
    CICD -->|"tests/deploys"| HC
    DOC -->|"documents"| HC
    CICD -->|"supports"| DOC

    %% Click Events
    click HC "https://github.com/vessl-ai/hyperpocket/tree/main/libs/hyperpocket"
    click EXT "https://github.com/vessl-ai/hyperpocket/tree/main/libs/extensions"
    click DOCK "https://github.com/vessl-ai/hyperpocket/tree/main/libs/docks"
    click TOOL "https://github.com/vessl-ai/hyperpocket/tree/main/tools"
    click EX "https://github.com/vessl-ai/hyperpocket/tree/main/examples"
    click CICD "https://github.com/vessl-ai/hyperpocket/blob/main/.github"
    click DOC "https://github.com/vessl-ai/hyperpocket/tree/main/docs"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef extension fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef dock fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef tool fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef ancillary fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
