# storyprotocol/protocol-core-v1 architecture

> Architecture diagram of the GitHub repository storyprotocol/protocol-core-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/storyprotocol/protocol-core-v1
- Repository: https://github.com/storyprotocol/protocol-core-v1

## Overview

##### Main Components

a) Core Layer:
- IPAsset Registry (fundamental storage)
- IPAccount Registry (ERC-6551 based accounts)
- Module Registry (functionality registration)
- License Registry (IP licensing management)

b) Access Control Layer:
- Access Controller
- Permission Table
- Permission Engine

c) Module Layer (organize in distinct sections):
- Dispute Modules
- Grouping Modules
- Licensing Modules
- Metadata Modules
- Royalty Modules (including LAP and LRP policies)

d) External Integrations:
- ERC-721/NFT Contracts
- UMA Protocol (for dispute resolution)
- Client Applications

**[Application Layer (External dApps)]**
- ↕
**[Core Protocol Layer]**
- Access Control Layer
- Registry Layer
- Module Layer
- ↕
**[Blockchain Layer (Ethereum)]**

##### Connection Types

- Double lines: Inheritance relationships

##### Key Relationships to Highlight

a) IPAccount Interactions:
- How IPAccounts interact with modules through execute() and executeWithSig()
- Demonstrate the relationship between NFTs and their IPAccounts

b) Module Dependencies:
- How modules interact with registries
- Permission flows through the Access Controller

c) Registry Relationships:
- Connections between different registries
- How they maintain global state

##### Implementation Details

Create subsections for complex components:
- Detailed view of the Permission System
- Module interaction patterns
- Registry data flow
- Licensing and royalty mechanics

##### Technical Notes

- Use of ERC-7201 for storage patterns
- Upgrade proxy pattern implementation
- Where external calls are made
- Critical security boundaries

Remember to emphasize the protocol's unique aspects:
- IP-centric architecture
- Modular design
- Permission-based access control
- Upgradeable components

This will provide a comprehensive view of the system while maintaining readability and usefulness for technical discussions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Layer"]
        direction TB
        Client["Client Applications"]
        NFT["ERC-721/NFT Contracts"]
        UMA["UMA Protocol"]:::external
    end

    subgraph Core["Core Protocol Layer"]
        direction TB
        subgraph Access["Access Control Layer"]
            direction TB
            AC["Access Controller"]:::access
            PT["Permission Table"]:::access
            PE["Permission Engine"]:::access
        end

        subgraph Registries["Registry Layer"]
            direction TB
            IPAsset["IPAsset Registry"]:::registry
            IPAccount["IPAccount Registry"]:::registry
            ModuleReg["Module Registry"]:::registry
            LicenseReg["License Registry"]:::registry
        end

        subgraph Modules["Module Layer"]
            direction TB
            subgraph DisputeMods["Dispute Modules"]
                DM["Dispute Module"]:::module
            end

            subgraph GroupMods["Grouping Modules"]
                GM["Grouping Module"]:::module
            end

            subgraph LicenseMods["Licensing Modules"]
                LM["Licensing Module"]:::module
                LPH["License Parameter Helpers"]:::module
            end

            subgraph MetadataMods["Metadata Modules"]
                MM["Metadata Module"]:::module
            end

            subgraph RoyaltyMods["Royalty Modules"]
                RM["Royalty Module"]:::module
                subgraph Policies["Royalty Policies"]
                    LAP["LAP Policy"]:::policy
                    LRP["LRP Policy"]:::policy
                end
            end
        end

        subgraph Interfaces["Interface Layer"]
            ModuleInt["Module Interfaces"]:::interface
            RegistryInt["Registry Interfaces"]:::interface
            AccessInt["Access Control Interfaces"]:::interface
        end
    end

    %% Relationships
    Client --> Core
    NFT --> IPAccount
    UMA --> DM

    %% Access Control Relationships
    AC --> PT
    AC --> PE
    Modules --> AC

    %% Registry Relationships
    IPAsset <--> IPAccount
    IPAccount <--> ModuleReg
    ModuleReg <--> LicenseReg

    %% Module Relationships
    DM --> Registries
    GM --> Registries
    LM --> Registries
    MM --> Registries
    RM --> Registries

    %% Policy Relationships
    LAP --> RM
    LRP --> RM

    %% Interface Relationships
    ModuleInt --> Modules
    RegistryInt --> Registries
    AccessInt --> Access

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333
    classDef access fill:#ffeb3b,stroke:#333
    classDef registry fill:#9c27b0,stroke:#333,color:white
    classDef module fill:#4caf50,stroke:#333
    classDef policy fill:#81c784,stroke:#333
    classDef interface fill:#90caf9,stroke:#333

    %% Click Events
    click IPAsset "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/registries"
    click IPAccount "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/registries"
    click ModuleReg "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/registries"
    click LicenseReg "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/registries"
    click AC "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/access"
    click DM "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/dispute"
    click GM "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/grouping"
    click LM "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/licensing"
    click MM "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/metadata"
    click RM "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/royalty"
    click LAP "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/royalty/policies/LAP"
    click LRP "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/royalty/policies/LRP"
    click UMA "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/dispute/policies/UMA"
    click ModuleInt "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/interfaces/modules"
    click RegistryInt "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/interfaces/registries"
    click AccessInt "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/interfaces/access"
    click Policies "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/royalty/policies"
    click LPH "https://github.com/storyprotocol/protocol-core-v1/tree/main/contracts/modules/licensing/parameter-helpers"
```
