# valesh-gosats/donation-portal-dapp architecture

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

- Interactive diagram: https://gitdiagram.com/valesh-gosats/donation-portal-dapp
- Repository: https://github.com/valesh-gosats/donation-portal-dapp

## Overview

##### Main Components
- Frontend (Next.js App):
- This includes the UI for various pages (home, create donation, dashboard, opportunities list/detail) and reusable React components (e.g., Header, Navbar, ConnectButton).
- Custom hooks (e.g., useDonationOpportunities, useEthPrice, useOpportunityFactory) indicate direct Web3 interactions.
- Providers, such as the Web3 provider, manage blockchain connectivity.

- Blockchain Layer:
- Smart contracts in the "contracts" folder define the logic for donation opportunities.
- ABIs in app/lib/contracts describe the contract interfaces and are used for Ethers.js integrations.
- Scripts (scripts/deploy.ts) indicate deployment routines for the blockchain contracts.

- Storage & Decentralized Proof Storage:
- IPFS utilities in app/lib/ipfs demonstrate integration with decentralized file storage.
- This is critical for storing verification data or proofs in a transparent and tamper-proof way.

- Backend & Database (though minimal code is present in the repository, the README mentions it):
- Supabase and Prisma ORM serve as the backend for authentication, recipients’ profiles, and transactional data.
- Even if not directly visible in the file tree, these services should be represented.

- Additional Utilities:
- Helper files like conversion utilities (usdToEth.ts) and country libraries (countries.ts)
- Configuration files (.env.example, next.config.js, hardhat.config.cjs) denote environment settings, contract deployments, and general project configuration.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separation with directories for components, hooks, libraries, and pages indicates a modular, maintainable architecture.
- Decoupling Between Frontend and Blockchain: The use of custom hooks and lib files (e.g., wagmi.ts) encapsulates Web3 interactions separately from UI concerns.
- API Routes: If API endpoints exist under "app/api", show them as intermediary layers between the frontend and backend.
- Use of Providers: Illustrate provider components (e.g., Web3Provider) to manage global state and external integrations.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: Next.js, React, TailwindCSS.
- Blockchain: Ethereum, Ethers.js (via provided contract ABIs), and Hardhat for contracts.
- Storage: IPFS (web3.storage).
- Authentication/Backend: Supabase, Prisma ORM.
- Additional libraries: Custom hooks for Ethereum price retrieval and factory interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Decentralized Donation Platform"]:::core

    subgraph "Frontend Layer"
        FP["Next.js App"]:::frontend
        subgraph "Pages"
            Home["Home Page"]:::page
            Create["Create Donation Page"]:::page
            Dashboard["Dashboard Page"]:::page
            Opportunities["Opportunities List"]:::page
            OpportunityDetail["Opportunity Detail"]:::page
        end
        subgraph "Components"
            Header["Header"]:::component
            Navbar["Navbar"]:::component
            ConnectButton["ConnectButton"]:::component
            OpportunityCard["OpportunityCard"]:::component
            OpportunityFilters["OpportunityFilters"]:::component
        end
        subgraph "Custom Hooks"
            Hook1["useDonationOpportunities"]:::hook
            Hook2["useEthPrice"]:::hook
            Hook3["useOpportunityFactory"]:::hook
        end
        subgraph "Providers"
            Web3Provider["Web3Provider"]:::provider
            GlobalProviders["Global Providers"]:::provider
        end
    end

    subgraph "Blockchain Layer"
        Contracts["Smart Contract Interfaces"]:::blockchain
        Deployment["Deployment Script"]:::blockchain
        Hardhat["Hardhat Configuration"]:::blockchain
    end

    Storage["IPFS Utilities"]:::storage
    Backend["Backend (Supabase/Prisma)"]:::backend

    subgraph "Additional Utilities"
        USDtoEth["Currency Conversion"]:::utility
        Countries["Country Data Library"]:::utility
    end

    A --> FP
    FP -->|"DonationTransaction"| Contracts
    FP -->|"DataQuery"| Backend
    FP -->|"IPFSUpload"| Storage
    Hook1 -->|"InteractsWith"| Contracts
    Hook2 -->|"InteractsWith"| Contracts
    Hook3 -->|"InteractsWith"| Contracts

    %% Click Events for Frontend Pages
    click Home "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/page.tsx"
    click Create "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/create/page.tsx"
    click Dashboard "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/dashboard/page.tsx"
    click Opportunities "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/opportunities/page.tsx"
    click OpportunityDetail "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/opportunities/[id]/page.tsx"

    %% Click Events for Reusable Components
    click Header "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/components/Header.tsx"
    click Navbar "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/components/Navbar.tsx"
    click ConnectButton "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/components/ConnectButton.tsx"
    click OpportunityCard "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/components/OpportunityCard.tsx"
    click OpportunityFilters "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/components/OpportunityFilters.tsx"
    
    %% Click Events for Custom Hooks
    click Hook1 "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/hooks/useDonationOpportunities.ts"
    click Hook2 "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/hooks/useEthPrice.ts"
    click Hook3 "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/hooks/useOpportunityFactory.ts"

    %% Click Events for Providers
    click Web3Provider "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/providers/Web3Provider.tsx"
    click GlobalProviders "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/providers.tsx"

    %% Click Events for Blockchain Layer
    click Contracts "https://github.com/valesh-gosats/donation-portal-dapp/tree/main/app/lib/contracts"
    click Deployment "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/scripts/deploy.ts"
    click Hardhat "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/hardhat.config.cjs"

    %% Click Events for Storage & Decentralized Proof Storage
    click Storage "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/lib/ipfs.ts"

    %% Click Events for Additional Utilities
    click USDtoEth "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/lib/usdToEth.ts"
    click Countries "https://github.com/valesh-gosats/donation-portal-dapp/blob/main/app/lib/countries.ts"

    %% Class Definitions for Coloring
    classDef core fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef frontend fill:#FFEDD5,stroke:#D2691E,stroke-width:2px;
    classDef page fill:#FFF8DC,stroke:#DAA520,stroke-width:1px;
    classDef component fill:#FFE4E1,stroke:#C71585,stroke-width:1px;
    classDef hook fill:#E6E6FA,stroke:#8A2BE2,stroke-width:1px;
    classDef provider fill:#E0FFFF,stroke:#20B2AA,stroke-width:1px;
    classDef blockchain fill:#F0FFF0,stroke:#2E8B57,stroke-width:2px;
    classDef storage fill:#F0F8FF,stroke:#4682B4,stroke-width:2px;
    classDef backend fill:#FFF0F5,stroke:#FF69B4,stroke-width:2px;
    classDef utility fill:#F5F5DC,stroke:#8B4513,stroke-width:1px;
```
