# collarnetworks/protocol-core architecture

> Architecture diagram of the GitHub repository collarnetworks/protocol-core, 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/collarnetworks/protocol-core
- Repository: https://github.com/collarnetworks/protocol-core

## Overview

##### Project Type and Purpose
- Type: Smart-contract‐only blockchain protocol (no UI layer).
- Purpose: A lending protocol using DEX swaps and option-like payoffs to offer liquidation-free, high-LTV borrowing.

##### Main Components
a. Core Contracts (src/base & src/interfaces)
– Core lending logic lives here.
– Interfaces define the protocol’s external API.
b. External Dependencies (lib/)
– OpenZeppelin (ERC20, AccessControl, etc.)
– Uniswap V3 core & periphery (swap router, pools).
– Custom swap-router contracts.
c. Deployment & Utility Scripts (script/)
– script/deploy: deployments to various chains.
– script/utils: batch Etherscan verification, diffs, explorer links.
– script/artifacts: stores previous deployments.
d. Testing Suite (test/)
– Unit tests (test/unit) for individual contracts.
– Integration tests (test/integration) simulating full protocol flows.
– Shared test utilities (test/utils).
e. Developer Tooling & Configuration
– Foundry (forge) setup (foundry.toml, remappings.txt).
– CI workflows (GitHub Actions in .github/workflows).
– Documentation (devdocs/, script/readme.md).
– Audit reports (audits/).

##### Relationships and Data Flow
- Developer → Foundry (forge) → Compiles core contracts + NatSpec docs.
- Deployment Scripts → RPC node → Deploy contracts on chain → Emit artifacts.
- Core Contracts ↔ External Dependencies (Uniswap v3, ERC20 tokens).
- Tests (unit & integration) → Local Hardhat/Anvil fork or testnet → Interact with deployed contracts & mocks.
- CI → Runs forge tests + script checks + docgen on every PR.

##### Architectural Patterns & Design Principles
- Modular Design: each functional domain (lending logic, swap router adaptor) is isolated in its own contract/module.
- Interface-Driven: clear contract interfaces for upgradeability or future extension.
- Dependency Injection via remappings: external protocol addresses & libraries injected at compile time.
- Continuous Verification: automated Etherscan re-verification scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actors
    Dev["Developer"]:::config
    CI["CI (GitHub Actions)"]:::config

    %% Subgraphs and modules
    subgraph "Contracts" 
        direction TB
        CoreContracts["Core Contracts (Lending Logic)"]:::contracts
        CoreInterfaces["Core Interfaces (Protocol API)"]:::contracts
    end

    subgraph "Libraries / External"
        direction TB
        OZ["OpenZeppelin"]:::external
        V3Core["Uniswap V3 Core"]:::external
        V3Peri["Uniswap V3 Periphery"]:::external
        SwapRouter["Custom Swap-Router"]:::external
    end

    subgraph "Scripts & Tools"
        direction TB
        DeployScripts["Deployment Scripts"]:::scripts
        Artifacts["Deployment Artifacts"]:::scripts
        UtilsScripts["Utility Scripts"]:::scripts
        FoundryConfig["foundry.toml"]:::config
        Remappings["remappings.txt"]:::config
        DevDocs["Developer Docs"]:::scripts
        Readme["script/readme.md"]:::scripts
        Audits["Audit Reports"]:::scripts
    end

    subgraph "Tests & CI"
        direction TB
        UnitTests(("Unit Tests")):::tests
        IntFull(("Integration Tests (Full Protocol)")):::tests
        IntUtils(("Integration Test Utilities")):::tests
        SharedUtils(("Shared Test Utilities")):::tests
        Workflows["CI Workflows"]:::config
    end

    %% Infrastructure
    RPC["RPC Node"]:::external
    Chain["Blockchain"]:::external
    Foundry["Foundry (forge)"]:::config

    %% Relationships
    Dev -->|uses| Foundry
    Foundry -->|compiles| CoreContracts
    Foundry -->|compiles| CoreInterfaces

    CoreContracts <-->|imports| OZ
    CoreContracts <-->|imports| V3Core
    CoreContracts <-->|imports| V3Peri
    CoreContracts <-->|imports| SwapRouter
    CoreInterfaces <-->|defines API| CoreContracts

    DeployScripts -->|calls RPC| RPC
    RPC -->|deploy| Chain
    DeployScripts -->|produces| Artifacts
    UtilsScripts -->|verifies & diffs| Chain

    UnitTests -->|fork/local| RPC
    IntFull -->|fork/local| RPC
    UnitTests -->|tests| CoreContracts
    IntFull -->|tests| CoreContracts
    IntUtils -->|assists| IntFull
    SharedUtils -->|shared code| UnitTests
    SharedUtils -->|shared code| IntFull

    CI -->|runs| UnitTests
    CI -->|runs| IntFull
    CI -->|checks| UtilsScripts
    CI -->|generates docs| DevDocs

    Dev -->|reads| DevDocs
    Dev -->|reviews| Audits

    %% Click Events
    click CoreContracts "https://github.com/collarnetworks/protocol-core/tree/develop/src/base"
    click CoreInterfaces "https://github.com/collarnetworks/protocol-core/tree/develop/src/interfaces"
    click OZ "https://github.com/collarnetworks/protocol-core/tree/develop/lib/openzeppelin-contracts"
    click V3Core "https://github.com/collarnetworks/protocol-core/tree/develop/lib/v3-core"
    click V3Peri "https://github.com/collarnetworks/protocol-core/tree/develop/lib/v3-periphery"
    click SwapRouter "https://github.com/collarnetworks/protocol-core/tree/develop/lib/swap-router-contracts"
    click DeployScripts "https://github.com/collarnetworks/protocol-core/tree/develop/script/deploy"
    click Artifacts "https://github.com/collarnetworks/protocol-core/tree/develop/script/artifacts"
    click UtilsScripts "https://github.com/collarnetworks/protocol-core/tree/develop/script/utils"
    click UnitTests "https://github.com/collarnetworks/protocol-core/tree/develop/test/unit"
    click IntFull "https://github.com/collarnetworks/protocol-core/tree/develop/test/integration/full-protocol"
    click IntUtils "https://github.com/collarnetworks/protocol-core/tree/develop/test/integration/utils"
    click SharedUtils "https://github.com/collarnetworks/protocol-core/tree/develop/test/utils"
    click FoundryConfig "https://github.com/collarnetworks/protocol-core/blob/develop/foundry.toml"
    click Remappings "https://github.com/collarnetworks/protocol-core/blob/develop/remappings.txt"
    click Workflows "https://github.com/collarnetworks/protocol-core/blob/develop/.github/workflows/tests.yml"
    click Workflows "https://github.com/collarnetworks/protocol-core/blob/develop/.github/workflows/discord-webhook.yml"
    click DevDocs "https://github.com/collarnetworks/protocol-core/tree/develop/devdocs"
    click Readme "https://github.com/collarnetworks/protocol-core/blob/develop/script/readme.md"
    click Audits "https://github.com/collarnetworks/protocol-core/tree/develop/audits"

    %% Styles
    classDef contracts fill:#cce5ff,stroke:#004085;
    classDef external fill:#d4edda,stroke:#155724;
    classDef scripts fill:#fff3cd,stroke:#856404;
    classDef tests fill:#f8d7da,stroke:#721c24;
    classDef config fill:#e2e3e5,stroke:#6c757d;
```
