# web3-gpt/web3gpt architecture

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

- Interactive diagram: https://gitdiagram.com/web3-gpt/web3gpt
- Repository: https://github.com/web3-gpt/web3gpt

## Overview

##### Main Components
- Frontend Client:
- Represented by the "app" directory and its pages (such as the root page, sign-in, chat, share pages).
- UI components are under the "components" directory (headers, sidebars, chat components, buttons, etc.).
- State management and styling (global CSS, Tailwind config, etc.) are part of this layer.
- API/Backend Layer:
- The "app/api" folder contains several API routes covering functionalities like authentication ([...nextauth]), chat threads (assistants/threads), cron jobs, deploy-contract actions, external deployment, IPFS upload, and more.
- Routes dedicated to smart contract and blockchain-related actions, such as deploy-contract, verify-contract, and completions.
- Business Logic and Helpers:
- The "lib" directory holds core business logic. This includes actions for AI (lib/actions/ai.ts), smart contract operations (lib/actions/solidity/compile-contract.ts, deploy-contract.ts, verify-contract.ts, etc.), IPFS integration, and interactions with external services (Unstoppable Domains, OpenAI, etc.).
- Utility functions, configuration, and hooks (under lib/hooks) that tie together UI interactions with backend processes.
- External Services & Blockchain Integrations:
- The system integrates with multiple blockchain testnets and external services (like IPFS, OpenZeppelin, Unstoppable Domains).

##### Out the Relationships and Interactions
- Data Flow:
- Frontend calling the API endpoints. For example, user interactions (chat messages, contract deployments) on the UI trigger API requests.
- Internal Communication:
- Within the backend, illustrate how specific API calls (say, for deploying a contract) use the business logic found in the “lib/actions/solidity” subdirectories.
- Interactions such as authentication flows (via NextAuth in “app/api/auth/[...nextauth]”) and how session management propagates to other parts of the system.
- External Integrations:
- API endpoints (or service components in "lib") to external blockchain networks and third-party services like IPFS, OpenAI, and Unstoppable Domains.

##### Architectural Patterns/Design Principles
- Modular Structure:
- The project is divided into clear modules: Frontend (UI and pages), Backend (API routes), Business Logic (lib), and external integrations.
- How separation of concerns (e.g., API routes for different functionalities and dedicated business logic modules) enhances maintainability.
- Next.js Convention:
- Use of file-based routing in the "app" directory indicates a conventional Next.js architecture, split between pages and API endpoints.
- Scalability:
- With features like cron endpoints and microservice-like API routes (each function in its own folder), the design is oriented toward scalability and potentially further micro-frontends or service expansion.

##### Relevant Technologies, Frameworks, and Patterns
- Technologies/Frameworks:
- Next.js for both server-side rendering (pages and API routes) and client-side interactivity.
- Integration with blockchain networks and smart contract deployment (solidity compilation, deployment via libraries in “lib/actions/solidity”).
- Authentication via NextAuth.
- Bun for package management and server execution (bun.lockb and bun commands in README).
- Tailwind CSS for styling and possibly units from UI libraries found in the “components/ui” folder.
- Architectural Patterns:
- MVC-like separation where the “app” layer is the View, the “app/api” along with “lib” comprise the Controller and Model parts.
- Use of hooks and providers in the “lib” and “components/providers” directories to manage state and external services (like web3 providers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Client
    subgraph "Frontend Client"
        FP1["Home Page"]:::frontend
        FP2["Sign In Page"]:::frontend
        FP3["Chat Page"]:::frontend
        FP4["Share Page"]:::frontend
        FC1["Header"]:::frontend
        FC2["Chat Component"]:::frontend
        FC3["UI Components"]:::frontend
    end

    %% API/Backend Layer
    subgraph "API/Backend Layer"
        API1["Authentication API"]:::api
        API2["Deploy Contract API"]:::api
        API3["Chat Threads API"]:::api
        API4["Cron Jobs API"]:::api
        API5["IPFS Upload API"]:::api
        API6["Completions API"]:::api
        API7["Verify Contract API"]:::api
    end

    %% Business Logic & Helpers
    subgraph "Business Logic & Helpers"
        BL1["AI Actions"]:::logic
        BL2["Deploy Contract Logic"]:::logic
        BL3["Solidity Compile"]:::logic
        BL4["Solidity Deploy"]:::logic
        BL5["Solidity Verify"]:::logic
        BL6["Custom Hooks"]:::logic
    end

    %% External Services & Blockchain Integrations
    subgraph "External Services & Blockchain Integrations"
        EX1["Unstoppable Domains Integration"]:::external
        EX2["IPFS Service"]:::external
        EX3["OpenAI Integration"]:::external
    end

    %% Frontend to API connections
    FP2 -->|"calls"| API1
    FC1 -->|"triggers"| API1
    FP3 -->|"calls"| API3
    FC2 -->|"triggers"| API3
    FP4 -->|"calls"| API2
    FC3 -->|"triggers"| API2
    FP1 -->|"calls"| API6

    %% API to Business Logic connections
    API2 -->|"processes"| BL2
    API2 -->|"invokes"| BL3
    API2 -->|"invokes"| BL4
    API7 -->|"invokes"| BL5
    API3 -->|"processes"| BL1
    API6 -->|"processes"| BL1
    API5 -->|"uploads_to"| EX2

    %% Business Logic to External Services connections
    BL1 -->|"integrates_with"| EX3
    BL2 -->|"integrates_with"| EX1
    BL4 -->|"integrates_with"| EX1

    %% Click Events for Frontend Client
    click FP1 "https://github.com/web3-gpt/web3gpt/blob/master/app/page.tsx"
    click FP2 "https://github.com/web3-gpt/web3gpt/blob/master/app/sign-in/page.tsx"
    click FP3 "https://github.com/web3-gpt/web3gpt/blob/master/app/chat/[id]/page.tsx"
    click FP4 "https://github.com/web3-gpt/web3gpt/blob/master/app/share/[id]/page.tsx"
    click FC1 "https://github.com/web3-gpt/web3gpt/tree/master/components/header"
    click FC2 "https://github.com/web3-gpt/web3gpt/tree/master/components/chat"
    click FC3 "https://github.com/web3-gpt/web3gpt/tree/master/components/ui"

    %% Click Events for API/Backend Layer
    click API1 "https://github.com/web3-gpt/web3gpt/blob/master/app/api/auth/[...nextauth]/route.ts"
    click API2 "https://github.com/web3-gpt/web3gpt/blob/master/app/api/deploy-contract/route.ts"
    click API3 "https://github.com/web3-gpt/web3gpt/tree/master/app/api/assistants/threads"
    click API4 "https://github.com/web3-gpt/web3gpt/tree/master/app/api/cron"
    click API5 "https://github.com/web3-gpt/web3gpt/blob/master/app/api/ipfs-upload/route.ts"
    click API6 "https://github.com/web3-gpt/web3gpt/blob/master/app/api/v1/completions/route.ts"
    click API7 "https://github.com/web3-gpt/web3gpt/blob/master/app/api/verify-contract/route.ts"

    %% Click Events for Business Logic & Helpers
    click BL1 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/ai.ts"
    click BL2 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/deploy-contract.ts"
    click BL3 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/solidity/compile-contract.ts"
    click BL4 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/solidity/deploy-contract.ts"
    click BL5 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/solidity/verify-contract.ts"
    click BL6 "https://github.com/web3-gpt/web3gpt/tree/master/lib/hooks"

    %% Click Events for External Services & Blockchain Integrations
    click EX1 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/unstoppable-domains.ts"
    click EX2 "https://github.com/web3-gpt/web3gpt/blob/master/lib/actions/ipfs.ts"
    click EX3 "https://github.com/web3-gpt/web3gpt/blob/master/lib/data/openai.ts"

    %% Class definitions for styling
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef logic fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
