# honeyhiveai/typescript-sdk architecture

> Architecture diagram of the GitHub repository honeyhiveai/typescript-sdk, 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/honeyhiveai/typescript-sdk
- Repository: https://github.com/honeyhiveai/typescript-sdk

## Overview

##### Project and Its Purpose
- HoneyHive is an SDK (and also an MCP server) designed to allow users and AI applications to interact with a range of resources (configurations, datapoints, datasets, events, experiments, metrics, projects, sessions, and tools) through a programmatically generated API.
- It supports both client-side usage (e.g., through standalone functions and API calls) and a standalone server mode (the MCP server that can be launched via CLI).

##### Main Components
a. SDK Client Library:
– Encapsulates authentication (bearerAuth), server URL handling, retry strategies, and debugging configuration.
– Provides access to a suite of functions (as seen in the “Available Resources and Operations” lists) with methods like create, update, delete and get for configurations, datapoints, datasets, etc.
– Organizes functions into modules (e.g., src/sdk, src/funcs). The core entry point is in src/index.ts and src/core.ts.
b. HTTP Client:
– A lightweight wrapper around the Fetch API (found in src/lib/http.ts) that supports hooks (beforeRequest, requestError) to alter requests, add headers (e.g., for custom HTTP client handlers) and manage errors.
– Handles retry logic configurable per-operation or globally (as described in the README).
c. MCP Server (Model Context Protocol Server):
– Implemented in its own module (src/mcp-server) with separate CLI commands (cli/start, cli/command.ts) that expose the SDK methods as tools for AI applications.
– Provides an alternative to using the SDK directly in client code by allowing the same operations to be executed via command line.
d. Operation Handlers and Standalone Functions:
– Within src/funcs and src/mcp-server/tools, you have discrete function modules that handle each API operation, such as creating events, retrieving datapoints, managing projects, etc.
– These modules use consistent validations, error handling (with SDKError and HTTP client errors) and follow the generated patterns.
e. Data Models and Schemas:
f. Utility Libraries and Hooks:
– The src/lib folder includes helper modules for encoding, security, retries, and logging.
– Hooks (in src/hooks) allow extra customization over request lifecycles.
g. Documentation and Tests:
– The docs directory holds markdown documentation (e.g., md files for each resource and operations overview).
– The tests directory (with integration tests, environment setups, and Docker/Makefile) validates the functionality of both the SDK and MCP server aspects.

##### Relationships and Interactions
– The SDK Client uses the HTTP Client to make network requests to the API backend. Its customizable hooks and retry strategies determine how each request is processed.
– Each functional module (for configurations, events, etc.) calls upon the shared libraries (models and lib functions) to validate inputs and interpret responses.
– For those running HoneyHive as an MCP server, the CLI module relays requests to the same underlying function modules that the SDK uses.
– Standalone functions allow for tree-shaken deployments by importing only what is needed.

##### Architectural Patterns and Design Principles
- Modularity: Each API resource is implemented as a separate module. This simplifies dependency management and testing.
- Separation of Concerns: Distinct layers for HTTP communications, business logic (operation handlers), data validation (models/schemas), and command-line interface (MCP server).
- Extensibility: Hooks (in the HTTP client and the registration under src/hooks) allow flexible customization of request/response handling.
- Error Handling Strategy: Centralized error types (SDKError, HTTP client errors) and detailed logging/debugging options to aid troubleshooting.

##### Relevant Technologies/Frameworks
– TypeScript as the main language.
– Node.js (v20+ for MCP server).
– Speakeasy for generating SDK components.
– Fetch API wrapped inside the HTTP client.
– Standard testing tools (Jest, integration tests scripts) and Docker/Makefile for test automation.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "SDK Client-Side"
        SDK_Core["SDK Client Core"]:::client
        SDK_Modules["SDK Resource Modules"]:::client
        SDK_Core --> SDK_Modules
        SDK_Modules --> HTTPC["HTTP Client"]:::service
    end

    subgraph "Operation Handlers (Client)"
        Ops_Client["Operation Handlers (Client Functions)"]:::handler
        HTTPC -->|"invokes"| Ops_Client
    end

    subgraph "MCP Server-Side"
        MCP_Server["MCP Server"]:::server
        Ops_MCP["Operation Handlers (MCP Tools)"]:::handler
        MCP_Server -->|"executes"| Ops_MCP
    end

    subgraph "Data & Validation"
        Data_Models["Data Models and Schemas"]:::model
        Ops_Client -->|"validates"| Data_Models
        Ops_MCP -->|"validates"| Data_Models
    end

    subgraph "Utilities"
        Utility_Lib["Utility Libraries"]:::util
        Hooks["Hooks"]:::util
        Utility_Lib --> Hooks
    end

    Docs["Documentation"]:::doc
    Tests["Tests"]:::test

    %% Connections to Utilities
    SDK_Core -->|"uses"| Utility_Lib
    HTTPC -->|"uses"| Utility_Lib
    Ops_Client -->|"uses"| Utility_Lib
    MCP_Server -->|"integrates"| Utility_Lib

    %% Connections to Docs and Tests
    Utility_Lib -->|"documented_by"| Docs
    Utility_Lib -->|"tested_by"| Tests

    %% Click Events
    click SDK_Core "https://github.com/honeyhiveai/typescript-sdk/blob/main/src/index.ts"
    click SDK_Modules "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/sdk"
    click HTTPC "https://github.com/honeyhiveai/typescript-sdk/blob/main/src/lib/http.ts"
    click Ops_Client "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/funcs"
    click MCP_Server "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/mcp-server"
    click Ops_MCP "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/mcp-server/tools"
    click Data_Models "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/models"
    click Utility_Lib "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/lib"
    click Hooks "https://github.com/honeyhiveai/typescript-sdk/tree/main/src/hooks"
    click Docs "https://github.com/honeyhiveai/typescript-sdk/tree/main/docs"
    click Tests "https://github.com/honeyhiveai/typescript-sdk/tree/main/tests"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef service fill:#ccf,stroke:#333,stroke-width:2px;
    classDef handler fill:#cfc,stroke:#333,stroke-width:2px;
    classDef server fill:#fc9,stroke:#333,stroke-width:2px;
    classDef model fill:#cff,stroke:#333,stroke-width:2px;
    classDef util fill:#ffc,stroke:#333,stroke-width:2px;
    classDef doc fill:#eee,stroke:#333,stroke-width:2px;
    classDef test fill:#efe,stroke:#333,stroke-width:2px;
```
