# roysubhrajit113/green-pulse-web-app architecture

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

- Interactive diagram: https://gitdiagram.com/roysubhrajit113/green-pulse-web-app
- Repository: https://github.com/roysubhrajit113/green-pulse-web-app

## Overview

##### Overview of Project Type and Purpose
- Green Pulse is a full-stack energy management platform that combines:
- A Node.js/Express backend exposing a REST API
- A React-based frontend dashboard for data visualization
- A Python/Flask chatbot microservice integrated with Google Gemini AI
- A blockchain layer (Solidity smart contracts, Hardhat, Ethers.js) for energy trading and carbon credits
- MongoDB as the primary data store
- Key use-cases:
- Monitoring carbon footprint and energy consumption
- Tokenized energy trading on-chain
- Gamified dashboard for administrators
- AI-powered user assistance via chatbot

##### Analyzing File Structure to Identify Components
- Top-level directories:
- backend/ (Express API, controllers, models, services, config, middleware)
- frontend/ (React app, components, contexts, services, assets)
- chatbot/ (Flask service, AI integration)
- contracts/ (Solidity smart contracts, tests, Hardhat config)
- deploy/ & docker-compose.yml (container orchestration)
- Cross-cutting concerns:
- config files and environment variables (.env)
- build/deploy scripts (scripts/, backend/scripts/, Hardhat scripts)
- tests (backend test scripts, contracts tests)

##### Main Components and Their Interactions
- Frontend (React)
- Hosts UI at http://localhost:3000
- Uses Axios (apiClient.js) to call backend endpoints (/auth, /buildings, /carbonData, /wallet, etc.)
- Renders charts (ApexCharts), forms, menus, and Chatbot widget
- Auth flow via JWT tokens stored in context
- Backend (Node.js/Express + MongoDB)
- Listens on port 5000
- MVC structure:
– Models: Mongoose schemas (User, Building, CarbonData, EnergyConsumption, etc.)
– Controllers: request handlers (authController, carbonDataController, alertController, etc.)
– Services: business logic, blockchainService (Ethers.js), alertService
– Routes: mount REST endpoints
– Middleware: auth, instituteAuth, validation
- Interacts with:
– MongoDB (backend/config/database.js)
– Ethereum network via blockchainService (backend/services/blockchainService.js)
- Chatbot Service (Python/Flask)
- Runs on port 5001
- Exposes REST endpoint for chat requests
- Communicates with Google Gemini AI using GEMINI_API_KEY
- Invoked by frontend Chatbot component (chatbotService.js)
- Blockchain Layer
- Hardhat network for local chain
- Solidity contracts under contracts/ (control, market, lib, test)
- Deploy scripts in scripts/ (deploy.js, trade.js, governance.js, etc.)
- Interaction via Ethers.js in backend and frontend blockchainService modules
- Database
- MongoDB cluster or local instance
- Stores user profiles, institute metadata, carbon metrics, energy transactions

##### Relationships and Data Flow
1. User ↔ React Frontend
– Login/Signup → calls /auth routes on backend
– Dashboard data fetch → GET /carbonData, /buildings, /meterData
– Blockchain transactions → POST /wallet (calls blockchainService → Ethereum)
– Chat queries → POST to Flask chatbot service → Gemini AI
2. Frontend ↔ Backend
– RESTful calls with JWT in header
– Real-time alerts via polling or websockets (if implemented)
3. Backend ↔ MongoDB
– CRUD operations through Mongoose models
4. Backend ↔ Ethereum network
– Smart contract calls (minting, trading carbon credits) via Ethers.js
5. Deployment
– Docker-Compose orchestrates services: backend, frontend, chatbot, MongoDB, Hardhat node

##### Architectural Patterns and Principles
- Layered architecture in backend (routes → controllers → services → models)
- Separation of concerns:
- Frontend presentation vs. backend API vs. blockchain logic vs. AI microservice
- Modularization:
- Smart contracts isolated under contracts/ and tested via Hardhat
- Chatbot as a standalone microservice
- Stateless REST API with JWT for authentication
- Context-based state management in React (AuthContext, CarbonContext, etc.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Compose"
        direction TB
        FE["React Frontend\n(port 3000)"]:::ui
        BE["Express API\n(port 5000)"]:::api
        CB["Flask Chatbot\n(port 5001)"]:::api
        MDB["MongoDB"]:::db
        HN["Hardhat Node\n(Local Ethereum)"]:::blockchain
    end

    subgraph "Blockchain Layer"
        direction TB
        CT["Solidity Contracts"]:::blockchain
    end

    Google["Google Gemini AI"]:::external

    FE -->|REST /auth, /carbonData, /wallet| BE
    FE -->|Chat requests| CB
    BE -->|CRUD operations| MDB
    BE -->|Ethers.js calls| HN
    HN -->|Deploy & interact| CT
    CB -->|API calls| Google

    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/tree/main/frontend/src"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/App.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/routes.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/index.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/tree/main/frontend/src/components"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/contexts/AuthContext.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/services/apiClient.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/services/blockchainService.js"
    click FE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/frontend/src/services/chatbotService.js"

    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/server.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/config/database.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/routes/auth.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/controllers/authController.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/services/blockchainService.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/models/User.js"
    click BE "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/backend/middleware/auth.js"

    click CB "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/chatbot/main.py"
    click CT "https://github.com/roysubhrajit113/green-pulse-web-app/tree/main/contracts"
    click HN "https://github.com/roysubhrajit113/green-pulse-web-app/blob/main/hardhat.config.js"

    classDef ui fill:#ADD8E6,stroke:#0366d6,color:#000
    classDef api fill:#98FB98,stroke:#228B22,color:#000
    classDef db fill:#FFA500,stroke:#FF8C00,color:#000
    classDef blockchain fill:#DDA0DD,stroke:#800080,color:#000
    classDef external fill:#D3D3D3,stroke:#696969,color:#000
```
