# bubble-finance/bubble-v1-protocol architecture

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

- Interactive diagram: https://gitdiagram.com/bubble-finance/bubble-v1-protocol
- Repository: https://github.com/bubble-finance/bubble-v1-protocol

## Overview

##### Project Type and Purpose
- This project is a smart contract-based decentralized exchange (DEX) platform built on Monad. It is focused on providing a gamified, ecosystem-driven liquidity hub and includes features such as MEV shield, gas sponsored swaps, raffles, launchpads, and farms.
- The README confirms that the project uses Solidity for its smart contracts, Foundry for development and testing, and pnpm for package management, with an emphasis on modularity in its smart contract code.

##### File Structure
- Top-Level Directories:
- src: Contains the core source code for the protocol. Subdirectories include:
- campaigns: Likely modules handling promotional or community-driven campaigns.
- core: Represents the core logic and functionalities of the DEX.
- governance: Contains smart contracts for protocol governance.
- interfaces: Holds contract interfaces for standardized interactions.
- library: Utility contracts or shared internal libraries.
- raffle: Contains the logic for the raffle feature.
- router: Manages routing for transactions or liquidity paths.
- lib: Third-party libraries such as OpenZeppelin Contracts, Forge-std, and Solmate indicating reusable modules, security utilities, and helper contracts.
- script: Deployment or utility scripts to handle contract deployment and operations.
- test: Contains unit and integration tests structured alongside helper functions and test notes.
- Other Files:
- foundry.toml, package.json, pnpm-lock.yaml, and remappings.txt are configuration and dependency management files.
- The presence of Makefile and shell scripts indicates automation in building and testing the system.
- .github/workflows directory shows integrated CI/CD testing using GitHub Actions.

a. Main Components:
- Smart Contract Modules (represented in the src directory):
- Core: The main logic of the DEX.
- Campaigns: Components handling promotional or community campaigns.
- Governance: Modules that allow stakeholders to participate in decision making.
- Raffle: Modules that drive the raffle functionality.
- Router: Facilitates the transaction routing logic.
- Interfaces & Library: Utility layers and standardized contract interfaces.
- Dependency / Library Components:
- OpenZeppelin Contracts: Standard token and security contracts.
- Solmate & Forge-std: Used to bolster the development, testing, and security.
- External Tools & Environment:
- Foundry: For testing and building smart contracts.
- pnpm: For package management.
- CI/CD Pipeline (GitHub Actions): Automated testing as defined in the .github/workflows directory.
- Deployment Scripts:
- Scripts used for deployment and utilities found in the script directory.
- Testing Infrastructure:
- Test modules and utilities as seen in the test directory.

b. Relationships and Interactions:
- The "Router" module interfaces with the "Core" to process swaps and liquidity transactions.
- "Governance" interacts with "Core" and possibly "Campaigns" to modify rules or proposals.
- "Raffle" is connected to both "Core" (for liquidity tracking or participation) and the "Campaigns" mechanics.
- The "Interfaces" and "Library" modules act as shared resources for multiple smart contract modules.
- The CI/CD pipeline triggers tests and builds that cover all these components.
- Deployment scripts use configuration files (like foundry.toml, remappings.txt) to correctly deploy the smart contracts.

c. Architectural Patterns and Design Principles:
- Modular Contract Design: Each separate folder under src represents a well-defined module.
- Separation of Concerns: Different functionality (campaigns, governance, raffle, router) is isolated within their own components.
- Dependency Reuse: Libraries like OpenZeppelin and Solmate are leveraged, which is standard practice in Solidity development.
- Testing and CI/CD Integration: Ensuring that each component is covered by unit/integration tests with automated testing pipelines.

d. Relevant Technologies, Frameworks, or Libraries:
- Solidity: Core programming language for smart contracts.
- Foundry: Development, testing, and deployment framework.
- OpenZeppelin, Solmate, and Forge-std: Utility libraries for security, token standards, and testing.
- pnpm: Package management.
- GitHub Actions: CI/CD workflow management.

##### Elements
- Use clear, concise labels for each component (e.g., "Core DEX Logic", "Governance Module", "Raffle Module", "Router", "Campaigns").
- For example, use rectangles for smart contract components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    U["User Interface"]:::external
    
    %% External Tools and Pipelines
    K["CI/CD Pipeline"]:::cid
    L["Testing Infrastructure"]:::test
    M["Deployment Scripts"]:::deployment

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        H["OpenZeppelin Contracts"]:::library
        I["Solmate"]:::library
        J["Forge-std"]:::library
    end

    %% On-Chain Environment (Smart Contracts)
    subgraph "Blockchain / On-Chain Environment"
        A["Core DEX Logic"]:::smartcontracts
        B["Campaigns Module"]:::smartcontracts
        C["Governance Module"]:::smartcontracts
        D["Raffle Module"]:::smartcontracts
        E["Router (Transaction Routing)"]:::smartcontracts
        F["Interfaces (Standardized Interactions)"]:::smartcontracts
        G["Library (Shared Utilities)"]:::smartcontracts
    end

    %% User interactions
    U -->|"initiates"| E
    U -->|"initiates"| A

    %% Internal interactions between smart contract modules
    E -->|"processes"| A
    C -->|"updates"| A
    C -->|"interacts"| B
    D -->|"participates"| A
    D -->|"couples"| B
    F -.->|"supports"| A
    G -.->|"supports"| A

    %% External dependencies supporting the on-chain environment
    H -.->|"provides utilities"| A
    I -.->|"provides utilities"| A
    J -.->|"provides utilities"| A

    %% CI/CD and Testing interactions
    K -->|"triggers"| L
    L -->|"validates"| A

    %% Deployment Scripts flow into the blockchain
    M -->|"deploys"| A

    %% Click Events for Smart Contract Modules
    click A "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/core"
    click B "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/campaigns"
    click C "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/governance"
    click D "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/raffle"
    click E "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/router"
    click F "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/interfaces"
    click G "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/src/library"

    %% Click Events for Dependencies
    click H "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/lib/openzeppelin-contracts"
    click I "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/lib/solmate"
    click J "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/lib/forge-std"

    %% Click Events for Deployment, Testing, and CI/CD
    click M "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/script/utils"
    click L "https://github.com/bubble-finance/bubble-v1-protocol/tree/main/test"
    click K "https://github.com/bubble-finance/bubble-v1-protocol/blob/main/.github/workflows/test.yml"

    %% Styles
    classDef smartcontracts fill:#FAD7A0,stroke:#E59866,stroke-width:2px;
    classDef external fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef test fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef deployment fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef cid fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef library fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
```
