# sanisabodakhe/impactchain architecture

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

- Interactive diagram: https://gitdiagram.com/sanisabodakhe/impactchain
- Repository: https://github.com/sanisabodakhe/impactchain

## Overview

##### Project type and purpose
- **Type**: Single-page React application built with Vite, TailwindCSS, and Framer Motion.
- **Purpose**: Frontend for **ImpactChain**, a blockchain-enabled CSR platform with AI-powered verification, smart contract automation, and real-time analytics.

##### File structure
- **Top-level files**:
- package.json, vite.config.mjs, tailwind.config.js → build & tooling
- index.html → SPA entry point
- **Public folder**: static assets, manifest, robots.txt
- **src folder**:
- **index.jsx / App.jsx / Routes.jsx** → SPA bootstrapping & routing
- **components/** → shared UI primitives (Button, Input, Breadcrumb, etc.)
- **pages/** → feature modules:
– ai-verification-interface
– authentication
– corporate-dashboard
– csr-project-marketplace
– landing-page
– ngo-project-management
– ngo-projects
- **services/projectService.js** → HTTP or Web3 calls to backend/API/smart contracts
- **utils/** → helper functions (navigation, classnames)
- **styles/** → Tailwind + custom CSS

##### Extract architecture insights from README
- **Client** → React SPA with routes per user persona (corporate, NGO, verifier).
- **Backend / Smart Contracts**: off-chain API + on-chain smart contracts (Ethereum), IPFS for evidence storage.
- **AI Verification Engine**: image & document analysis, NLP, confidence scoring.
- **Blockchain Network**: smart contracts for fund locking/release, ERC-721 Impact Tokens.
- **External Services**: MetaMask / WalletConnect, IPFS gateway, blockchain RPC nodes.

##### Main components
a. **Users / Clients**
- Corporate Donor (browser + wallet)
- NGO Project Manager (browser + wallet)
- Verifier (browser + wallet)
b. **Frontend SPA**
- React/Vite application
- Pages & UI components
- State & routing layer (React Router in Routes.jsx)
- Service layer (projectService.js)
c. **API Layer** (Off-chain backend)
- REST/GraphQL API
- Authentication & authorization (JWT / Web3 signature)
- Project & milestone management endpoints
d. **AI Verification Engine**
- Image analysis (Computer Vision)
- Document NLP
- ML confidence scoring & fraud detection
- Audit trail logging
e. **Blockchain Network**
- Smart Contracts (fund escrow, milestone triggers, token minting)
- Impact Tokens (ERC-721)
- Wallet integration (MetaMask, WalletConnect)
f. **Storage**
- IPFS (evidence & documents)
- Off-chain Database (project metadata, user profiles, analytics)
g. **Analytics & Notification**
- Real-time dashboards (Recharts)
- WebSocket or polling for live updates

##### Relationships & data flows
1. **User Interaction** → React SPA (UI components → pages)
2. **SPA → API Layer** via HTTPS / Web3 calls
3. **API → Database** for CRUD
4. **SPA → IPFS** to upload evidence (via IPFS gateway API)
5. **API → AI Engine** to process evidence
6. **AI Engine → API** returns verification decision
7. **API → Smart Contracts** (on blockchain RPC) to lock / release funds and mint tokens
8. **Blockchain → API / Events** triggers notifications / updates
9. **SPA** listens for events or polls for status → updates UI

##### Architectural patterns & principles
- **Modular SPA**: feature-based folder structure for pages & components
- **Clear separation**: UI layer (components & pages), service layer (API/Web3), external systems
- **Microservice-style**: AI engine decoupled from business API
- **Event-driven fund release**: on-chain events feed back to off-chain systems
- **Progressive enhancement**: responsive design, wallet integration fallback

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Roles
    Corporate["Corporate Donor\n(browser + wallet)"]:::external
    NGOUser["NGO Project Manager\n(browser + wallet)"]:::external
    Verifier["Verifier\n(browser + wallet)"]:::external

    %% Frontend Zone
    subgraph "Frontend (ImpactChain SPA)" 
        direction TB
        SPA_HTML["index.html"]:::frontend
        SPA_JS["src/index.jsx"]:::frontend
        App["src/App.jsx"]:::frontend
        Routes["src/Routes.jsx"]:::frontend

        subgraph "Components" 
            direction TB
            Components["src/components"]:::frontend
            UI["src/components/ui"]:::frontend
        end

        subgraph "Pages"
            direction TB
            AIV["ai-verification-interface\n(index.jsx)"]:::frontend
            AIVComp["components"]:::frontend
            Auth["authentication\n(index.jsx)"]:::frontend
            AuthComp["components"]:::frontend
            CorpDash["corporate-dashboard\n(index.jsx)"]:::frontend
            CorpDashComp["components"]:::frontend
            Marketplace["csr-project-marketplace\n(index.jsx)"]:::frontend
            MarketComp["components"]:::frontend
            Landing["landing-page\n(index.jsx)"]:::frontend
            LandingComp["components"]:::frontend
            NGOMan["ngo-project-management\n(index.jsx)"]:::frontend
            NGOManComp["components"]:::frontend
            NGOList["ngo-projects\n(index.jsx)"]:::frontend
        end

        Service["src/services/projectService.js"]:::frontend
        Utils["src/utils"]:::frontend
        StylesIndex["src/styles/index.css"]:::frontend
        StylesTailwind["src/styles/tailwind.css"]:::frontend
    end

    %% Backend & External Zone
    subgraph "Backend & External Services"
        direction TB
        API["REST/GraphQL API"]:::backend
        DB["Off-chain Database\n(project metadata, user profiles)"]:::storage
        IPFS["IPFS Gateway\n(evidence storage)"]:::storage
        subgraph "AI Verification Engine"
            direction TB
            AIImg["Image Analysis"]:::backend
            AINLP["Document NLP & Scoring"]:::backend
            Audit["Audit Trail"]:::backend
        end
        subgraph "Blockchain Network"
            direction TB
            Contracts["Smart Contracts\n(fund escrow, tokens)"]:::blockchain
            RPC["Ethereum RPC Nodes"]:::external
            Token["ERC-721 Impact Tokens"]:::blockchain
        end
        Wallet["MetaMask / WalletConnect"]:::external
    end

    %% Data Flows
    Corporate -->|1. Browse/Interact| SPA_HTML
    NGOUser -->|1. Browse/Interact| SPA_HTML
    Verifier -->|1. Browse/Interact| SPA_HTML

    SPA_HTML -->|2. Boot | SPA_JS
    SPA_JS -->|3. Render| App
    App -->|4. Routing| Routes
    Routes -->|5. Load UI| Components
    Components --> UI
    Routes --> Pages

    Pages --> AIV
    AIV --> AIVComp
    Pages --> Auth
    Auth --> AuthComp
    Pages --> CorpDash
    CorpDash --> CorpDashComp
    Pages --> Marketplace
    Marketplace --> MarketComp
    Pages --> Landing
    Landing --> LandingComp
    Pages --> NGOMan
    NGOMan --> NGOManComp
    Pages --> NGOList

    Pages -->|6. Service Calls| Service
    Service -->|7. HTTP/Web3| API
    Service -->|8. Utils| Utils

    API -->|9. CRUD| DB
    API -->|10. Upload Evidence| IPFS
    API -->|11. Send for Verification| AIImg
    AIImg --> AINLP
    AINLP --> Audit
    Audit --> API

    API -->|12. Blockchain Tx| Contracts
    Contracts --> RPC
    Contracts --> Token
    RPC -->|13. Event| API

    API -->|14. Notify| SPA_JS

    SPA_JS -->|15. Real-time Updates| RPC
    SPA_JS -->|16. Poll/WS| API

    %% Click Events
    click SPA_HTML "https://github.com/sanisabodakhe/impactchain/blob/main/index.html"
    click SPA_JS "https://github.com/sanisabodakhe/impactchain/blob/main/src/index.jsx"
    click App "https://github.com/sanisabodakhe/impactchain/blob/main/src/App.jsx"
    click Routes "https://github.com/sanisabodakhe/impactchain/blob/main/src/Routes.jsx"
    click Components "https://github.com/sanisabodakhe/impactchain/tree/main/src/components"
    click UI "https://github.com/sanisabodakhe/impactchain/tree/main/src/components/ui"
    click AIV "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/ai-verification-interface/index.jsx"
    click AIVComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/ai-verification-interface/components"
    click Auth "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/authentication/index.jsx"
    click AuthComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/authentication/components"
    click CorpDash "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/corporate-dashboard/index.jsx"
    click CorpDashComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/corporate-dashboard/components"
    click Marketplace "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/csr-project-marketplace/index.jsx"
    click MarketComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/csr-project-marketplace/components"
    click Landing "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/landing-page/index.jsx"
    click LandingComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/landing-page/components"
    click NGOMan "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/ngo-project-management/index.jsx"
    click NGOManComp "https://github.com/sanisabodakhe/impactchain/tree/main/src/pages/ngo-project-management/components"
    click NGOList "https://github.com/sanisabodakhe/impactchain/blob/main/src/pages/ngo-projects/index.jsx"
    click Service "https://github.com/sanisabodakhe/impactchain/blob/main/src/services/projectService.js"
    click Utils "https://github.com/sanisabodakhe/impactchain/tree/main/src/utils"
    click StylesIndex "https://github.com/sanisabodakhe/impactchain/blob/main/src/styles/index.css"
    click StylesTailwind "https://github.com/sanisabodakhe/impactchain/blob/main/src/styles/tailwind.css"
    click Public "https://github.com/sanisabodakhe/impactchain/tree/main/public/assets"
    click Manifest "https://github.com/sanisabodakhe/impactchain/blob/main/public/manifest.json"
    click Robots "https://github.com/sanisabodakhe/impactchain/blob/main/public/robots.txt"
    click Config1 "https://github.com/sanisabodakhe/impactchain/blob/main/package.json"
    click Config2 "https://github.com/sanisabodakhe/impactchain/blob/main/vite.config.mjs"
    click Config3 "https://github.com/sanisabodakhe/impactchain/blob/main/tailwind.config.js"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef storage fill:#f5f5f5,stroke:#9e9e9e,color:#424242
    classDef blockchain fill:#fff8e1,stroke:#ffb300,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#263238
```
