# kphanipavan/harmoney architecture

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

- Interactive diagram: https://gitdiagram.com/kphanipavan/harmoney
- Repository: https://github.com/kphanipavan/harmoney

## Overview

##### Main Components
- Client: Initiates function calls using harmoney/client.py.
- Broker: Acts as the mediator (using harmoney/router.py) that handles connection management and load balancing between clients and runners.
- Runner: Executes the requested functions (using harmoney/runner.py) and returns results.
- (Optionally) Utility/helper layers: Indicate support modules like harmoney/_callSpec.py, which may be used for validating or specifying function call details.
- External Dependencies/Technologies: These include the networking layer (websockets), FastAPI (for creating the broker’s service), Uvicorn (for serving the API), Requests, and Pydantic for data validation.

##### Relationships and Interactions
- The Client sends a request (via cli.runSingle) to the Broker.
- The Broker (router) listens on a specific IP/port, routing the request to one or more connected Runners.
- Runners (via run.startRunner) register and listen for assigned tasks. They execute the function (e.g., “custFn”) and return the result back to the Broker.
- The Broker then forwards the result back to the Client.

##### Architectural Patterns and Design Principles
- Distributed System Design: The framework separates concerns by decoupling client requests from the execution environment.
- Message Routing/Load Balancing: Broker is central to handling incoming requests and distributing them to available Runners.
- Asynchronous Communication: Although not fully detailed in the current README, dependencies (websockets, FastAPI, and Uvicorn) suggest an asynchronous event-driven architecture.
- Loose Coupling & Extensibility: The design allows the addition of multiple runners and the possibility to extend functionality by altering individual components.

##### Important Details to Capture
- Network topology, such as indicating the IP and port configuration (shown in the README example) for better visual understanding.
- Anticipated improvements or TODO aspects (like enhanced error handling and dependency refinements), if relevant for planning extensions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        A("Client"):::client
    end

    %% Broker Layer
    subgraph "Broker Layer"
        B("Broker (Router)"):::broker
        E("Dependencies<br>FastAPI, Uvicorn,<br>Requests, Pydantic"):::external
    end

    %% Runner Layer
    subgraph "Runner Layer"
        C("Runner"):::runner
    end

    %% Utility/Helper Module
    subgraph "Utility/Helper"
        D("CallSpec Utility"):::utility
    end

    %% Interactions
    A -->|"function_call_request<br>via_websockets"| B
    B -->|"forwards_task"| C
    C -->|"returns_result<br>(Python_Function_Execution)"| B
    B -->|"final_response"| A
    B ---|"validates_call_spec"| D
    C ---|"uses_validation"| D

    %% Click Events
    click A "https://github.com/kphanipavan/harmoney/blob/master/harmoney/client.py"
    click B "https://github.com/kphanipavan/harmoney/blob/master/harmoney/router.py"
    click C "https://github.com/kphanipavan/harmoney/blob/master/harmoney/runner.py"
    click D "https://github.com/kphanipavan/harmoney/blob/master/harmoney/_callSpec.py"

    %% Styles
    classDef client fill:#a1d99b,stroke:#000,stroke-width:2px;
    classDef broker fill:#9ecae1,stroke:#000,stroke-width:2px;
    classDef runner fill:#fdae6b,stroke:#000,stroke-width:2px;
    classDef utility fill:#d7b5d8,stroke:#000,stroke-width:2px;
    classDef external fill:#c6dbef,stroke:#000,stroke-width:2px;
```
