# gdsc-zhcet/voltsense architecture

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

- Interactive diagram: https://gitdiagram.com/gdsc-zhcet/voltsense
- Repository: https://github.com/gdsc-zhcet/voltsense

## Overview

##### Project Type and Purpose
- VoltSense is an AI-powered IoT smart energy monitoring system. It combines hardware (sensors, relay modules, IoT smart switches), a web dashboard (client side built on Next.js), and an API backend (built in Node.js/Express), alongside integrations with Firebase (Authentication, Cloud Messaging, Firestore) and Google Cloud services (Cloud Run for deployment, Vertex AI for anomaly detection).
- The README emphasizes both real-time monitoring via WebSockets and anomaly detection with Vertex AI, while also underlining secure access and push notifications. This indicates a full-stack, containerized, cloud-native application with IoT connectivity.

##### Analyzing the File Structure
- Top-level directories include “client” and “server” which clearly separate the frontend and backend concerns.
- The “server” directory contains the backend files (e.g., app.js, firebaseAdmin.js, vertexAI.js) that likely initialize the Express server, manage Firebase integrations, and interact with Vertex AI. It includes Docker configuration files to containerize the backend.
- Additional configuration files and CI/CD workflow scripts (in .github/workflows and cloudbuild.yaml) show that deployment automation and cloud container orchestration (Google Cloud Run) are key parts of the system’s lifecycle.

##### Main Components
a. Hardware/IoT Devices:
- IoT smart switches and sensors (e.g., ZMPT101B, ACS712, Songle Relay) to capture real-time energy usage and voltage/current data.
b. Frontend (Web Dashboard & Mobile App):
- Next.js app with interactive graphs, authentication UI, and real-time data visualization.
- Integration with third-party libraries (Tailwind CSS, Chart.js) for styling and analytics.
c. Backend (API Server):
- Node.js/Express.js server managing API endpoints.
- Real-time data channels possibly based on WebSockets.
- Business logic for processing IoT data and interfacing with AI services.
d. External Services and Integrations:
- Firebase (Authentication, FCM, Firestore, Firebase Storage)
- Vertex AI for anomaly detection via the Gemini API.
- Deployment on Google Cloud Run using Docker.
e. CI/CD and Deployment:
- GitHub Workflows for automated deployment pipelines.
- Containerization via Dockerfiles in both “client” and “server”.

##### Relationships and Interactions
- The backend processes this data, possibly triggering Vertex AI analytics for anomaly detection; applications of these alerts then propagate as notifications via Firebase Cloud Messaging.
- The frontend interacts with the backend for real-time updates (via WebSockets) and also directly uses Firebase Authentication for user management.
- The CI/CD pipelines manage building Docker images for both client and server, which are then deployed on Google Cloud Run.

##### Architectural Patterns & Design Principles
- Separation of concerns: Clear division between frontend and backend logic.
- Containerized deployment: Utilize Docker configuration files which imply a focus on containerization and cloud-native deployments.
- Real-time data handling: Use of WebSockets implies an event-driven architecture.
- Integration of multiple external APIs/services: Notably Firebase and Vertex AI.
- Scalability: Deployment on Google Cloud Run suggests horizontal scaling considerations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "IoT Hardware"
        IOT["IoT Devices\n(Sensors,Smart Switches)"]:::hardware
    end

    subgraph "Backend"
        API["API Server\n(Node.js,Express)"]:::backend
        FBAdmin["Firebase Admin"]:::backend
        Vertex["Vertex AI Integration"]:::backend
    end

    subgraph "Frontend"
        WS["Web Dashboard\n(Next.js,Tailwind,Chart.js)"]:::frontend
        FBClient["Firebase Client"]:::frontend
    end

    subgraph "External Services"
        FirebaseExt["Firebase Services\n(Auth,FCM,Firestore)"]:::external
        VertexExt["Vertex AI\n(AnomalyDetection)"]:::external
    end

    subgraph "Deployment"
        CIPipeline["CI/CD Pipeline\n(GitHubWorkflows,CloudBuild)"]:::deployment
        DockerClient["Client Dockerfile"]:::deployment
        DockerServer["Server Dockerfile"]:::deployment
        CloudRun["Google Cloud Run Deployment"]:::deployment
    end

    IOT -->|"sends_data"| API
    API -->|"uses"| FBAdmin
    FBAdmin -->|"integrates"| FirebaseExt
    API -->|"calls"| Vertex
    Vertex -->|"processes"| VertexExt
    WS <-->|"realTime_comm"| API
    WS -->|"auth_calls"| FBClient
    FBClient -->|"connects"| FirebaseExt
    CIPipeline -->|"builds"| DockerClient
    CIPipeline -->|"builds"| DockerServer
    DockerClient -->|"deploys_to"| CloudRun
    DockerServer -->|"deploys_to"| CloudRun
    CloudRun -->|"hosts"| API
    CloudRun -->|"hosts"| WS

    click WS "https://github.com/gdsc-zhcet/voltsense/tree/master/client/"
    click API "https://github.com/gdsc-zhcet/voltsense/tree/master/server/"
    click FBAdmin "https://github.com/gdsc-zhcet/voltsense/blob/master/server/src/firebaseAdmin.js"
    click Vertex "https://github.com/gdsc-zhcet/voltsense/blob/master/server/src/vertexAI.js"
    click FBClient "https://github.com/gdsc-zhcet/voltsense/blob/master/client/src/lib/firebaseConfig.ts"
    click DockerClient "https://github.com/gdsc-zhcet/voltsense/tree/master/client/Dockerfile"
    click DockerServer "https://github.com/gdsc-zhcet/voltsense/tree/master/server/Dockerfile"
    click CIPipeline "https://github.com/gdsc-zhcet/voltsense/blob/master/.github/workflows/deploy.yml"

    classDef frontend fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef backend fill:#C7F6AD,stroke:#000,stroke-width:2px;
    classDef hardware fill:#FFF4C2,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef deployment fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
