# metacontract/mc architecture

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

- Interactive diagram: https://gitdiagram.com/metacontract/mc
- Repository: https://github.com/metacontract/mc

## Overview

##### Project Type and Purpose
- This is an open-source, Foundry-based smart-contract framework (“Meta Contract”) that implements the UCS (ERC-7546) upgradeable-clone architecture.
- It provides two core libraries—`devkit` (for registry, system messaging, utilities, testing scaffolds) and `std` (standard functions, interfaces, storage)—plus a full documentation site and CI/CD pipelines.

##### Top-Level Architectural Components
A. Source Code
- src/devkit (core modules: registry, system, test stubs, types, utils)
- src/std (standard functions, internal/protected layers, interfaces, storage)
- lib (Git submodules: forge-std, ucs-contracts)
B. Build & Test
- Foundry (`forge`): compile, test, deploy
- deployments/*.json: output artifacts
- script/ (Solidity or JS scripts to drive tasks)
- test/ (unit & integration tests for devkit and std)
C. Documentation Site
- site/ (Docusaurus config, docs/ content, React pages, static assets)
- site/script/ (tools to generate and integrate Forge docs into site)
D. CI/CD & Release Automation
- .github/workflows (ci.yml, review_workflow.yml)
- GitHub issue & PR templates
- npm (`package.json`) and Foundry (`foundry.toml`, `remappings.txt`) for dependency and build management

##### Relationships and Data Flows
- Developer edits `src/…` → `forge build` → compiled JSON/artifacts → optionally deployed on-chain
- `forge test` runs tests in test/ using mock/dummy contexts from devkit
- site/script extracts on-chain API docs from compiled artifacts → merges into site/docs → `npm run build` → static site
- GitHub Actions triggers on push/PR → runs `forge test`, lints code, builds docs, publishes to GH Pages or package registry

##### Key Architectural Patterns & Principles
- Modularity: clear separation between devkit core logic and std library
- Upgradeable-clone (UCS) pattern: clone factories, proxy logic, registry management
- Layered design: internal vs protected vs public interfaces in std functions
- Documentation-as-code: automated generation & integration of API docs
- Continuous integration: automated testing, docs build, and release workflows

##### Essential Details to Capture
- Names of key modules (e.g., devkit.registry, std.functions.protected)
- Data/artifact formats (JSON ABI, bytecode, markdown docs)
- Flow of test mocks and dummy contexts from devkit into tests
- Integration points (site/script ↔ forge docs, CI/CD ↔ package publish)
- Upgradeable-clone factory interaction with registry and on-chain proxies

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Source Code"
        subgraph "DevKit Core Modules" 
            DK_registry["registry"]:::code
            DK_context["registry/context"]:::code
            DK_system["system"]:::code
            DK_message["system/message"]:::code
        end
        subgraph "DevKit Testing & Utilities"
            DK_test["test"]:::code
            DK_dummy["test/dummy"]:::code
            DK_mocks["test/mocks"]:::code
            DK_types["types"]:::code
            DK_utils["utils"]:::code
            DK_global["utils/global"]:::code
            DK_mapping["utils/mapping"]:::code
        end
        subgraph "Std Library"
            STD_functions["functions"]:::code
            STD_internal["functions/internal"]:::code
            STD_protected["functions/protected"]:::code
            STD_protection["functions/protected/protection"]:::code
            STD_interfaces["interfaces"]:::code
            STD_storage["storage"]:::code
        end
        subgraph "External Submodules"
            LIB_forge["forge-std"]:::code
            LIB_ucs["ucs-contracts"]:::code
        end
    end

    subgraph "Build & Test"
        Forge["Foundry (forge)"]:::pipeline
        Deploys["deployments/111.json"]:::pipeline
        Scripts["script/*"]:::pipeline
        subgraph "Test Suites"
            Test_devkit["test/devkit"]:::pipeline
            Test_std["test/std"]:::pipeline
            Test_std_funcs["test/std/functions"]:::pipeline
            Test_std_internal["test/std/functions/internal"]:::pipeline
            Test_std_protected["test/std/functions/protected"]:::pipeline
            Test_std_protection["test/std/functions/protected/protection"]:::pipeline
        end
    end

    subgraph "Documentation"
        SiteContent["site/docs & config"]:::pipeline
        Site_config["site/docusaurus.config.ts"]:::pipeline
        Site_sidebars["site/sidebars.ts"]:::pipeline
        Site_pkg["site/package.json"]:::pipeline
        Site_readme["site/README.md"]:::pipeline
        subgraph "Doc Generation Scripts"
            Doc_config["site/script/config.ts"]:::pipeline
            Doc_gen_temp["site/script/generate_temp_soldocs.sh"]:::pipeline
            Doc_integrate["site/script/integrate_soldocs.ts"]:::pipeline
            Doc_remove["site/script/remove_temp_soldocs.sh"]:::pipeline
            soldocs["site/script/soldocs"]:::pipeline
        end
    end

    subgraph "CI/CD & Release Automation"
        CI[".github/workflows"]:::pipeline
        Issue_PR[".github/ISSUE_TEMPLATE & PULL_REQUEST_TEMPLATE"]:::pipeline
        PM["package.json & mc.toml & .env.sample"]:::pipeline
    end

    subgraph "External Services"
        Eth["Ethereum Network"]:::external
        NpmReg["npm Registry"]:::external
        GH["GitHub"]:::external
    end

    %% Connections
    DK_registry & DK_context & DK_system & DK_message & DK_test & DK_dummy & DK_mocks & DK_types & DK_utils & DK_global & DK_mapping & STD_functions & STD_internal & STD_protected & STD_protection & STD_interfaces & STD_storage & LIB_forge & LIB_ucs --> Forge
    Forge -->|compiles| Deploys -->|deploys to| Eth
    Forge -->|runs tests| Test_devkit & Test_std & Test_std_funcs & Test_std_internal & Test_std_protected & Test_std_protection
    Test_devkit -->|uses| DK_dummy & DK_mocks
    Deploys -->|artifacts| Doc_gen_temp --> Doc_integrate --> SiteContent
    SiteContent -->|build site| Site_pkg
    Site_pkg --> GH
    GH -->|push/PR triggers| CI
    CI -->|runs forge test| Forge
    CI -->|build docs| SiteContent
    CI -->|publish| NpmReg
    CI -->|publish| GH

    %% Click Events for component mappings
    click DK_registry "https://github.com/metacontract/mc/tree/main/src/devkit/registry"
    click DK_context "https://github.com/metacontract/mc/tree/main/src/devkit/registry/context"
    click DK_system "https://github.com/metacontract/mc/tree/main/src/devkit/system"
    click DK_message "https://github.com/metacontract/mc/tree/main/src/devkit/system/message"
    click DK_test "https://github.com/metacontract/mc/tree/main/src/devkit/test"
    click DK_dummy "https://github.com/metacontract/mc/tree/main/src/devkit/test/dummy"
    click DK_mocks "https://github.com/metacontract/mc/tree/main/src/devkit/test/mocks"
    click DK_types "https://github.com/metacontract/mc/tree/main/src/devkit/types"
    click DK_utils "https://github.com/metacontract/mc/tree/main/src/devkit/utils"
    click DK_global "https://github.com/metacontract/mc/tree/main/src/devkit/utils/global"
    click DK_mapping "https://github.com/metacontract/mc/tree/main/src/devkit/utils/mapping"
    click STD_functions "https://github.com/metacontract/mc/tree/main/src/std/functions"
    click STD_internal "https://github.com/metacontract/mc/tree/main/src/std/functions/internal"
    click STD_protected "https://github.com/metacontract/mc/tree/main/src/std/functions/protected"
    click STD_protection "https://github.com/metacontract/mc/tree/main/src/std/functions/protected/protection"
    click STD_interfaces "https://github.com/metacontract/mc/tree/main/src/std/interfaces"
    click STD_storage "https://github.com/metacontract/mc/tree/main/src/std/storage"
    click LIB_forge "https://github.com/metacontract/mc/tree/main/lib/forge-std"
    click LIB_ucs "https://github.com/metacontract/mc/tree/main/lib/ucs-contracts"
    click Deploys "https://github.com/metacontract/mc/blob/main/deployments/111.json"
    click Scripts "https://github.com/metacontract/mc/tree/main/script/"
    click Test_devkit "https://github.com/metacontract/mc/tree/main/test/devkit"
    click Test_std "https://github.com/metacontract/mc/tree/main/test/std"
    click Test_std_funcs "https://github.com/metacontract/mc/tree/main/test/std/functions"
    click Test_std_internal "https://github.com/metacontract/mc/tree/main/test/std/functions/internal"
    click Test_std_protected "https://github.com/metacontract/mc/tree/main/test/std/functions/protected"
    click Test_std_protection "https://github.com/metacontract/mc/tree/main/test/std/functions/protected/protection"
    click SiteContent "https://github.com/metacontract/mc/tree/main/site/docs"
    click Site_config "https://github.com/metacontract/mc/blob/main/site/docusaurus.config.ts"
    click Site_sidebars "https://github.com/metacontract/mc/blob/main/site/sidebars.ts"
    click Site_pkg "https://github.com/metacontract/mc/blob/main/site/package.json"
    click Site_readme "https://github.com/metacontract/mc/blob/main/site/README.md"
    click Doc_config "https://github.com/metacontract/mc/blob/main/site/script/config.ts"
    click Doc_gen_temp "https://github.com/metacontract/mc/blob/main/site/script/generate_temp_soldocs.sh"
    click Doc_integrate "https://github.com/metacontract/mc/blob/main/site/script/integrate_soldocs.ts"
    click Doc_remove "https://github.com/metacontract/mc/blob/main/site/script/remove_temp_soldocs.sh"
    click soldocs "https://github.com/metacontract/mc/tree/main/site/script/soldocs"
    click CI "https://github.com/metacontract/mc/blob/main/.github/workflows/ci.yml"
    click Issue_PR "https://github.com/metacontract/mc/tree/main/.github/ISSUE_TEMPLATE"
    click PM "https://github.com/metacontract/mc/blob/main/package.json"

    classDef code fill:#D0E6FF,stroke:#085FC7,color:#000
    classDef pipeline fill:#E6F4EA,stroke:#28A745,color:#000
    classDef external fill:#F0F0F0,stroke:#636363,color:#000
```
