# krish-depani/decentralized-voting-system architecture

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

- Interactive diagram: https://gitdiagram.com/krish-depani/decentralized-voting-system
- Repository: https://github.com/krish-depani/decentralized-voting-system

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized voting dApp.
- Purpose: Provide a secure, transparent voting process by combining a web frontend, a Node.js server, a blockchain layer (Ethereum contracts), a Python microservice for authentication, and a MySQL database.

##### File Structure
– Top-level “index.js” (Node.js web server serving static assets & possibly proxying API calls)
– “src/” (static frontend: HTML, CSS, JS bundled via Browserify)
– “contracts/”, “migrations/”, “truffle-config.js” (smart contract source + deployment scripts)
– “Database_API/main.py” (FastAPI microservice for JWT-based auth against MySQL)
– “public/” (images, screenshots)
– Configuration: “.env” files for DB & blockchain endpoints

##### README for Technical Stack
– Frontend: HTML/CSS/JS, Browserify
– Backend #1: Node.js (serves UI, orchestrates contract interactions)
– Backend #2: FastAPI (Python) for authentication & JWT, talking to MySQL
– Blockchain: Ethereum (Ganache local network), Truffle for compile/migrate, Web3.js & MetaMask
– Database: MySQL on port 3306

##### Main Components & Relationships
a. Frontend (Client Browser)
- HTML/CSS/JS bundles (login, admin, voter pages)
- MetaMask extension injects Web3 provider
- Interacts via HTTP(S) to Node.js server for static assets & any REST endpoints
- Interacts via Web3 calls to Ethereum network for voting transactions
b. Node.js Server (index.js)
- Serves frontend assets on port 8080
- May proxy or forward authentication requests to FastAPI
- Hosts any server-side logic (e.g., serve API keys, config)
c. Database API Service (FastAPI)
- Exposes REST endpoints for login/auth
- Validates credentials against MySQL, issues JWT tokens
d. MySQL Database
- Stores voter records (voter_id, role, password hash)
e. Ethereum Blockchain (Ganache local)
- Runs a local Ethereum node
- Hosts deployed Voting.sol contracts
- Listens on RPC (http://localhost:7545)
f. Truffle Suite
- Manages contract compilation & migrations
- Configuration via truffle-config.js

##### Architectural Patterns & Design Principles
– Microservices: Node.js web server separated from FastAPI auth service
– Decentralized layer: Client-side Web3 interactions with smart contracts
– Stateless JWT auth between client & DB API
– Clear separation of concerns: UI vs. business logic vs. data layer vs. blockchain layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Client Browser)"
        direction TB
        HTML["src/html/"]:::frontend
        CSS["src/css/"]:::frontend
        JS["src/js/"]:::frontend
        Assets["src/assets/"]:::frontend
    end

    %% Node.js Server Layer
    subgraph "Node.js Server (Web UI & Orchestration)"
        direction TB
        Index["index.js"]:::backend
        Package["package.json"]:::backend
        Lock["package-lock.json"]:::backend
        EnvNode[".env"]:::backend
        GitNode[".gitignore"]:::backend
    end

    %% Authentication Service Layer
    subgraph "FastAPI Auth Service (Python + JWT)"
        direction TB
        MainPy["Database_API/main.py"]:::backend
        EnvAPI["Database_API/.env"]:::backend
        GitAPI["Database_API/.gitignore"]:::backend
    end

    %% Data Store
    DB["MySQL Database<br/>(port 3306)"]:::data

    %% Blockchain & Contracts
    subgraph "Smart Contract Layer"
        direction TB
        ContractsDir["contracts/"]:::blockchain
        DeployScript["contracts/2_deploy_contracts.js"]:::blockchain
        MigrationsDir["migrations/"]:::blockchain
        MigrationScript["migrations/1_initial_migration.js"]:::blockchain
        TruffleConf["truffle-config.js"]:::blockchain
    end

    Blockchain["Ethereum Ganache Node<br/>(RPC 7545)"]:::blockchain

    %% Public Assets
    Public["public/"]:::frontend

    %% Connections
    HTML -->|"GET /static"| Index
    Public --> Index
    HTML -->|"POST /login"| MainPy
    MainPy -->|"SQL query"| DB
    HTML -->|"eth_sendTransaction / eth_call"| Blockchain
    TruffleConf -->|"deploy & migrate contracts"| Blockchain

    %% Click Events
    click HTML "https://github.com/krish-depani/decentralized-voting-system/tree/main/src/html/"
    click CSS "https://github.com/krish-depani/decentralized-voting-system/tree/main/src/css/"
    click JS "https://github.com/krish-depani/decentralized-voting-system/tree/main/src/js/"
    click Assets "https://github.com/krish-depani/decentralized-voting-system/tree/main/src/assets/"
    click Index "https://github.com/krish-depani/decentralized-voting-system/blob/main/index.js"
    click Package "https://github.com/krish-depani/decentralized-voting-system/blob/main/package.json"
    click Lock "https://github.com/krish-depani/decentralized-voting-system/blob/main/package-lock.json"
    click EnvNode "https://github.com/krish-depani/decentralized-voting-system/blob/main/.env"
    click GitNode "https://github.com/krish-depani/decentralized-voting-system/blob/main/.gitignore"
    click MainPy "https://github.com/krish-depani/decentralized-voting-system/blob/main/Database_API/main.py"
    click EnvAPI "https://github.com/krish-depani/decentralized-voting-system/blob/main/Database_API/.env"
    click GitAPI "https://github.com/krish-depani/decentralized-voting-system/blob/main/Database_API/.gitignore"
    click ContractsDir "https://github.com/krish-depani/decentralized-voting-system/tree/main/contracts/"
    click DeployScript "https://github.com/krish-depani/decentralized-voting-system/blob/main/contracts/2_deploy_contracts.js"
    click MigrationsDir "https://github.com/krish-depani/decentralized-voting-system/tree/main/migrations/"
    click MigrationScript "https://github.com/krish-depani/decentralized-voting-system/blob/main/migrations/1_initial_migration.js"
    click TruffleConf "https://github.com/krish-depani/decentralized-voting-system/blob/main/truffle-config.js"
    click Public "https://github.com/krish-depani/decentralized-voting-system/tree/main/public/"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#3498DB,color:#1B4F72;
    classDef backend fill:#D5F5E3,stroke:#27AE60,color:#186A3B;
    classDef data fill:#FCF3CF,stroke:#F1C40F,color:#B9770E;
    classDef blockchain fill:#F5EEF8,stroke:#8E44AD,color:#512E5F;
```
