# pcaversaccio/snekmate architecture

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

- Interactive diagram: https://gitdiagram.com/pcaversaccio/snekmate
- Repository: https://github.com/pcaversaccio/snekmate

## Overview

##### Project Type & Purpose
- Type: Open-source smart-contract building-blocks library in Vyper.
- Purpose: Offer modular, reusable, hyper-optimised, and secure contracts (auth, tokens, governance, extensions, utils) plus tests and mocks, published via PyPI, npm, and Foundry.

##### Main Components
- Core Modules (src/snekmate/…):
– auth (ownable, access_control)
– tokens (erc20, erc721, erc1155)
– extensions (erc2981, erc4626)
– governance (timelock_controller)
– utils (base64, ecdsa, merkle, multicall, etc.)
- Interfaces: each module’s interface definitions (…/interfaces/*.vyi)
- Mocks: reference implementations under each category (…/mocks/*.vy)
- Tests: Foundry (unit/property/invariant), Echidna, Halmos test harnesses (test/…)
- Build & Packaging:
– scripts/compile.py & VyperDeployer.sol
– packaging configs: pyproject.toml, package.json, lib/ submodules
– CI workflows (.github/workflows/*.yml)
- Audits & Docs: audits/ and README.md

##### Relationships & Data Flows
- Package Managers → Codebase: show distribution paths (PyPI, npm, Foundry).
- CI/CD → Codebase: pipelines trigger tests and packaging.

##### Architectural Patterns & Principles
- Composition-over-inheritance: modules are Vyper modules imported via `uses`/`initialize`.
- Modular separation by domain (auth, tokens, governance, utils).
- Tests co-located with code; mocks illustrate integration.
- Multi-language packaging ensures broad adop­tion.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumers
    subgraph "External Consumers"
        direction TB
        PyPI(["PyPI"]):::external
        npm(["npm"]):::external
        Foundry(["Foundry"]):::external
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        subgraph "1 Auth" 
            direction TB
            AuthCore(["Auth Core Modules"]):::auth
            AuthInterfaces(["Auth Interfaces"]):::iface
            AuthMocks(["Auth Mocks"]):::mock
        end
        subgraph "2 Tokens"
            direction TB
            TokensCore(["Tokens Core Modules"]):::tokens
            TokensInterfaces(["Tokens Interfaces"]):::iface
            TokensMocks(["Tokens Mocks"]):::mock
        end
        subgraph "3 Extensions"
            direction TB
            ExtCore(["Extensions Core Modules"]):::ext
            ExtInterfaces(["Extensions Interfaces"]):::iface
            ExtMocks(["Extensions Mocks"]):::mock
        end
        subgraph "4 Governance"
            direction TB
            GovCore(["Governance Core Module"]):::gov
            GovMocks(["Governance Mocks"]):::mock
        end
        subgraph "5 Utils"
            direction TB
            UtilsCore(["Utils Core Modules"]):::utils
            UtilsInterfaces(["Utils Interfaces"]):::iface
            UtilsMocks(["Utils Mocks"]):::mock
        end
    end

    %% Tests
    subgraph "Tests & Harnesses"
        direction TB
        FoundryTests(["Foundry Tests"]):::test
        InterfaceTests(["Interface Tests"]):::test
        MocksTests(["Mocks Tests"]):::test
        Echidna(["Echidna Harness"]):::test
        Halmos(["Halmos Harness"]):::test
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        CI(["CI/CD Workflows"]):::ci
        Packaging(["Build & Packaging"]):::pkg
        AuditsDocs(["Audits & Documentation"]):::doc
    end

    %% Relationships
    AuthCore -->|"implements"| AuthInterfaces
    AuthCore -->|"imports"| AuthMocks
    TokensCore -->|"implements"| TokensInterfaces
    TokensCore -->|"imports"| TokensMocks
    ExtCore -->|"implements"| ExtInterfaces
    ExtCore -->|"imports"| ExtMocks
    GovCore -->|"imports"| GovMocks
    UtilsCore -->|"implements"| UtilsInterfaces
    UtilsCore -->|"imports"| UtilsMocks

    FoundryTests -->|"tests"| AuthCore
    FoundryTests -->|"tests"| TokensCore
    FoundryTests -->|"tests"| ExtCore
    FoundryTests -->|"tests"| GovCore
    FoundryTests -->|"tests"| UtilsCore

    InterfaceTests -->|"tests"| AuthInterfaces
    InterfaceTests -->|"tests"| TokensInterfaces
    InterfaceTests -->|"tests"| ExtInterfaces
    InterfaceTests -->|"tests"| UtilsInterfaces

    MocksTests -->|"tests"| AuthMocks
    MocksTests -->|"tests"| TokensMocks
    MocksTests -->|"tests"| ExtMocks
    MocksTests -->|"tests"| GovMocks
    MocksTests -->|"tests"| UtilsMocks

    Echidna -->|"harness"| TokensCore
    Halmos -->|"harness"| UtilsCore

    PyPI -->|"published to"| Packaging
    npm -->|"published to"| Packaging
    Foundry -->|"published to"| Packaging

    CI -->|"triggers"| FoundryTests
    CI -->|"triggers"| Packaging

    Packaging -->|"configs"| CI

    AuditsDocs -.-> Packaging

    %% Click Events
    click AuthCore "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/auth/"
    click AuthInterfaces "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/auth/interfaces/"
    click AuthMocks "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/auth/mocks/"
    click TokensCore "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/tokens/"
    click TokensInterfaces "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/tokens/interfaces/"
    click TokensMocks "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/tokens/mocks/"
    click ExtCore "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/extensions/"
    click ExtInterfaces "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/extensions/interfaces/"
    click ExtMocks "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/extensions/mocks/"
    click GovCore "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/governance/"
    click GovMocks "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/governance/mocks/"
    click UtilsCore "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/utils/"
    click UtilsInterfaces "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/utils/interfaces/"
    click UtilsMocks "https://github.com/pcaversaccio/snekmate/tree/main/src/snekmate/utils/mocks/"
    click CI "https://github.com/pcaversaccio/snekmate/tree/main/.github/workflows/"
    click Packaging "https://github.com/pcaversaccio/snekmate/blob/main/pyproject.toml"
    click AuditsDocs "https://github.com/pcaversaccio/snekmate/tree/main/audits/"

    %% Styles
    classDef auth fill:#f9c2ff,stroke:#d07cd7
    classDef tokens fill:#c2f9ff,stroke:#7cd0d0
    classDef ext fill:#e2f9c2,stroke:#8fd07c
    classDef gov fill:#f9e2c2,stroke:#d07c3f
    classDef utils fill:#f9c2e2,stroke:#d07c7f
    classDef iface fill:#eeeeee,stroke:#cccccc,stroke-dasharray: 5 5
    classDef mock fill:none,stroke:#999999,stroke-dasharray: 2 2
    classDef test fill:#fff4b2,stroke:#e0c040
    classDef ci fill:#c2d8f9,stroke:#3f6fd0
    classDef pkg fill:#d8c2f9,stroke:#6d3fd0
    classDef doc fill:#f2f2f2,stroke:#999999,stroke-dasharray: 3 3
    classDef external fill:#d0d0d0,stroke:#888888,stroke-dasharray: 3 3
```
