# usepicnic/picnic-contracts architecture

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

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

## Overview

##### Project type and purpose
- This repo (“defibasket-contracts”) is a Solidity-based smart-contract codebase for DeFi Basket, a blockchain portfolio-sharing platform. It provides on-chain components (core contracts + bridge adapters) plus off-chain tooling (Hardhat, scripts, tests, CI/CD).

##### File structure
- Top-level directories & files:
- contracts/ – Solidity code subdivided into:
– bridges/ – one adapter per external DeFi protocol (Aave, Compound, Curve, Uniswap, etc.)
– interfaces/ – interface definitions for external protocols
– libraries/ – shared helper libraries
– tests/ – contract unit tests
- scripts/ – TypeScript scripts for deployment, utility actions via Hardhat
- test/ – end-to-end and bridge-specific tests
- hardhat.config.ts, tsconfig.json, package.json – project configuration
- .github/workflows – CI pipelines (compile, lint, slither, test)
- audits/ – third-party security reports

##### Extract additional insights from the README
- Built with Hardhat + Solidity v0.8.6
- Contracts expose a developer-API (see documentation)
- A modular “bridge” pattern: core contract calls out to protocol-specific adapters

##### Main components & their interactions
a. On-chain components:
- CoreController (DeFiBasket central logic & registry)
- BridgeRegistry (maps strategy IDs to bridge contracts)
- Bridge Adapters (one per external protocol)
- Shared Libraries (math, asset helpers)
- Interfaces (contract ABIs for Aave, Compound, etc.)
b. Off-chain components:
- Hardhat environment (compiler, network simulation)
- Deployment & utility scripts (scripts/*.ts)
- Test harness (test/*, contracts/tests/)
- CI/CD workflows (.github/workflows)
c. External on-chain services:
- Aave, Compound, Curve, Uniswap, etc. – each bridge invokes their on-chain contracts

##### Architectural patterns & design principles
- Adapter pattern: one Bridge contract per external protocol, unified by a common interface
- Registry/factory: dynamic lookup of supported bridges in the core contract
- Separation of concerns: core logic vs. protocol-specific logic vs. libraries
- Immutable deployment scripts & extensive test coverage for safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Off-chain Tooling & CI Layer
    subgraph "Off-chain Tooling & CI"
        direction TB
        OFF_Hardhat["Hardhat (hardhat.config.ts)"]:::offchain
        OFF_TSConfig["TypeScript Config (tsconfig.json)"]:::offchain
        OFF_Scripts["Deployment & Utility Scripts (scripts/)"]:::offchain
        OFF_UnitTests["Contract Unit Tests (contracts/tests/)"]:::offchain
        OFF_E2ETests["E2E & Bridge-Specific Tests (test/)"]:::offchain
        OFF_CI["CI/CD Workflows (.github/workflows/)"]:::offchain
    end

    %% On-chain Contracts Layer
    subgraph "On-chain Contracts"
        direction TB
        OC_CoreController["CoreController.sol"]:::onchain
        OC_BridgeRegistry["BridgeRegistry.sol"]:::onchain
        OC_Libraries["Shared Libraries (contracts/libraries/)"]:::onchain
        OC_Interfaces["External Protocol Interfaces (contracts/interfaces/)"]:::onchain
        subgraph "Bridge Adapters" 
            direction TB
            OC_BridgeAave["AaveV2 Adapter"]:::onchain
            OC_BridgeCompound["Compound Adapter"]:::onchain
            OC_BridgeCurve["Curve Adapter"]:::onchain
            OC_BridgeUniswap["UniswapV3 Adapter"]:::onchain
            OC_BridgeOthers["Other Protocol Adapters"]:::onchain
            OC_BridgeInterfaces["Bridge Adapter Interfaces (contracts/bridges/interfaces/)"]:::onchain
        end
    end

    %% External Protocols Layer
    subgraph "External Protocols"
        direction TB
        EXT_Aave["Aave Protocol"]:::external
        EXT_Compound["Compound Protocol"]:::external
        EXT_Curve["Curve Protocol"]:::external
        EXT_Uniswap["Uniswap Protocol"]:::external
        EXT_Others["Other DeFi Protocols"]:::external
    end

    %% Users
    USER["User Wallet/DApp"]:::external

    %% Data Flows
    USER -->|"transactions"| OC_CoreController
    OFF_Scripts -->|"deploy()"| OC_CoreController
    OFF_Scripts -->|"deploy()"| OC_BridgeRegistry
    OC_CoreController -->|"lookupBridge()"| OC_BridgeRegistry
    OC_BridgeRegistry -->|"getAdapter()"| OC_BridgeAave
    OC_BridgeRegistry -->|"getAdapter()"| OC_BridgeCompound
    OC_BridgeRegistry -->|"getAdapter()"| OC_BridgeCurve
    OC_BridgeRegistry -->|"getAdapter()"| OC_BridgeUniswap
    OC_BridgeRegistry -->|"getAdapter()"| OC_BridgeOthers
    OC_BridgeAave -->|"deposit()/withdraw()"| EXT_Aave
    OC_BridgeCompound -->|"mint()/redeem()"| EXT_Compound
    OC_BridgeCurve -->|"swap()"| EXT_Curve
    OC_BridgeUniswap -->|"swap()/addLiquidity()"| EXT_Uniswap
    OC_BridgeOthers -->|"adapterCalls()"| EXT_Others

    %% Click Events
    click OC_CoreController "https://github.com/usepicnic/picnic-contracts/blob/dev/contracts/CoreController.sol"
    click OC_BridgeRegistry "https://github.com/usepicnic/picnic-contracts/blob/dev/contracts/BridgeRegistry.sol"
    click OC_BridgeAave "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/AaveV2"
    click OC_BridgeCompound "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/Compound"
    click OC_BridgeCurve "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/Curve"
    click OC_BridgeUniswap "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/UniswapV3"
    click OC_BridgeOthers "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/"
    click OC_BridgeInterfaces "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/bridges/interfaces"
    click OC_Interfaces "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/interfaces"
    click OC_Libraries "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/libraries"
    click OFF_UnitTests "https://github.com/usepicnic/picnic-contracts/tree/dev/contracts/tests"
    click OFF_E2ETests "https://github.com/usepicnic/picnic-contracts/tree/dev/test/"
    click OFF_Scripts "https://github.com/usepicnic/picnic-contracts/tree/dev/scripts/"
    click OFF_Hardhat "https://github.com/usepicnic/picnic-contracts/blob/dev/hardhat.config.ts"
    click OFF_TSConfig "https://github.com/usepicnic/picnic-contracts/blob/dev/tsconfig.json"
    click OFF_CI "https://github.com/usepicnic/picnic-contracts/tree/dev/.github/workflows/"

    %% Styles
    classDef offchain fill:#b3e6b3,stroke:#2d662d,color:#000;
    classDef onchain fill:#cce0ff,stroke:#264d73,color:#000;
    classDef external fill:#e0e0e0,stroke:#707070,color:#000;

    %% Legend
    subgraph "Legend"
        direction TB
        L1["Green: Off-chain Tools & CI"]:::offchain
        L2["Blue: On-chain Contracts"]:::onchain
        L3["Gray: External Protocols"]:::external
        NoteTech["Note: Built with Hardhat + Solidity v0.8.6"]:::external
    end
```
