# bcnmy/nexus architecture

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

- Interactive diagram: https://gitdiagram.com/bcnmy/nexus
- Repository: https://github.com/bcnmy/nexus

## Overview

This project is a smart contract foundation for modular smart accounts built on the ERC-7579 standard. The repository supports both Foundry and Hardhat development environments, which is evident from the presence of configuration files (foundry.toml, hardhat.config.ts), separate deployment scripts (in scripts/foundry and scripts/hardhat), and extensive test directories for both frameworks. The README further confirms that this solution is aimed at streamlining contract development with a major focus on security, best practices, and efficiency in the blockchain space.

##### Main Components
- Smart Contracts: Represented by the “contracts” directory which is organized into several subdirectories such as base, common, factory, interfaces, modules, and utilities. This communicates that the project is highly modular with clearly separated contract concerns.
- Testing Frameworks: Two main testing components are present:
- Foundry-based tests (test/foundry) – includes unit tests, integration tests, and tests for forking networks.
- Hardhat-based tests (test/hardhat) – covers similar areas including deployment and smart account executions.
- Deployment Scripts: Found in the “scripts” directory with sub-folders for Foundry and Hardhat. These are used for deploying contracts to various networks (e.g., mainnet and testnet), which indicates a separation of deployment concerns.
- CI/CD & Automation: The .github directory with workflows, issue templates, and pull request templates outlines the inclusion of automated checks, branch naming policies, and gas/diff reporting through GitHub Actions.
- Development & Configuration: Files such as .env.example, package.json, tsconfig.json, and various YAML configuration files indicate the project’s reliance on both JavaScript/TypeScript tooling and Ethereum-specific tooling.
- Documentation & Audit Resources: The README links to additional documentation (wiki, external deployment references, security audits, and gas optimization details), and directories like audits provide external audit documentation.

##### Relationships and Interactions
- The contracts serve as the core business logic; they interact with each other via interfaces and library functions, and any factory modules help in creating instances of accounts or modules.
- Deployment scripts act as orchestrators that deploy these contracts to a blockchain. They often take into account network-specific configurations through dynamic network configuration scripts.
- Testing components ensure that each contract module is unit, integration, or fuzz tested, with Foundry and Hardhat tests working in parallel to ensure comprehensive coverage.
- CI/CD pipelines (configured via GitHub workflows) automatically run tests (both for Foundry and Hardhat), lint the code, generate gas and coverage reports, and ensure adherence to code quality standards.

##### Architectural Patterns and Design Principles
- Modularity: The repository is highly modularized. Contracts are split into interfaces, concrete implementations, factories, modules, and libraries, supporting a clean separation of concerns.
- Dual-Environment Support: By having both Foundry and Hardhat setups, developers can choose their preferred framework. This dual support suggests the use of wrappers or abstraction layers that ensure consistency across environments.
- Test-Driven Development (TDD): A comprehensive test suite across both frameworks highlights a strong commitment to TDD and ensures that each component from unit tests to end-to-end tests is well-covered.
- CI/CD and Automation: Integration with GitHub Actions for automated linting, testing, and deployment processes reinforces a modern DevOps approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Configuration Subgraph
    subgraph "Development & Configuration"
        ENV[".env.example"]:::config
        FDT["foundry.toml"]:::config
        HC["hardhat.config.ts"]:::config
        PKG["package.json"]:::config
        TS["tsconfig.json"]:::config
        REM["remappings.txt"]:::config
    end

    %% Smart Contracts Subgraph
    subgraph "Smart Contracts"
        BASE["Base Contracts"]:::contract
        COMMON["Common Contracts"]:::contract
        FACTORY["Factory Modules"]:::contract
        INTERFACES["Interfaces"]:::contract
        MODULES["Modules"]:::contract
        LIB["Libraries"]:::contract
    end

    %% Testing Environments Subgraph
    subgraph "Testing Environments"
        FTEST["Foundry Tests"]:::test
        HTTEST["Hardhat Tests"]:::test
    end

    %% Deployment Scripts Subgraph
    subgraph "Deployment Scripts"
        FSCRIPTS["Foundry Deployment Scripts"]:::script
        HSCRIPTS["Hardhat Deployment Scripts"]:::script
    end

    %% Documentation & Audit Resources Subgraph
    subgraph "Documentation & Audit Resources"
        README["README.md"]:::doc
        AUDITS["Audits"]:::doc
    end

    %% Additional Components
    CICD["CI/CD & Automation"]:::cicd
    NETWORK["Blockchain Network"]:::network

    %% Connections from Development & Configuration to Smart Contracts
    PKG -->|"supports"| BASE
    ENV -->|"configures"| BASE
    FDT -->|"configures"| BASE
    HC -->|"configures"| BASE
    TS -->|"configures"| BASE
    REM -->|"configures"| BASE

    %% Connections from Smart Contracts to Testing Environments and Deployment Scripts
    BASE -->|"testedBy"| FTEST
    COMMON -->|"testedBy"| HTTEST
    INTERFACES -->|"integratedWith"| FTEST
    MODULES -->|"integratedWith"| HTTEST
    LIB -->|"utilizedBy"| FSCRIPTS

    %% Connections from Deployment Scripts to Blockchain Network
    FSCRIPTS -->|"deploysTo"| NETWORK
    HSCRIPTS -->|"deploysTo"| NETWORK

    %% CI/CD Integration
    CICD -->|"runs"| FTEST
    CICD -->|"runs"| HTTEST
    CICD -->|"orchestrates"| FSCRIPTS
    CICD -->|"orchestrates"| HSCRIPTS
    CICD -->|"monitors"| BASE

    %% Documentation & Audit links
    README -->|"documents"| PKG
    AUDITS -->|"reviews"| PKG

    %% Class definitions for styling
    classDef contract fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef test fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef script fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef cicd fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef doc fill:#F5DEB3,stroke:#333,stroke-width:2px;
    classDef network fill:#E0FFFF,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click BASE "https://github.com/bcnmy/nexus/tree/main/contracts/base"
    click COMMON "https://github.com/bcnmy/nexus/tree/main/contracts/common"
    click FACTORY "https://github.com/bcnmy/nexus/tree/main/contracts/factory"
    click INTERFACES "https://github.com/bcnmy/nexus/tree/main/contracts/interfaces"
    click MODULES "https://github.com/bcnmy/nexus/tree/main/contracts/modules"
    click LIB "https://github.com/bcnmy/nexus/tree/main/contracts/lib"

    click FTEST "https://github.com/bcnmy/nexus/tree/main/test/foundry"
    click HTTEST "https://github.com/bcnmy/nexus/tree/main/test/hardhat"
    click FSCRIPTS "https://github.com/bcnmy/nexus/tree/main/scripts/foundry"
    click HSCRIPTS "https://github.com/bcnmy/nexus/tree/main/scripts/hardhat"

    click CICD "https://github.com/bcnmy/nexus/blob/main/.github"

    click ENV "https://github.com/bcnmy/nexus/blob/main/.env.example"
    click FDT "https://github.com/bcnmy/nexus/blob/main/foundry.toml"
    click HC "https://github.com/bcnmy/nexus/blob/main/hardhat.config.ts"
    click PKG "https://github.com/bcnmy/nexus/blob/main/package.json"
    click TS "https://github.com/bcnmy/nexus/blob/main/tsconfig.json"
    click REM "https://github.com/bcnmy/nexus/blob/main/remappings.txt"

    click README "https://github.com/bcnmy/nexus/blob/main/README.md"
    click AUDITS "https://github.com/bcnmy/nexus/tree/main/audits"
```
