# privately-exclusive/privately-smartcontract architecture

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

- Interactive diagram: https://gitdiagram.com/privately-exclusive/privately-smartcontract
- Repository: https://github.com/privately-exclusive/privately-smartcontract

## Overview

##### Project type and purpose
- This is a blockchain “core” repository for Privately, a platform for private-reference NFTs on the Base chain.
- It contains three Solidity smart contracts (ERC20 token, ERC721 collection, auction system), a TypeScript client library for meta-transaction flows, deployment & test scripts, plus Docker/Hardhat setups.

##### File structure
- Top‐level:
- contracts/ – Solidity code (PrivatelyCoin.sol, PrivatelyCollection.sol, PrivatelyAuctionSystem.sol)
- lib/ – TypeScript SDK (client.ts, modules for auctions, coin, collection) and its tests
- scripts/ – build-docs.sh, deploy.ts
- Dockerfile, docker-compose.yml/test, run_node.sh, run_tests.sh
- Hardhat configs (hardhat.config.js/ts)
- CI workflows (.github/workflows)
- Patterns:
- On‐chain vs off‐chain separation
- Meta-transaction EIP-712 layer
- Modular TS client (one module per contract)
- Containerized local development & CI

##### Insights from README
- Meta-transaction system: user signs off-chain → Relayer API → on-chain
- TypeScript library abstracts contract interactions and EIP-712 signature crafting
- Local Docker+Hardhat for reproducible dev/testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-Chain Layer
    subgraph "Off-Chain Components" 
        direction TB
        App["User Device & Privately App"]:::offchain
        subgraph "TypeScript Client Library (lib/src)" 
            direction TB
            Client["client.ts"]:::offchain
            subgraph "Common Utilities"
                direction TB
                CommonIdx["index.ts"]:::offchain
                PrivErr["privately.error.ts"]:::offchain
                ReqSig["request-signature.ts"]:::offchain
            end
            subgraph "Coin Module"
                direction TB
                coinClient["coin.client.ts"]:::offchain
                coinApprove["coin.approve.request.ts"]:::offchain
                coinTransfer["coin.transfer.request.ts"]:::offchain
                coinNonces["coin.nonces.ts"]:::offchain
                coinErrors["coin.errors.ts"]:::offchain
                coinIndex["index.ts"]:::offchain
            end
            subgraph "Collection Module"
                direction TB
                collClient["collection.client.ts"]:::offchain
                collMint["collection.mint.request.ts"]:::offchain
                collTransfer["collection.transfer.request.ts"]:::offchain
                collApprove["collection.approve.request.ts"]:::offchain
                collNonces["collection.nonces.ts"]:::offchain
                collNFT["collection.nft.ts"]:::offchain
                collIndex["index.ts"]:::offchain
            end
            subgraph "Auctions Module"
                direction TB
                aucClient["auctions.client.ts"]:::offchain
                aucCreate["auctions.create.request.ts"]:::offchain
                aucBid["auctions.bid.request.ts"]:::offchain
                aucNonces["auctions.nonces.ts"]:::offchain
                aucErrors["auctions.errors.ts"]:::offchain
                aucAuction["auctions.auction.ts"]:::offchain
                aucIndex["index.ts"]:::offchain
            end
        end
        Relayer["Meta-Transaction Relayer Service"]:::external
    end

    %% On-Chain Layer
    subgraph "On-Chain Components"
        direction TB
        BCNet["Base Blockchain Network"]:::blockchain
        subgraph "Smart Contracts"
            direction TB
            PCoin["PrivatelyCoin.sol"]:::blockchain
            PCollection["PrivatelyCollection.sol"]:::blockchain
            PAuction["PrivatelyAuctionSystem.sol"]:::blockchain
        end
    end

    %% Infrastructure Layer
    subgraph "Infrastructure & DevOps"
        direction TB
        Docker["Docker & Hardhat"]:::infra
        CI["GitHub Actions CI/CD"]:::infra
        DeployScript["deploy.ts"]:::infra
        DocsScript["build-docs.sh"]:::infra
    end

    %% Flows
    App -->|"signs EIP-712 payload"| Client
    Client -->|"submits signed payload"| Relayer
    Relayer -->|"RPC txn"| BCNet
    BCNet -->|"executes & emits events"| PCoin
    BCNet -->|"executes & emits events"| PCollection
    BCNet -->|"executes & emits events"| PAuction
    BCNet -->|"events"| Client

    CI --> DeployScript
    CI --> DocsScript
    CI --> Docker

    %% Click Events
    click PCoin "https://github.com/privately-exclusive/privately-smartcontract/blob/main/contracts/PrivatelyCoin.sol"
    click PCollection "https://github.com/privately-exclusive/privately-smartcontract/blob/main/contracts/PrivatelyCollection.sol"
    click PAuction "https://github.com/privately-exclusive/privately-smartcontract/blob/main/contracts/PrivatelyAuctionSystem.sol"
    click Client "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/client.ts"
    click CommonIdx "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/common/index.ts"
    click PrivErr "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/common/privately.error.ts"
    click ReqSig "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/common/request-signature.ts"
    click coinClient "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/coin.client.ts"
    click coinApprove "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/coin.approve.request.ts"
    click coinTransfer "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/coin.transfer.request.ts"
    click coinNonces "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/coin.nonces.ts"
    click coinErrors "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/coin.errors.ts"
    click coinIndex "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/coin/index.ts"
    click collClient "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.client.ts"
    click collMint "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.mint.request.ts"
    click collTransfer "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.transfer.request.ts"
    click collApprove "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.approve.request.ts"
    click collNonces "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.nonces.ts"
    click collNFT "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/collection.nft.ts"
    click collIndex "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/collection/index.ts"
    click aucClient "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.client.ts"
    click aucCreate "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.create.request.ts"
    click aucBid "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.bid.request.ts"
    click aucNonces "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.nonces.ts"
    click aucErrors "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.errors.ts"
    click aucAuction "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/auctions.auction.ts"
    click aucIndex "https://github.com/privately-exclusive/privately-smartcontract/blob/main/lib/src/modules/auctions/index.ts"
    click DeployScript "https://github.com/privately-exclusive/privately-smartcontract/blob/main/scripts/deploy.ts"
    click DocsScript "https://github.com/privately-exclusive/privately-smartcontract/blob/main/scripts/build-docs.sh"

    %% Styles
    classDef offchain fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef blockchain fill:#D0FFD0,stroke:#00AA00,color:#000
    classDef infra fill:#FFE0B2,stroke:#CC6600,color:#000
    classDef external fill:#F0F0F0,stroke:#888,color:#000
```
