# valeshgopal/donation-portal-dapp architecture

> Architecture diagram of the GitHub repository valeshgopal/donation-portal-dapp, 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/valeshgopal/donation-portal-dapp
- Repository: https://github.com/valeshgopal/donation-portal-dapp

## Overview

##### Main Components
- Frontend (Next.js/React)
- Represented by the “app” directory containing pages, components, hooks, and providers.
- Components like ConnectButton.tsx, OpportunityCard.tsx, and CreateOpportunityForm.tsx indicate that the UI caters to both donor interactions (wallet connection, donation forms) and recipient profiles.
- API Routes & Backend Logic
- The “app/api” folder has endpoints for functionalities like “didit”, “kyc”, and “webhook”, which map to wallet-based authentication, KYC verification, and other API integrations.
- Blockchain/Smart Contracts
- The “contracts” directory holds smart contracts (including Hardhat configurations) along with ABI definitions in “app/lib/contracts”. This part manages decentralized donation logic and interactions with Ethereum.
- Decentralized Storage & External Services
- The “app/lib/ipfs.ts” and usage of “web3.storage” via IPFS indicate the use of decentralized storage for proof and metadata.
- Database & External Integrations
- The “app/lib/mongodb.ts” shows the integration with MongoDB for storing donor/recipient data and transaction tracking.

##### Relationships and Interactions
- Frontend interacts with APIs through the Next.js App Router:
- API routes (such as those in “app/api”) serve as the backend layer handling tasks like creating sessions (didit) and processing KYC verifications.
- Backend integrates with Blockchain:
- User wallet-based authentication and transactions invoke smart contract functions via Ethers.js (logic partly found in “app/lib/wagmi.ts” and contract ABIs).
- Off-Chain Storage and On-Chain Verification:
- When a donation is made, the platform logs transactions on Ethereum and stores relevant proofs/data on IPFS.
- User Flow:
- The frontend components (e.g., OpportunityCard, CreateOpportunityForm) interface with custom hooks (like useEthPrice, useOpportunityFactory) to dynamically fetch on-chain data and combine it with off-chain data from MongoDB.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Clear separation between UI (app/components), business logic and data fetching (app/hooks, app/lib), and API routes (app/api).
- Modularization:
- Smart contracts are maintained separately in “contracts”, and their interactions are abstracted in the “app/lib/contracts”.
- Decentralization:
- The architecture leverages decentralized storage (IPFS), blockchain for transaction verifiability, and wallet authentication for user identity.
- Full-Stack and Distributed System Integration:
- Combining a modern React-based frontend, a Node/Next.js backend, blockchain smart contracts, and decentralized storage points to a distributed full-stack design.

##### Relevant Technologies
- Frontend: Next.js 14, React 18, TailwindCSS.
- Backend: API routes in Next.js, MongoDB (using mongoose).
- Blockchain: Ethereum, Ethers.js.
- Storage: IPFS/Web3.storage.
- Misc: Wallet Connect, custom hooks for Ethereum interactions.

##### Final Recommendations
- Then, drill down into each layer to show key modules. For example, extend the Frontend layer to show how components, hooks, and providers interact.
- That all connections are well annotated: for instance, the “Create Session” route in “didit” should clearly be connected with authentication flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js/React)"
        FE["App Directory: UI & Pages"]:::frontend
        UI["UI Components (ConnectButton, OpportunityCard, CreateOpportunityForm)"]:::frontend
        HK["Custom Hooks & Providers"]:::frontend
        FE --> UI
        FE --> HK
    end

    %% Backend/API Layer
    subgraph "Backend/API"
        API["API Routes (didit, kyc, webhook)"]:::backend
        DB["MongoDB Integration"]:::external
        API -->|"donation_data_submission"| DB
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        SC["Smart Contracts & ABIs"]:::blockchain
        ETH["Ethereum Connection (Ethers.js via wagmi)"]:::blockchain
        SC -->|"contract_calls"| ETH
    end

    %% Decentralized Storage
    subgraph "Decentralized Storage"
        IPFS["IPFS & Web3.storage"]:::storage
    end

    %% Interactions between layers
    UI -->|"submit_donation"| API
    HK -->|"fetch_onchain_data"| SC
    HK -->|"fetch_offchain_data"| DB
    API -->|"invoke_contract"| SC
    API -->|"store_proof"| IPFS
    ETH -->|"tx_hash_update"| UI

    %% Click Events
    click FE "https://github.com/valeshgopal/donation-portal-dapp/tree/main/app"
    click UI "https://github.com/valeshgopal/donation-portal-dapp/tree/main/app/components"
    click API "https://github.com/valeshgopal/donation-portal-dapp/tree/main/app/api"
    click SC "https://github.com/valeshgopal/donation-portal-dapp/tree/main/contracts"
    click ETH "https://github.com/valeshgopal/donation-portal-dapp/blob/main/app/lib/wagmi.ts"
    click IPFS "https://github.com/valeshgopal/donation-portal-dapp/blob/main/app/lib/ipfs.ts"
    click DB "https://github.com/valeshgopal/donation-portal-dapp/blob/main/app/lib/mongodb.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef blockchain fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef storage fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
```
