# swayam-2003/blockchain-certificate-system architecture

> Architecture diagram of the GitHub repository swayam-2003/blockchain-certificate-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swayam-2003/blockchain-certificate-system
- Repository: https://github.com/swayam-2003/blockchain-certificate-system

## Overview

##### Project Type and Purpose
- This is a full-stack decentralized web application (“Blockchain Certificate System”) that enables educational institutions to issue, store, and verify tamper-proof certificates on Ethereum, with metadata stored on IPFS, authentication via Firebase, and a responsive static frontend.

##### File Structure
- Top-level folders:
- contracts/ & migrations/: Truffle smart contract (CertificateRegistry.sol) + deploy scripts
- public/: Static web UI (HTML pages, CSS, client-side JS)
- src/: Node.js/Express backend
– config/: env & Firebase setup
– controllers/: HTTP request handlers
– middleware/: Express auth guard (Firebase-based)
– routes/: REST API endpoints (/api/certificates/…)
– services/: business logic for IPFS, Pinata, Web3 interactions
– index.js & app.js: server bootstrap and router wiring
- templates/: HTML template(s) for server-rendered views
- truffle-config.js: blockchain network config

##### README for Insights
- Core components:
- Frontend: static HTML/CSS/JS + Bootstrap + MetaMask integration
- Backend: Node/Express REST API
- Blockchain: Ethereum contracts via Web3.js & Truffle (deployed on Ganache in dev)
- Storage: IPFS (Pinata) for certificate metadata
- Auth & DB: Firebase Authentication + Firestore for user roles and metadata indexing

##### Main Components
a. Frontend (browser):
- Static assets (public/pages/*.html, auth.js)
- MetaMask plugin for signing blockchain transactions
- Consumes Express REST API & directly interacts with smart contract via Web3.js (optional)
b. Express Backend (Node.js):
- Routes → Controllers → Services
- Middleware for Firebase authentication & role checks
- Services:
- web3Service: calls smart contract methods on Ethereum
- ipfsService / pinataService: uploads certificate metadata to IPFS/Pinata
- (Optional) Firestore client for quick lookup of certificate events
c. Ethereum Blockchain:
- CertificateRegistry.sol contract
- Ganache (development) or public test/mainnet
d. IPFS Network:
- Pinata gateway for persistently pinning JSON metadata
e. Firebase:
- Firebase Auth: user login & issuer role enforcement
- Firestore: stores user-certificate indexing, maybe USN uniqueness
f. External Tools:
- MetaMask (user wallet)
- Ganache Desktop (local Ethereum node)

##### Relationships and Data Flow
- User → Frontend → (1) REST API calls to Express backend or (2) direct Web3 calls via MetaMask
- Backend:
- Verifies Firebase JWT via auth middleware
- Calls IPFS/Pinata to store certificate JSON; receives CID
- Calls smart contract (web3Service) to mint/store certificate on Ethereum, passing CID + USN + metadata
- Optionally logs metadata in Firestore for search/recent endpoints
- Frontend:
- Displays certificate issuance/validation UI
- Fetches certificate details via REST (which may read contract via web3Service or Firestore)
- Smart Contract:
- Emits events (CertificateIssued, Revoked)
- Provides view functions for validation

##### Architectural Patterns & Principles
- Layered Architecture: Presentation (static UI), API Layer (Express), Service Layer (business logic), Data Layer (Ethereum + IPFS + Firestore)
- Separation of Concerns:
- Auth (Firebase middleware)
- Storage (IPFS vs Firestore vs blockchain)
- Contract interaction (web3Service)
- Event-Driven: Smart contract emits events that backend (or another service) could consume for indexing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Browser)" 
        direction TB
        UIStatic["Static UI\n(public/)"]:::frontend
        LandingPage["Landing Page\n(public/pages/landing.html)"]:::frontend
        AuthPage["Auth Page\n(public/pages/auth.html)"]:::frontend
        DashboardPage["Dashboard Page\n(public/pages/dashboard.html)"]:::frontend
        Styles["CSS Styles\n(public/css/styles.css)"]:::frontend
        AuthScript["Auth Script\n(public/js/auth.js)"]:::frontend
        MetaMask["MetaMask\n(User Wallet)"]:::external
    end

    %% Backend Layer
    subgraph "Backend (Node.js/Express)" 
        direction TB
        Index["Server Bootstrap\n(src/index.js)"]:::backend
        App["App Config & Middleware\n(src/app.js)"]:::backend
        subgraph "Configuration"
            direction TB
            EnvConfig["Env & Firebase Config\n(src/config/config.js)"]:::backend
            FirebaseConfig["Firebase Init\n(src/config/firebase.js)"]:::backend
        end
        subgraph "Routing & Middleware"
            direction TB
            Routes["Certificate Routes\n(src/routes/certificateRoutes.js)"]:::backend
            AuthMiddleware["Firebase Auth Middleware\n(src/middleware/auth.js)"]:::backend
            Controller["Certificate Controller\n(src/controllers/certificateController.js)"]:::backend
        end
        subgraph "Services (Business Logic)"
            direction TB
            IPFS["IPFS Service\n(src/services/ipfsService.js)"]:::service
            Pinata["Pinata Service\n(src/services/pinataService.js)"]:::service
            Web3Svc["Web3 Service\n(src/services/web3Service.js)"]:::service
        end
    end

    %% On-Chain Layer
    subgraph "Blockchain (Ethereum)" 
        direction TB
        ContractDir["Smart Contracts\n(contracts/)"]:::blockchain
        Contract["CertificateRegistry.sol"]:::blockchain
        Migrations["Deploy Scripts\n(migrations/1_deploy_contracts.js)"]:::blockchain
        TruffleCfg["Network Config\n(truffle-config.js)"]:::blockchain
        Ganache["Ganache Node"]:::external
    end

    %% Storage & Auth
    subgraph "Off-Chain Storage & Auth"
        direction TB
        IPFSNet["IPFS Network"]:::external
        PinataGW["Pinata Gateway"]:::external
        FirebaseAuth["Firebase Auth"]:::auth
        Firestore["Firestore DB"]:::auth
        Templates["View Templates\n(templates/index.html)"]:::backend
    end

    %% Misc
    GitIgnore[".gitignore"]:::misc
    Readme["README.md"]:::misc

    %% Relationships
    UIStatic -->|loads| LandingPage
    UIStatic -->|loads| AuthPage
    UIStatic -->|loads| DashboardPage
    UIStatic -->|uses| Styles
    AuthPage -->|executes| AuthScript
    DashboardPage -->|executes| AuthScript

    LandingPage -->|calls REST API| App
    AuthPage -->|calls REST API| App
    DashboardPage -->|calls REST API| App
    LandingPage -->|web3.eth.send| MetaMask
    DashboardPage -->|web3.eth.call| MetaMask

    App -->|uses| EnvConfig
    App -->|uses| FirebaseConfig
    App -->|registers routes| Routes
    Routes -->|guards| AuthMiddleware
    Routes -->|forwards| Controller
    Controller -->|calls| IPFS
    Controller -->|calls| Pinata
    Controller -->|calls| Web3Svc
    Controller -->|writes index| Firestore

    IPFS -->|pinJSONToIPFS| PinataGW
    Web3Svc -->|eth.sendTransaction| Contract
    Contract -->|emit events| Ganache
    Contract -->|read/write| TruffleCfg
    ContractDir --> Contract

    %% External flows
    MetaMask -->|transact| Ganache
    Controller -->|verify JWT| FirebaseAuth

    %% Click Events
    click UIStatic "https://github.com/swayam-2003/blockchain-certificate-system/tree/main/public/"
    click LandingPage "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/public/pages/landing.html"
    click AuthPage "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/public/pages/auth.html"
    click DashboardPage "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/public/pages/dashboard.html"
    click Styles "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/public/css/styles.css"
    click AuthScript "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/public/js/auth.js"
    click ContractDir "https://github.com/swayam-2003/blockchain-certificate-system/tree/main/contracts/"
    click Migrations "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/migrations/1_deploy_contracts.js"
    click TruffleCfg "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/truffle-config.js"
    click Index "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/index.js"
    click App "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/app.js"
    click EnvConfig "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/config/config.js"
    click FirebaseConfig "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/config/firebase.js"
    click Routes "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/routes/certificateRoutes.js"
    click Controller "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/controllers/certificateController.js"
    click AuthMiddleware "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/middleware/auth.js"
    click IPFS "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/services/ipfsService.js"
    click Pinata "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/services/pinataService.js"
    click Web3Svc "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/src/services/web3Service.js"
    click Templates "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/templates/index.html"
    click GitIgnore "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/.gitignore"
    click Readme "https://github.com/swayam-2003/blockchain-certificate-system/blob/main/README.md"

    %% Styles
    classDef frontend fill:#CEF,stroke:#09F,stroke-width:1px
    classDef backend fill:#CF9,stroke:#393,stroke-width:1px
    classDef service fill:#FC9,stroke:#E65,stroke-width:1px
    classDef blockchain fill:#FCA,stroke:#F85,stroke-width:1px
    classDef auth fill:#F99,stroke:#900,stroke-width:1px
    classDef external fill:#DDD,stroke:#999,stroke-width:1px,stroke-dasharray: 5 5
    classDef misc fill:#EEE,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
