# superfluid-org/protocol-monorepo architecture

> Architecture diagram of the GitHub repository superfluid-org/protocol-monorepo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/superfluid-org/protocol-monorepo
- Repository: https://github.com/superfluid-org/protocol-monorepo

## Overview

##### Project Type and Purpose
- This is a protocol-monorepo for the Superfluid real-time finance framework, combining:
- EVM smart contracts (packages/ethereum-contracts, automation-contracts, scheduler)
- TypeScript SDKs (packages/sdk-core, packages/sdk-redux, packages/js-sdk deprecated)
- Metadata (package/metadata), testing harnesses (packages/hot-fuzz), examples, Haskell specs, and CI/CD

##### File-Structure Analysis
- Top-level “packages/” directory holds each logical component as its own package.
- Smart-contract packages include contracts/, tests/, dev scripts, deploy scripts, Hardhat and Foundry configs.
- sdk-redux builds on sdk-core exposing Redux slices via RTK Query for frontend consumption.
- metadata provides static JSON/CJS/TS modules with network addresses.
- hot-fuzz wraps Echidna for contract fuzz testing.
- examples directories show Next.js and React front-ends consuming sdk-redux.
- spec-haskell and solidity-semantic-money are reference implementations & formal specs.

##### README Insights
- Confirms monorepo nature, lists each published package and its role.

a. Main Components
- Ethereum Networks (Mainnet/Testnets) hosting Superfluid core contracts (Host, CFA, IDA, GDA, governance, tokens).
- SDK-Redux layer building on SDK-Core to provide React-friendly RTK Query endpoints and transaction tracking.
- Front-end Example Apps (Next.js, React) connecting via SDK-Redux.
- Testing Tools: hot-fuzz (Echidna wrapper), Foundry/Hardhat test runners.

b. Relationships & Data Flows
- Front-end → Redux slice (SDK-Redux) → SDK-Core → Ethereum JSON-RPC (read/write)
- Smart contracts emit events → Graph Node ingest → GraphQL schema
- Metadata feeds both SDK-Core and front-ends with correct addresses/URLs

c. Architectural Patterns
- Monorepo with independent packages → clear separation of concerns
- Event-driven indexing via TheGraph

d. Key Technologies
- Solidity, Hardhat, Foundry for contracts
- TypeScript, Node.js for SDKs and scripts
- Redux Toolkit Query for client state management
- Echidna for fuzz testing in hot-fuzz wrapper
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% On-Chain Layer
    subgraph "On-Chain Layer"
        ethereum["Ethereum Networks<br/>(Mainnet/Testnets)"]:::onchain
        ethContracts["Ethereum Smart Contracts Core"]:::onchain
        autoWrap["Automation Autowrap Contracts"]:::onchain
        scheduler["Automation Scheduler Contracts"]:::onchain
    end

    %% Indexing Layer
    subgraph "Indexing Layer"
        graphNode["TheGraph Node"]:::indexing
        mappings["Mappings & Handlers"]:::indexing
        testsSubgraph["Subgraph Tests & Validation"]:::indexing
    end

    %% SDK Layer
    subgraph "SDK Layer"
        sdkCore["SDK-Core Library"]:::sdk
        subclient["Subgraph Client Module"]:::sdk
        sdkRedux["SDK-Redux Layer"]:::sdk
        rtkQuery["RTK Query Slices"]:::sdk
        txTracker["Transaction Tracker Slice"]:::sdk
        jsSdk["Deprecated JS SDK"]:::sdk
    end

    %% Metadata
    metadata["Metadata Package"]:::sdk

    %% Frontend Examples
    subgraph "Frontend Examples"
        nextjs["Next.js TS App"]:::frontend
        reactApp["React TS App"]:::frontend
    end

    %% Testing Tools
    subgraph "Testing Tools"
        hotFuzz["Fuzz Testing Harness"]:::testing
        hardhatFoundry["Foundry & Hardhat Tests"]:::testing
    end

    %% CI/CD & Tasks
    cicd["CI/CD Workflows"]:::cicd
    tasks["Automation & Utility Tasks"]:::cicd

    %% Relationships
    nextjs -->|"uses"| sdkRedux
    reactApp -->|"uses"| sdkRedux
    sdkRedux -->|"calls"| sdkCore
    sdkCore -->|"JSON-RPC read/write"| ethereum
    sdkCore -->|"GraphQL queries"| graphNode
    ethContracts -->|"deployed on"| ethereum
    autoWrap -->|"deployed on"| ethereum
    scheduler -->|"deployed on"| ethereum
    ethereum -->|"events emitted"| graphNode
    graphNode -->|"serves data"| sdkCore
    metadata -->|"provides addresses/endpoints"| sdkCore
    metadata -->|"provides addresses/endpoints"| nextjs
    metadata -->|"provides addresses/endpoints"| reactApp
    cicd -->|"build/test/deploy"| ethContracts
    cicd -->|"build/test/deploy"| graphNode
    cicd -->|"build/test/deploy"| sdkCore
    cicd -->|"build/test/deploy"| sdkRedux
    cicd -->|"run examples"| nextjs
    cicd -->|"run examples"| reactApp
    tasks -->|"orchestrates"| hotFuzz
    tasks -->|"orchestrates"| hardhatFoundry

    %% Click Events
    click ethContracts "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/ethereum-contracts"
    click autoWrap "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/automation-contracts/autowrap"
    click scheduler "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/automation-contracts/scheduler"
    click hardhatFoundry "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/ethereum-contracts/test"
    click hardhatFoundry "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/ethereum-contracts/test/foundry"
    click graphNode "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/subgraph"
    click mappings "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/subgraph/src/mappings"
    click testsSubgraph "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/subgraph/test"
    click testsSubgraph "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/subgraph/tests"
    click sdkCore "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/sdk-core"
    click subclient "https://github.com/superfluid-org/protocol-monorepo/blob/dev/packages/sdk-core/src/subgraph/SubgraphClient.ts"
    click subclient "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/sdk-core/src/subgraph"
    click rtkQuery "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/sdk-redux/src/reduxSlices/rtkQuery"
    click txTracker "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/sdk-redux/src/reduxSlices/transactionTrackerSlice"
    click jsSdk "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/js-sdk"
    click metadata "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/metadata"
    click hotFuzz "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/hot-fuzz"
    click specHaskell "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/spec-haskell"
    click solidityMoney "https://github.com/superfluid-org/protocol-monorepo/tree/dev/packages/solidity-semantic-money"
    click nextjs "https://github.com/superfluid-org/protocol-monorepo/tree/dev/sdk-redux-examples/sdk-redux-nextjs-typescript"
    click reactApp "https://github.com/superfluid-org/protocol-monorepo/tree/dev/sdk-redux-examples/sdk-redux-react-typecript"
    click cicd "https://github.com/superfluid-org/protocol-monorepo/tree/dev/.github/workflows"
    click tasks "https://github.com/superfluid-org/protocol-monorepo/tree/dev/tasks/"

    %% Styles
    classDef onchain fill:#ffe6e6,stroke:#cc0000,stroke-width:1px
    classDef indexing fill:#fff0b3,stroke:#cc9900,stroke-width:1px
    classDef sdk fill:#e6ffe6,stroke:#009933,stroke-width:1px
    classDef frontend fill:#e6f2ff,stroke:#0059b3,stroke-width:1px
    classDef testing fill:#fff0e6,stroke:#cc6600,stroke-width:1px
    classDef cicd fill:#e6ffff,stroke:#009999,stroke-width:1px
```
