# vpatel95/hyper-line architecture

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

- Interactive diagram: https://gitdiagram.com/vpatel95/hyper-line
- Repository: https://github.com/vpatel95/hyper-line

## Overview

##### Main Components
a. User Node (avd_user)
- Loads the user’s application as a shared object (.so)
- Reads `user.json` config
- Initiates pipeline request to Server over TCP
b. Server Node (avd_server)
- Reads `server.json` config
- Listens on two ports: one for user requests, one for worker registrations
- Manages task orchestration, worker registry, and final result collation
c. Worker Nodes (avd_worker)
- Each runs on its own machine
- Reads `worker.json` config
- Registers with Server
- Hosts a peer‐to‐peer server for inter‐stage communication
- Executes one pipeline stage (invokes user .so function)
d. Shared Libraries & Tools
- avd_log (logging)
- cJSON (JSON parsing)
- avd_pipe (message‐passing primitives)
- src/tools/avd_sim (optional simulator)

##### Relationships & Data Flows
1. User → Server: Pipeline request + serialized user config
2. Server → Worker: Stage assignment + input data
3. Worker → Worker: Stage‐to‐stage data forwarding (peer ports)
4. Last Worker → Server: Final stage output
5. Server → User: Aggregated result

##### Architectural Patterns
- Distributed assembly‐line/pipeline pattern
- Plugin pattern (user code loaded as .so)
- Master–worker orchestration (Server is Master, Workers are Slaves)
- Peer‐to‐peer chaining between Workers

##### Call out Key Technologies & Files
- Makefile/Common.mk: build orchestration
- `src/apps/...`: sample applications (encryption.so, sum.so)
- `src/lib`: core libraries (avd_log.c, cJSON.c)
- `src/include`: public APIs (avd_session.h, avd_message.h, etc.)
- `src/server`, `src/worker`, `src/user`: binaries avd_server, avd_worker, avd_user

##### Detailed Elements
- Clear labels on each component: name, binary filename, listening ports

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Tier
    user["avd_user<br/>(user.c)"]:::network
    config_user["user.json"]:::config
    user -->|"reads config"| config_user
    user -->|"Pipeline Request (TCP)"| server

    %% Server Tier
    server["avd_server<br/>(server.c)"]:::network
    config_server["server.json"]:::config
    server -->|"reads config"| config_server

    %% Worker Tier
    subgraph "Workers Pipeline"
        direction LR
        w1["avd_worker<br/>(worker.c)"]:::network
        config_w1["conf_w1.json"]:::config
        w1 -->|"reads config"| config_w1

        w2["avd_worker<br/>(worker.c)"]:::network
        config_w2["conf_w2.json"]:::config
        w2 -->|"reads config"| config_w2

        w3["avd_worker<br/>(worker.c)"]:::network
        config_w3["conf_w3.json"]:::config
        w3 -->|"reads config"| config_w3

        w4["avd_worker<br/>(worker.c)"]:::network
        config_w4["conf_w4.json"]:::config
        w4 -->|"reads config"| config_w4

        w1 -->|"ASSIGN_TASK (TCP)"| w2
        w2 -->|"STAGE_OUTPUT (Peer TCP)"| w3
        w3 -->|"STAGE_OUTPUT (Peer TCP)"| w4
    end

    %% Data Flows
    server -->|"ASSIGN_TASK (TCP)"| w1
    w4 -->|"FINAL_STAGE_OUTPUT (TCP)"| server
    server -->|"Aggregated Result (TCP)"| user

    %% Libraries & Tools
    subgraph "Libraries & Tools"
        direction TB
        log["avd_log"]:::lib
        cjson["cJSON"]:::lib
        pipe["avd_pipe"]:::lib
        session["avd_session"]:::lib
        message["avd_message"]:::lib
        sim["avd_sim"]:::tool
    end

    %% Dotted Dependencies
    log -.-> user
    log -.-> server
    log -.-> w1
    cjson -.-> user
    cjson -.-> server
    cjson -.-> w1
    pipe -.-> server
    pipe -.-> w1
    session -.-> server
    session -.-> w1
    message -.-> server
    message -.-> w1
    sim -.-> user

    %% Click Events
    click user "https://github.com/vpatel95/hyper-line/blob/master/src/user/user.c"
    click server "https://github.com/vpatel95/hyper-line/blob/master/src/server/server.c"
    click w1 "https://github.com/vpatel95/hyper-line/blob/master/src/worker/worker.c"
    click w2 "https://github.com/vpatel95/hyper-line/blob/master/src/worker/worker.c"
    click w3 "https://github.com/vpatel95/hyper-line/blob/master/src/worker/worker.c"
    click w4 "https://github.com/vpatel95/hyper-line/blob/master/src/worker/worker.c"
    click log "https://github.com/vpatel95/hyper-line/blob/master/src/lib/avd_log.c"
    click cjson "https://github.com/vpatel95/hyper-line/blob/master/src/lib/cJSON.c"
    click pipe "https://github.com/vpatel95/hyper-line/blob/master/src/include/avd_pipe.h"
    click session "https://github.com/vpatel95/hyper-line/blob/master/src/include/avd_session.h"
    click message "https://github.com/vpatel95/hyper-line/blob/master/src/include/avd_message.h"
    click sim "https://github.com/vpatel95/hyper-line/blob/master/src/tools/avd_sim.c"

    %% Styles
    classDef network fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tool fill:#90EE90,stroke:#000,stroke-width:1px
    classDef plugin fill:#D3D3D3,stroke:#000,stroke-width:1px
```
