# clarkjoao/dappkit architecture

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

- Interactive diagram: https://gitdiagram.com/clarkjoao/dappkit
- Repository: https://github.com/clarkjoao/dappkit

## Overview

##### Project Type and Purpose
- This is a TypeScript-based JavaScript SDK (“dappkit”) for Web3 projects. It provides:
- A unified Web3 connection layer
- Curated, ready-to-use contract wrappers (ERC20, ERC4626, Sablier, Uniswap, custom contracts, etc.)
- Shared base classes, interface definitions, models, utilities
- Command-line/build tools for compiling and cleaning contract ABIs
- Intended for both client-side (browser) and server-side (Node.js) use.

##### File Structure Highlights
- contracts/… : Solidity source code and protocol-specific subfolders
- src/
- base/ : generic contract-wrapper primitives (Ownable, Pausable, Stakeable, IPFS wrapper, Web3Connection)
- interfaces/ : typed method signatures, event and modifier definitions
- models/ : concrete wrappers around specific contracts (ERC20, UniswapRouter, Sablier, etc.)
- utils/ : helper functions (transaction handling, JSON-RPC param formatting, constant definitions)
- index.ts : public API aggregation
- tools/ : scripts (compile.mjs, contract-json-cleaner.mjs, size checks)
- test/ : unit and integration tests for base, models, utils
- docker-compose.yml & Dockerfile: local chain & environment setup for CI/tests
- CI: GitHub Actions integration-tests.yml

##### Additional README Insights
- Emphasis on instantiating Web3Connection, then using model classes to deploy/interact
- Guides for client, server, advanced usage (IPFS, custom ABI, Docker)
- Published to npm (`@taikai/dappkit`), docs auto-generated via `npm run docs`

1. Developer Application
- Browser or Node.js code importing dappkit
2. dappkit SDK
- Public API (src/index.ts)
- Web3Connection module
- Contract Wrapper layer
– Base primitives (Ownable, Pausable, use-model, web3-contract)
– Models (ERC20, Sablier, Uniswap, custom)
– Interfaces (method/event definitions)
- Utility layer (transaction handler, JSON-RPC params, constants)
- IPFS wrapper (optional metadata/pin)
3. Build & Tooling
- tools/compile.mjs → compiles Solidity under contracts/ → JSON ABIs
- contract-json-cleaner → strips extra fields
4. Test & CI Environment
- test/ suites triggered by GitHub Actions
- docker-compose local blockchain node for integration tests
5. External Services
- Blockchain RPC endpoint (Infura, Alchemy, local Geth)
- IPFS gateway or node
- NPM registry (package publish)
- Developer App → imports → dappkit Public API
- Public API → uses → Web3Connection to establish JSON-RPC channel to Blockchain
- Contract Wrappers → invoke → Web3Connection.web3 → send transactions or calls
- Web3Connection → returns → Promises (tx receipts, chain data) back to App
- IPFS Wrapper → sends/receives → HTTP API to IPFS node/gateway
- tools/compile.mjs → reads → contracts/ → outputs → build artifacts → published in npm
- CI pipeline → runs → tests against local blockchain via Docker
c. Architectural Patterns and Principles:
- Layered architecture: Public API → Domain (models & interfaces) → Infrastructure (web3 + IPFS)
- Wrapper/Adapter pattern for contracts
- Factory pattern in model constructors for contract instantiation
- Single Responsibility: each module has one clear purpose (connection vs. model vs. util)
- Extensibility through new models/interfaces under src/models & src/interfaces
d. Key Technologies & Frameworks:
- TypeScript (tsconfig.json)
- web3.js (wrapped in Web3Connection)
- IPFS HTTP API wrapper
- Solidity compiler (via tools/compile.mjs)
- Docker & docker-compose for local chain
- GitHub Actions for CI
- npm for package management

##### Final Advice
- 4 layers (Application, SDK, Tooling, External) in one cohesive view
- Don’t omit the compile-to-ABI/build pipeline and the CI/test harness
- Detail how modules relate: models rely on base, which rely on Web3Connection
- Both read-only (call) and transactional (send) flows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Application
    subgraph "Developer Application" 
        Browser["Browser (Client-Side)"]:::app
        NodeApp["Node.js (Server-Side)"]:::app
    end

    %% SDK Layer
    subgraph "dappkit SDK" 
        PublicAPI["Public API"]:::sdk
        Web3Conn["Web3Connection"]:::sdk
        IPFSWrapper["IPFS Wrapper"]:::sdk

        subgraph "Base Primitives"
            ModelBase["model.ts"]:::sdk
            Ownable["ownable.ts"]:::sdk
            Pausable["pausable.ts"]:::sdk
            Stakeable["stakeable.ts"]:::sdk
            UseModel["use-model.ts"]:::sdk
            Web3Contract["web3-contract.ts"]:::sdk
            Governed["governed.ts"]:::sdk
        end

        InterfaceDir["Interfaces"]:::sdk
        subgraph "Contract Models"
            ERC20["erc20.ts"]:::sdk
            ERC4626["erc4626.ts"]:::sdk
            Sablier["sablier.ts"]:::sdk
            UniswapFactory["uniswap-v3-factory.ts"]:::sdk
            UniswapRouter["uniswap-v3-router-bridge.ts"]:::sdk
            OtherModels["other models"]:::sdk
        end

        subgraph "Utilities"
            TxHandler["transaction-handler.ts"]:::sdk
            JSONRPCParams["json-rpc-params.ts"]:::sdk
            Constants["constants.ts"]:::sdk
            OtherUtils["other utils"]:::sdk
        end
    end

    %% Build & Tooling
    subgraph "Build & Tooling" 
        Compile["compile.mjs"]:::tool
        Cleaner["contract-json-cleaner.mjs"]:::tool
        SizeCheck["contract-size.mjs"]:::tool
        ContractsDir["contracts/"]:::tool
    end

    %% Test & CI
    subgraph "Test & CI" 
        Tests["test/ suites"]:::tool
        CI["integration-tests.yml"]:::tool
        DockerCompose["docker-compose.yml"]:::tool
        DockerFile["Dockerfile"]:::tool
    end

    %% External Services
    subgraph "External Services" 
        RPC["Blockchain RPC Node"]:::ext
        IPFSNode["IPFS Node/Gateway"]:::ext
        NPMReg["npm Registry"]:::ext
    end

    %% Connections
    Browser -->|imports| PublicAPI
    NodeApp -->|imports| PublicAPI

    PublicAPI -->|uses| Web3Conn
    PublicAPI -->|exposes| InterfaceDir
    PublicAPI -->|calls| ERC20
    PublicAPI -->|calls| ERC4626
    PublicAPI -->|calls| Sablier
    PublicAPI -->|calls| UniswapFactory
    PublicAPI -->|calls| UniswapRouter
    PublicAPI -->|calls| OtherModels
    PublicAPI -->|uses| TxHandler
    PublicAPI -->|uses| JSONRPCParams
    PublicAPI -->|uses| Constants
    PublicAPI -->|uses| OtherUtils
    PublicAPI -->|uses| IPFSWrapper

    Web3Conn -->|connects| RPC
    IPFSWrapper -->|connects| IPFSNode

    ERC20 -->|extends| ModelBase
    ERC4626 -->|extends| ModelBase
    Sablier -->|extends| ModelBase
    UniswapFactory -->|extends| ModelBase
    UniswapRouter -->|extends| ModelBase
    OtherModels -->|extends| ModelBase

    ModelBase -->|inherits| Web3Contract
    Ownable -->|mixes in| ModelBase
    Pausable -->|mixes in| ModelBase
    Stakeable -->|mixes in| ModelBase
    UseModel -->|factory for| ContractModels
    Governed -->|mixes in| ModelBase

    Compile -->|reads| ContractsDir
    Compile -->|outputs ABIs| Cleaner
    Cleaner -->|cleans| Compile
    Compile -->|publishes| NPMReg
    Cleaner -->|publishes| NPMReg
    SizeCheck -->|checks| ContractsDir

    CI -->|runs| Tests
    CI -->|uses| DockerCompose
    CI -->|uses| DockerFile
    Tests -->|tests| Web3Conn
    Tests -->|tests| IPFSWrapper
    Tests -->|tests| OtherModels
    Tests -->|tests| OtherUtils

    %% Click Events
    click PublicAPI "https://github.com/clarkjoao/dappkit/blob/master/src/index.ts"
    click Web3Conn "https://github.com/clarkjoao/dappkit/blob/master/src/base/web3-connection.ts"
    click IPFSWrapper "https://github.com/clarkjoao/dappkit/blob/master/src/base/ipfs-wrapper.ts"
    click ModelBase "https://github.com/clarkjoao/dappkit/blob/master/src/base/model.ts"
    click Ownable "https://github.com/clarkjoao/dappkit/blob/master/src/base/ownable.ts"
    click Pausable "https://github.com/clarkjoao/dappkit/blob/master/src/base/pausable.ts"
    click Stakeable "https://github.com/clarkjoao/dappkit/blob/master/src/base/stakeable.ts"
    click UseModel "https://github.com/clarkjoao/dappkit/blob/master/src/base/use-model.ts"
    click Web3Contract "https://github.com/clarkjoao/dappkit/blob/master/src/base/web3-contract.ts"
    click Governed "https://github.com/clarkjoao/dappkit/blob/master/src/base/governed.ts"
    click InterfaceDir "https://github.com/clarkjoao/dappkit/tree/master/src/interfaces/"
    click ERC20 "https://github.com/clarkjoao/dappkit/blob/master/src/models/erc20.ts"
    click ERC4626 "https://github.com/clarkjoao/dappkit/blob/master/src/models/erc4626.ts"
    click Sablier "https://github.com/clarkjoao/dappkit/blob/master/src/models/sablier.ts"
    click UniswapFactory "https://github.com/clarkjoao/dappkit/blob/master/src/models/uniswap-v3-factory.ts"
    click UniswapRouter "https://github.com/clarkjoao/dappkit/blob/master/src/models/uniswap-v3-router-bridge.ts"
    click OtherModels "https://github.com/clarkjoao/dappkit/tree/master/src/models/"
    click TxHandler "https://github.com/clarkjoao/dappkit/blob/master/src/utils/transaction-handler.ts"
    click JSONRPCParams "https://github.com/clarkjoao/dappkit/blob/master/src/utils/json-rpc-params.ts"
    click Constants "https://github.com/clarkjoao/dappkit/blob/master/src/utils/constants.ts"
    click OtherUtils "https://github.com/clarkjoao/dappkit/tree/master/src/utils/"
    click ContractsDir "https://github.com/clarkjoao/dappkit/tree/master/contracts/"
    click Compile "https://github.com/clarkjoao/dappkit/blob/master/tools/compile.mjs"
    click Cleaner "https://github.com/clarkjoao/dappkit/blob/master/tools/contract-json-cleaner.mjs"
    click SizeCheck "https://github.com/clarkjoao/dappkit/blob/master/tools/contract-size.mjs"
    click Tests "https://github.com/clarkjoao/dappkit/tree/master/test/"
    click CI "https://github.com/clarkjoao/dappkit/blob/master/.github/workflows/integration-tests.yml"
    click DockerCompose "https://github.com/clarkjoao/dappkit/blob/master/docker-compose.yml"
    click DockerFile "https://github.com/clarkjoao/dappkit/tree/master/Dockerfile"

    %% Styles
    classDef sdk fill:#cce5ff,stroke:#0085cc
    classDef ext fill:#ccffcc,stroke:#339933
    classDef app fill:#ffdd99,stroke:#cc7a00
    classDef tool fill:#e0e0e0,stroke:#888888
```
