# hypermusic-ai/pt architecture

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

- Interactive diagram: https://gitdiagram.com/hypermusic-ai/pt
- Repository: https://github.com/hypermusic-ai/pt

## Overview

##### Project type and purpose
- This is a multi-stack blockchain project called “Performative Transactions.”
- It has three main codebases:
- cpp/ – an off-chain C++ node framework (server, networking, registry, operand processing)
- solidity/ – Ethereum smart-contract modules, scripts, tests (Hardhat, Ethers/Web3)
- solana/ – Solana chain-program code (C++ via CMake, Dockerized)

##### File structure
- Top-level dirs:
- cpp/ – subdivided into include (PT core, concepts, registry, operand), network (TCP/UDP/Server), native wrappers (Unix/Windows), src, and CMake configs.
- solidity/ – Hardhat config, contracts (organized by feature, condition, ownable, registry, transformation), scripts, tests, package.json, tsconfig.
- solana/ – CMakeLists, Dockerfile, src/lib.cpp and main.cpp for the Solana program.
- assets/ – CSS/images for documentation or UI site.
- Config/build files: CMakeLists, deps.cmake, Dockerfile, hardhat.config.ts, .vscode settings, tsconfig.json.

##### README insights
- The repo is explicitly divided by smart-contract language (Solidity on Ethereum vs C++ for server node).
- External documentation link provided (docs site).

a. Main components:
1. Front-end/docs (optional UI or assets/css site)
2. Off-chain C++ node
– Core modules: PT (Performative Transaction) logic, concepts, operands, registry
– Native abstraction layer (Unix/Windows)
– Network layer (TCP, UDP, Server endpoints)
3. Ethereum blockchain
– Solidity contracts (conditions, features, transformations, registry, ownable)
– Deployment scripts (Hardhat/Ethers/Web3)
4. Solana blockchain
– Solana program (C++ chain-code)
– Docker container for Solana runtime
b. Relationships & interactions:
– C++ node ⇄ Ethereum: via JSON-RPC over HTTP/WebSocket, invoking contract functions, listening to events
– C++ node ⇄ Solana: via RPC endpoints or direct program instructions, submitting transactions
– Front-end/UI (if present) ⇄ C++ node: REST or WebSocket APIs
– Deployment scripts ⇄ blockchains: orchestrate contract/program deployment
c. Architectural patterns and design principles:
– Modular layering: separation of core logic, network, and native abstraction
– Adapter pattern: native wrapper to decouple OS specifics
– Plugin‐style grouping in solidity/contracts to allow independent features (conditions, transformations, etc.)
– Infrastructure-as-code: Dockerfile for Solana, CMake for cross-platform builds, Hardhat for Ethereum
d. Technologies/frameworks:
– C++17, CMake, cross‐platform (Unix/Windows)
– Boost.Asio-style networking (TCP/UDP server)
– Hardhat, TypeScript, Web3/Ethers.js for Ethereum
– Solana SDK in C++ with Docker for on‐chain program

## Diagram (Mermaid)

```mermaid
graph TD
    %% Front-end / Docs
    subgraph "Front-end / Docs"
        FE_CSS["assets/css/style.css"]:::frontend
        FE_IMG["assets/images/"]:::frontend
        FE_MD["index.md"]:::frontend
    end

    %% Off-chain C++ Node
    subgraph "Off-chain C++ Node" 
        direction TB
        subgraph "Core Logic" 
            PT_HPP["PT.hpp"]:::offchain
            PT_CPP["PT.cpp"]:::offchain
            CFWD["concept-fwd.hpp"]:::offchain
            CONCEPT_HPP["concept.hpp"]:::offchain
            CONCEPT_CPP["concept.cpp"]:::offchain
            OFWD["operand-fwd.hpp"]:::offchain
            OPERAND_HPP["operand.hpp"]:::offchain
            OPERAND_CPP["operand.cpp"]:::offchain
            REG_HPP["registry.hpp"]:::offchain
            REG_CPP["registry.cpp"]:::offchain
        end
        subgraph "Native Abstraction" 
            NACMA["native/CMakeLists.txt"]:::tooling
            NATIVE_HPP["native.hpp"]:::offchain
            UNIX_HPP["unix-native.hpp"]:::offchain
            WIN_HPP["windows-native.hpp"]:::offchain
            NATIVE_CPP["native.cpp"]:::offchain
            WIN_CPP["windows-native.cpp"]:::offchain
        end
        subgraph "Network Layer"
            NETCMA["network/CMakeLists.txt"]:::tooling
            NET_HPP["network.hpp"]:::offchain
            SRV_HPP["server.hpp"]:::offchain
            TCP_HPP["tcp.hpp"]:::offchain
            UDP_HPP["udp.hpp"]:::offchain
            NET_CPP["network.cpp"]:::offchain
            SRV_CPP["server.cpp"]:::offchain
            TCP_CPP["tcp.cpp"]:::offchain
            UDP_CPP["udp.cpp"]:::offchain
        end
        subgraph "Entry & Build"
            MAIN_CPP["main.cpp"]:::offchain
            CMAKE["CMakeLists.txt"]:::tooling
            DEPS["deps.cmake"]:::tooling
        end
    end

    %% Ethereum Blockchain
    subgraph "Ethereum Blockchain"
        direction TB
        subgraph "Contracts"
            SOL_COND["contracts/condition/"]:::ethereum
            SOL_FEAT["contracts/feature/"]:::ethereum
            SOL_OWN["contracts/ownable/"]:::ethereum
            SOL_REG["contracts/registry/"]:::ethereum
            SOL_TRANS["contracts/transformation/"]:::ethereum
        end
        subgraph "Deployment & Tooling"
            HH_CFG["hardhat.config.ts"]:::tooling
            PKG_JSON["package.json"]:::tooling
            TS_CFG["tsconfig.json"]:::tooling
        end
        subgraph "Scripts"
            DEP_ETHERS["deploy_with_ethers.ts"]:::tooling
            DEP_WEB3["deploy_with_web3.ts"]:::tooling
            LIB_ETHERS["ethers-lib.ts"]:::tooling
            LIB_WEB3["web3-lib.ts"]:::tooling
        end
        subgraph "Tests"
            TEST_LOCK["Lock.ts"]:::tooling
            TEST_UT["test/ut/"]:::tooling
        end
    end

    %% Solana Blockchain
    subgraph "Solana Blockchain"
        direction TB
        SOL_CMA["CMakeLists.txt"]:::tooling
        SOL_DOCKER["Dockerfile"]:::tooling
        SOL_LIB["lib.cpp"]:::solana
        SOL_MAIN["main.cpp"]:::solana
    end

    %% Interactions
    FE_MD -->|"REST/WebSocket"| MAIN_CPP
    PT_CPP -->|"JSON-RPC HTTP/WebSocket"| SOL_COND
    PT_CPP -->|"JSON-RPC HTTP/WebSocket"| SOL_FEAT
    PT_CPP -->|"JSON-RPC HTTP/WebSocket"| SOL_OWN
    PT_CPP -->|"JSON-RPC HTTP/WebSocket"| SOL_REG
    PT_CPP -->|"JSON-RPC HTTP/WebSocket"| SOL_TRANS
    MAIN_CPP -->|"Solana RPC Instructions"| SOL_LIB
    SOL_LIB -->|"Dockerize & Deploy"| SOL_DOCKER
    SOL_CMA --> SOL_LIB
    CMAKE --> MAIN_CPP
    HH_CFG --> SOL_COND
    HH_CFG --> SOL_FEAT
    HH_CFG --> SOL_OWN
    HH_CFG --> SOL_REG
    HH_CFG --> SOL_TRANS

    %% Click Events
    click FE_CSS "https://github.com/hypermusic-ai/pt/blob/main/assets/css/style.css"
    click FE_IMG "https://github.com/hypermusic-ai/pt/tree/main/assets/images/"
    click FE_MD "https://github.com/hypermusic-ai/pt/blob/main/index.md"
    click PT_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/PT.hpp"
    click PT_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/src/PT.cpp"
    click CFWD "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/concept-fwd.hpp"
    click CONCEPT_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/concept.hpp"
    click CONCEPT_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/src/concept.cpp"
    click OFWD "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/operand-fwd.hpp"
    click OPERAND_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/operand.hpp"
    click OPERAND_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/src/operand.cpp"
    click REG_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/include/registry.hpp"
    click REG_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/src/registry.cpp"
    click NACMA "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/CMakeLists.txt"
    click NATIVE_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/include/native.hpp"
    click UNIX_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/include/unix-native.hpp"
    click WIN_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/include/windows-native.hpp"
    click NATIVE_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/src/native.cpp"
    click WIN_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/native/src/windows-native.cpp"
    click NETCMA "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/CMakeLists.txt"
    click NET_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/include/network.hpp"
    click SRV_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/include/server.hpp"
    click TCP_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/include/tcp.hpp"
    click UDP_HPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/include/udp.hpp"
    click NET_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/src/network.cpp"
    click SRV_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/src/server.cpp"
    click TCP_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/src/tcp.cpp"
    click UDP_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/network/src/udp.cpp"
    click MAIN_CPP "https://github.com/hypermusic-ai/pt/blob/main/cpp/src/main.cpp"
    click CMAKE "https://github.com/hypermusic-ai/pt/blob/main/cpp/CMakeLists.txt"
    click DEPS "https://github.com/hypermusic-ai/pt/blob/main/cpp/deps.cmake"
    click SOL_COND "https://github.com/hypermusic-ai/pt/tree/main/solidity/contracts/condition/"
    click SOL_FEAT "https://github.com/hypermusic-ai/pt/tree/main/solidity/contracts/feature/"
    click SOL_OWN "https://github.com/hypermusic-ai/pt/tree/main/solidity/contracts/ownable/"
    click SOL_REG "https://github.com/hypermusic-ai/pt/tree/main/solidity/contracts/registry/"
    click SOL_TRANS "https://github.com/hypermusic-ai/pt/tree/main/solidity/contracts/transformation/"
    click HH_CFG "https://github.com/hypermusic-ai/pt/blob/main/solidity/hardhat.config.ts"
    click PKG_JSON "https://github.com/hypermusic-ai/pt/blob/main/solidity/package.json"
    click TS_CFG "https://github.com/hypermusic-ai/pt/blob/main/solidity/tsconfig.json"
    click DEP_ETHERS "https://github.com/hypermusic-ai/pt/blob/main/solidity/scripts/deploy_with_ethers.ts"
    click DEP_WEB3 "https://github.com/hypermusic-ai/pt/blob/main/solidity/scripts/deploy_with_web3.ts"
    click LIB_ETHERS "https://github.com/hypermusic-ai/pt/blob/main/solidity/scripts/ethers-lib.ts"
    click LIB_WEB3 "https://github.com/hypermusic-ai/pt/blob/main/solidity/scripts/web3-lib.ts"
    click TEST_LOCK "https://github.com/hypermusic-ai/pt/blob/main/solidity/test/Lock.ts"
    click TEST_UT "https://github.com/hypermusic-ai/pt/tree/main/solidity/test/ut/"
    click SOL_CMA "https://github.com/hypermusic-ai/pt/blob/main/solana/CMakeLists.txt"
    click SOL_DOCKER "https://github.com/hypermusic-ai/pt/tree/main/solana/Dockerfile"
    click SOL_LIB "https://github.com/hypermusic-ai/pt/blob/main/solana/src/lib.cpp"
    click SOL_MAIN "https://github.com/hypermusic-ai/pt/blob/main/solana/src/main.cpp"

    %% Styles
    classDef frontend fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef offchain fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef ethereum fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef solana fill:#98FB98,stroke:#333,stroke-width:1px
    classDef tooling fill:#D3D3D3,stroke:#333,stroke-width:1px
```
