# sagarshivalingappaathani/public-fund-management architecture

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

- Interactive diagram: https://gitdiagram.com/sagarshivalingappaathani/public-fund-management
- Repository: https://github.com/sagarshivalingappaathani/public-fund-management

## Overview

##### Project type and purpose
- This is a full‑stack decentralized application (DApp) for public fund management.
- Core purpose: allow authorities and citizens to propose, vote on, and release government funds in stages using Ethereum smart contracts, with AI‑powered verification of utilization reports.

##### File structure
- Top level:
- backend/ – Django REST API for AI‑powered document analysis
- frontend/ – Next.js application with React components and Web3 integration
- smart‑contracts/ – Hardhat‑based Solidity contracts and deployment scripts
- files/ – sample output PDF
- backend directory follows a typical Django MVC layout (APIs app, settings, migrations, middleware).
- frontend uses Next.js “app” router, custom hooks, component library (ui/) and Web3 contract libraries in lib/.
- smart‑contracts holds Solidity code, tests, deployment scripts, Hardhat config.

##### README for additional insights
- Workflow:
a. Authorities create/vote on proposals on-chain
b. Public votes with soulbound tokens (SBT)
c. Funds released in 3 stages; each stage release conditioned on report upload (to IPFS)
d. Django backend analyzes reports via RAG + LangChain + vector DB + LLM
- Technologies:
- Smart contracts on Ethereum + IPFS for off‑chain storage
- Next.js + Web3.js
- Django REST + Groq API + HuggingFace embeddings + FAISS

##### Main components & interactions
a. Frontend (Next.js)
– React pages and components
– Web3 provider / Wallet connector
– Calls smart‑contract functions and listens to events
– Calls Django API for report analysis
b. Backend API (Django)
– /analyze/ endpoint
– Document loader → text‑chunker → embeddings → FAISS vector store → LangChain RAG → decision logic
– Returns analysis and CID back to frontend or triggers contract call
c. Smart contracts (Solidity)
– PublicFundManagement.sol (proposal, voting, staged disbursement)
– SoulboundToken.sol (SBT issuance for public voters)
– Deploy scripts and tests
d. Blockchain network
– Ethereum (e.g., testnet/mainnet) for contract state and events
– IPFS for storing report documents, smart contract stores CIDs
e. External services
– GROQ API / LLM
– HuggingFace embeddings
– IPFS gateway
– FAISS vector store (could be self‑hosted or cloud)

##### Architectural patterns & design principles
- Layered architecture:
- Presentation layer (frontend)
- API layer (Django REST)
- Smart‑contract layer (on‑chain business logic)
- Data / storage layer (Ethereum state + IPFS + vector store)
- Event‑driven interactions: frontend listens to on‑chain events to reflect state changes
- RAG microservice: decoupled AI pipeline behind REST API
- Separation of concerns: UI, blockchain logic, AI logic are separate components that communicate via well‑defined interfaces

##### Essential details to capture
- Multi-stage funding workflow: initial proposal → authority vote → public vote → stage‑wise disbursement
- AI verification loop: report upload → RAG analysis → automated fund release or review trigger
- Off‑chain storage vs. on‑chain state differentiation
- Extensibility: where to plug in additional standard questions or new LLM models

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        Browser["User Browser"]:::client
        Browser --> FrontendApp
    end

    %% Frontend Layer
    subgraph "Frontend (Next.js)" 
        FrontendApp["Next.js App"]:::frontend
        Layout["layout.tsx"]:::frontend
        Providers["providers.tsx"]:::frontend
        HomePage["dashboard/home/page.tsx"]:::frontend
        FundList["dashboard/fund-mangement/page.tsx"]:::frontend
        FundDetail["dashboard/fund-mangement/[id]/page.tsx"]:::frontend
        PFUI["PublicFundManagement UI"]:::frontend
        UILib["UI Library"]:::frontend
        Hook1["useWallet.ts"]:::frontend
        Hook2["useContractData.ts"]:::frontend
        Hook3["useProposals.ts"]:::frontend
        Hook4["use-toast.ts"]:::frontend
        Lib1["publicFundingContract.js"]:::frontend
        Lib2["sbtTokenContract.js"]:::frontend
        Types["types.ts"]:::frontend
        Utils["utils.ts"]:::frontend

        FrontendApp --> Layout
        FrontendApp --> Providers
        FrontendApp --> HomePage
        FrontendApp --> FundList
        FrontendApp --> FundDetail
        FrontendApp --> PFUI
        FrontendApp --> UILib
        FrontendApp --> Hook1
        FrontendApp --> Hook2
        FrontendApp --> Hook3
        FrontendApp --> Hook4
        FrontendApp --> Lib1
        FrontendApp --> Lib2
        FrontendApp --> Types
        FrontendApp --> Utils
    end

    %% Backend Layer
    subgraph "Backend (Django API)"
        APIs["APIs App"]:::backend
        Urls["urls.py"]:::backend
        Models["models.py"]:::backend
        Views["views.py (/analyze/)"]:::backend
        UtilsBE["utils.py (AI pipeline)"]:::backend
        Settings["settings.py"]:::backend
        Middleware["memory_middleware.py"]:::backend
        Manage["manage.py"]:::backend
        ASGI["asgi.py"]:::backend
        WSGI["wsgi.py"]:::backend

        APIs --> Urls
        APIs --> Models
        APIs --> Views
        APIs --> UtilsBE
        Settings --> Middleware
        Manage --> ASGI
        Manage --> WSGI
    end

    %% Smart Contracts Layer
    subgraph "Smart Contracts (Hardhat)"
        Contracts["contracts/"]:::contracts
        HHConf["hardhat.config.js"]:::contracts
        Deploy["scripts/deploy.js"]:::contracts
        Tests["test/PublicFundTreasury.js"]:::contracts

        Contracts --> HHConf
        Contracts --> Deploy
        Contracts --> Tests
    end

    %% Blockchain & Storage
    subgraph "Blockchain & Storage"
        Ethereum["Ethereum Network"]:::chain
        IPFS["IPFS Storage"]:::chain
        FAISS["FAISS Vector Store"]:::db
        Groq["GROQ API / LLM"]:::external
    end

    %% Interactions
    Browser -->|"loads app"| FrontendApp
    FrontendApp -->|"calls contract"| Lib1
    FrontendApp -->|"calls contract"| Lib2
    FrontendApp -->|"POST /analyze"| Views
    FrontendApp -->|"upload report"| IPFS
    Views -->|"process report"| UtilsBE
    UtilsBE -->|"store/query vectors"| FAISS
    UtilsBE -->|"LLM query"| Groq
    Views -->|"return analysis"| FrontendApp
    Views -->|"store CID"| IPFS
    Lib1 -->|"transactions/events"| Ethereum
    Lib2 -->|"transactions/events"| Ethereum
    Deploy --> Ethereum
    Contracts --> Ethereum
    Tests --> Ethereum
    Ethereum -->|"events"| FrontendApp

    %% Click Events
    click FrontendApp "https://github.com/sagarshivalingappaathani/public-fund-management/tree/main/frontend/app"
    click Layout "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/app/layout.tsx"
    click Providers "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/app/providers.tsx"
    click HomePage "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/app/dashboard/home/page.tsx"
    click FundList "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/app/dashboard/fund-mangement/page.tsx"
    click FundDetail "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/app/dashboard/fund-mangement/[id]/page.tsx"
    click PFUI "https://github.com/sagarshivalingappaathani/public-fund-management/tree/main/frontend/components/PublicFundManagement"
    click UILib "https://github.com/sagarshivalingappaathani/public-fund-management/tree/main/frontend/components/ui"
    click Hook1 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/hooks/useWallet.ts"
    click Hook2 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/hooks/useContractData.ts"
    click Hook3 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/hooks/useProposals.ts"
    click Hook4 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/hooks/use-toast.ts"
    click Lib1 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/lib/publicFundingContract.js"
    click Lib2 "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/lib/sbtTokenContract.js"
    click Types "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/lib/types.ts"
    click Utils "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/frontend/lib/utils.ts"
    click APIs "https://github.com/sagarshivalingappaathani/public-fund-management/tree/main/backend/APIs"
    click Urls "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/APIs/urls.py"
    click Models "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/APIs/models.py"
    click Views "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/APIs/views.py"
    click UtilsBE "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/APIs/utils.py"
    click Settings "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/backend/settings.py"
    click Middleware "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/backend/memory_middleware.py"
    click Manage "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/manage.py"
    click ASGI "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/backend/asgi.py"
    click WSGI "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/backend/backend/wsgi.py"
    click Contracts "https://github.com/sagarshivalingappaathani/public-fund-management/tree/main/smart-contracts/contracts"
    click HHConf "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/smart-contracts/hardhat.config.js"
    click Deploy "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/smart-contracts/scripts/deploy.js"
    click Tests "https://github.com/sagarshivalingappaathani/public-fund-management/blob/main/smart-contracts/test/PublicFundTreasury.js"

    %% Styles
    classDef client fill:#B3E5FC,stroke:#0288D1,color:#000;
    classDef frontend fill:#BBDEFB,stroke:#1976D2,color:#000;
    classDef backend fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef contracts fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef chain fill:#E0E0E0,stroke:#616161,color:#000;
    classDef db fill:#FFE0B2,stroke:#F57C00,color:#000;
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
