# thematters/contracts architecture

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

- Interactive diagram: https://gitdiagram.com/thematters/contracts
- Repository: https://github.com/thematters/contracts

## Overview

##### Main Components
- Deployment & Network Environment: Highlight the different blockchain networks (Polygon Mainnet, Polygon Mumbai, OP Mainnet, and OP Sepolia) as the deployment targets. Show which contracts are deployed on which networks using information from the README.
- Development and Testing Infrastructure: Represent the build, deployment, and testing tools (foundry for testing and building, Makefile targets, and scripts in the "scripts" directory) that are used to manage the lifecycle of the contracts.
- External Interfaces: Include external services like Polygonscan/Etherscan for contract verification and monitoring. You might also note ABI generation and static analysis (e.g., via Slither and specific make targets).

##### Architectural Patterns and Technologies
- The repository follows a modular structure (each contract has its own directory and corresponding documentation) and leverages Foundry (indicated by foundry.toml, Makefile commands) for building and testing smart contracts. This underscores the testing-driven and modular design pattern.
- Integration of external libraries (like OpenZeppelin contracts, ds-test, and relay-context-contracts from the "lib" folder) which are critical in understanding security and standard implementations within the smart contracts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Testing Tools
    subgraph "Development & Testing Tools"
        D1["Makefile"]:::dev
        D2["foundry.toml"]:::dev
        subgraph "Scripts"
            D3["scripts/billboard"]:::dev
            D4["scripts/logbook-metadata.js"]:::dev
        end
        D5["src/test"]:::dev
    end

    %% Smart Contract Modules
    subgraph "Smart Contract Modules"
        S1["Logbook Contract Module\n(metadata logging)"]:::contract
        S2["TheSpace Contract Module\n(token management)"]:::contract
        S3["Billboard Contract Module\n(operator, registry, distribution)"]:::contract
        S4["Curation Contract Module"]:::contract
        S5["Snapper Contract Module"]:::contract
    end

    %% Deployment & Network Environment
    subgraph "Deployment & Network Environment"
        N1["Local Environment (.env.local.example)"]:::env
        N2["Polygon Mainnet (.env/polygon-mainnet.example)"]:::env
        N3["Polygon Mumbai (.env/polygon-mumbai.example)"]:::env
        N4["OP Mainnet (.env/op-mainnet.example)"]:::env
        N5["OP Sepolia (.env/op-sepolia.example)"]:::env
    end

    %% External Libraries & Interfaces
    subgraph "External Libraries & Interfaces"
        E1["OpenZeppelin Contracts"]:::ext
        E2["ds-test"]:::ext
        E3["forge-std"]:::ext
        E4["relay-context-contracts"]:::ext
    end

    %% Documentation
    subgraph "Documentation"
        DOC1["Logbook Docs"]:::doc
        DOC2["TheSpace Docs"]:::doc
        DOC3["Billboard Docs"]:::doc
        DOC4["Curation Docs"]:::doc
        DOC5["Snapper Docs"]:::doc
    end

    %% Connections from Development to Smart Contract Modules (Build & Test Pipeline)
    D1 -->|"build"| S1
    D1 -->|"build"| S2
    D1 -->|"build"| S3
    D1 -->|"build"| S4
    D1 -->|"build"| S5

    D2 -->|"configure"| S1
    D2 -->|"configure"| S2
    D2 -->|"configure"| S3
    D2 -->|"configure"| S4
    D2 -->|"configure"| S5

    D3 -->|"script execution"| S3
    D4 -->|"metadata extraction"| S1
    D5 -->|"testing"| S1
    D5 -->|"testing"| S2
    D5 -->|"testing"| S3
    D5 -->|"testing"| S4
    D5 -->|"testing"| S5

    %% Connections from Smart Contract Modules to Deployment & Network Environment
    %% Assume Logbook, TheSpace and Billboard are deployed on Polygon networks
    S1 -->|"deploys to"| N2
    S1 -->|"deploys to"| N3

    S2 -->|"deploys to"| N2
    S2 -->|"deploys to"| N3

    S3 -->|"deploys to"| N2
    S3 -->|"deploys to"| N3

    %% Curation and Snapper are deployed on Optimism networks
    S4 -->|"deploys to"| N4
    S4 -->|"deploys to"| N5

    S5 -->|"deploys to"| N4
    S5 -->|"deploys to"| N5

    %% Connections from Smart Contract Modules to External Libraries & Interfaces
    S1 ---|"uses"| E1
    S1 ---|"uses"| E2
    S1 ---|"uses"| E3
    S1 ---|"uses"| E4

    S2 ---|"uses"| E1
    S3 ---|"uses"| E1
    S4 ---|"uses"| E1
    S5 ---|"uses"| E1

    %% Connections from Smart Contract Modules to Documentation
    S1 -->|"documented in"| DOC1
    S2 -->|"documented in"| DOC2
    S3 -->|"documented in"| DOC3
    S4 -->|"documented in"| DOC4
    S5 -->|"documented in"| DOC5

    %% Click Events for Smart Contract Modules
    click S1 "https://github.com/thematters/contracts/tree/develop/src/Logbook"
    click S2 "https://github.com/thematters/contracts/tree/develop/src/TheSpace"
    click S3 "https://github.com/thematters/contracts/tree/develop/src/Billboard"
    click S4 "https://github.com/thematters/contracts/tree/develop/src/Curation"
    click S5 "https://github.com/thematters/contracts/tree/develop/src/Snapper"

    %% Click Events for Deployment & Network Environment Configurations
    click N1 "https://github.com/thematters/contracts/blob/develop/.env.local.example"
    click N2 "https://github.com/thematters/contracts/blob/develop/.env/polygon-mainnet.example"
    click N3 "https://github.com/thematters/contracts/blob/develop/.env/polygon-mumbai.example"
    click N4 "https://github.com/thematters/contracts/blob/develop/.env/op-mainnet.example"
    click N5 "https://github.com/thematters/contracts/blob/develop/.env/op-sepolia.example"

    %% Click Events for Development and Testing Infrastructure
    click D1 "https://github.com/thematters/contracts/tree/develop/Makefile"
    click D2 "https://github.com/thematters/contracts/blob/develop/foundry.toml"
    click D3 "https://github.com/thematters/contracts/tree/develop/scripts/billboard"
    click D4 "https://github.com/thematters/contracts/blob/develop/scripts/logbook-metadata.js"
    click D5 "https://github.com/thematters/contracts/tree/develop/src/test"

    %% Click Events for External Libraries & Interfaces
    click E1 "https://github.com/thematters/contracts/tree/develop/lib/openzeppelin-contracts"
    click E2 "https://github.com/thematters/contracts/tree/develop/lib/ds-test"
    click E3 "https://github.com/thematters/contracts/tree/develop/lib/forge-std"
    click E4 "https://github.com/thematters/contracts/tree/develop/lib/relay-context-contracts"

    %% Click Events for Documentation
    click DOC1 "https://github.com/thematters/contracts/tree/develop/docs/Logbook"
    click DOC2 "https://github.com/thematters/contracts/tree/develop/docs/TheSpace"
    click DOC3 "https://github.com/thematters/contracts/tree/develop/docs/Billboard"
    click DOC4 "https://github.com/thematters/contracts/tree/develop/docs/Curation"
    click DOC5 "https://github.com/thematters/contracts/tree/develop/docs/Snapper"

    %% Styles
    classDef dev fill:#f0f9ff,stroke:#036,stroke-width:2px;
    classDef contract fill:#e0ffe0,stroke:#080,stroke-width:2px;
    classDef env fill:#fff0f5,stroke:#c00,stroke-width:2px;
    classDef ext fill:#ffffe0,stroke:#aa0,stroke-width:2px;
    classDef doc fill:#f5f5dc,stroke:#888,stroke-width:2px;
```
