# zs0c131y/trustvault architecture

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

- Interactive diagram: https://gitdiagram.com/zs0c131y/trustvault
- Repository: https://github.com/zs0c131y/trustvault

## Overview

##### Project Type and Purpose
- TrustVault is a hybrid full-stack system that combines blockchain smart contracts with a traditional RESTful backend and web-based frontend.
- The focus is on property registration/ownership transfers and document verification, integrating Ethereum smart contracts (PropertyRegistry.sol and DocumentVerification.sol) along with IPFS for decentralized file storage.
- Security is a paramount design aspect with JWT authentication, input sanitization, CSRF protections, and HTTP security headers.

##### Main Components
a. Frontend:
– Represented by the public directory with HTML, CSS, and JavaScript files.
– Includes pages for property registration, document verification, government dashboards, and user management.
– Uses Web3.js to interact with the blockchain and Firebase for authentication.

b. Backend API Server:
– Built in Node.js/Express (entry point: server.js) that handles RESTful API requests.
– Uses middleware (e.g., authProtection, csrfProtection, etc.) and models (MongoDB models in the models folder).
– Manages business logic, file uploads, and integration with the blockchain.

c. Blockchain & Smart Contracts:
– Two contracts (PropertyRegistry.sol and DocumentVerification.sol) compiled by Hardhat.
– Deployment artifacts and configuration files reside in the artifacts, contracts, and deployments directories.
– The backend and frontend interact with these contracts via Web3.js.

d. Database:
– A MongoDB database is used for storing user details, transaction records, logs, etc.
– Represented by models in the project.

e. Services and Utilities:
– Services like BlockchainSync.js, IPFSService.js, and IPFSVerificationService.js indicate background processes managing blockchain state syncing and IPFS integration.
– Utility functions for logging and error handling as found in the utils folder.

##### Architectural Relationships and Data Flow
– Users interact with the frontend (client-side HTML/JS) which makes REST API calls to the backend server.
– The backend processes these requests, validates access via middleware, and interacts with both MongoDB (for data storage) and the Ethereum network (invoking smart contracts) using Web3.js.
– Smart contracts are deployed on the Ethereum blockchain (local development with Hardhat) for secure verification and registry operations.
– IPFS is integrated for decentralized file storage of document content, where file hashes are stored on-chain for verification.
– External authentication services (e.g., Firebase Authentication) might be used to manage user sessions.

##### Architectural Patterns & Design Principles
– Layered Architecture: Separates concerns between presentation (frontend), business logic (backend), and data storage (MongoDB and blockchain).
– Microservices-like Separation: Even though it is a monolithic repository, distinct directories for middleware, services, and models reflect separation of concerns.
– Blockchain Integration: Hybrid approach keeping off-chain data in a database while maintaining security-critical data on-chain.
– Security-Oriented Design: Emphasis on JWT-based authentication, rate limiting, and middleware for validating inputs and protecting against CSRF/XSS.

##### Putting It All Together
Layer 1 – User Interface (Frontend: HTML/JS/CSS).
Layer 2 – API Gateway (Express server with middleware).
Layer 3 – Data Management (MongoDB database and file storage via IPFS).
Layer 4 – Verification & Integrity Layer (Ethereum smart contracts on the blockchain).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["Frontend Client"]:::ui
        Firebase["Firebase Authentication"]:::external
    end

    %% API Gateway Layer
    subgraph "API Gateway"
        API["Express API Server"]:::api
        Middleware["Middleware (Auth/CSRF)"]:::api
        Models["Data Models"]:::api
    end

    %% Data Management Layer
    subgraph "Data Management"
        DB["MongoDB Database"]:::db
    end

    %% Blockchain & Decentralized Storage Layer
    subgraph "Blockchain & Decentralized Storage"
        BC["Ethereum Smart Contracts"]:::blockchain
        IPFS["IPFS Node"]:::blockchain
    end

    %% Background Services Layer
    subgraph "Background Services"
        BCSync["BlockchainSync Service"]:::service
        IPFSService["IPFS Service"]:::service
        IPFSVerif["IPFS Verification Service"]:::service
        Logger["Logger Utility"]:::service
        LogHelper["Logging Helper"]:::service
    end

    %% Deployment Scripts Layer
    subgraph "Deployment Scripts"
        Deploy["Deploy Script"]:::deploy
        Restore["Blockchain Restore Script"]:::deploy
        Verify["Document Verification Script"]:::deploy
    end

    %% Relationships between layers
    UI -->|"API-request"| API
    UI -->|"auth"| Firebase

    API -->|"use"| Middleware
    API -->|"access"| Models
    API -->|"store/retrieve"| DB
    API -->|"invoke"| BC
    API -->|"document upload"| IPFS

    BCSync -->|"sync"| BC
    IPFSService -->|"transfer"| IPFS
    IPFSVerif -->|"verify"| IPFS

    Deploy -->|"deploy"| BC
    Restore -->|"restore"| BC
    Verify -->|"verify-doc"| IPFS

    %% Styles
    classDef ui fill:#fff8dc,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef db fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef blockchain fill:#ffe6f2,stroke:#333,stroke-width:2px;
    classDef service fill:#e6ffe6,stroke:#333,stroke-width:2px;
    classDef deploy fill:#ffd6d6,stroke:#333,stroke-width:2px;
    classDef external fill:#f3e6ff,stroke:#333,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/zs0c131y/trustvault/tree/main/public"
    click API "https://github.com/zs0c131y/trustvault/blob/main/server.js"
    click Middleware "https://github.com/zs0c131y/trustvault/tree/main/middleware"
    click Models "https://github.com/zs0c131y/trustvault/tree/main/models"
    click DB "https://github.com/zs0c131y/trustvault/blob/main/models/Property.js"
    click BC "https://github.com/zs0c131y/trustvault/tree/main/contracts"
    click IPFS "https://github.com/zs0c131y/trustvault/tree/main/public/contracts"
    click BCSync "https://github.com/zs0c131y/trustvault/blob/main/services/BlockchainSync.js"
    click IPFSService "https://github.com/zs0c131y/trustvault/blob/main/services/IPFSService.js"
    click IPFSVerif "https://github.com/zs0c131y/trustvault/blob/main/services/IPFSVerificationService.js"
    click Logger "https://github.com/zs0c131y/trustvault/blob/main/utils/logger.js"
    click LogHelper "https://github.com/zs0c131y/trustvault/blob/main/utils/loggingHelper.js"
    click Deploy "https://github.com/zs0c131y/trustvault/blob/main/scripts/deploy.js"
    click Restore "https://github.com/zs0c131y/trustvault/blob/main/scripts/restore-blockchain.js"
    click Verify "https://github.com/zs0c131y/trustvault/blob/main/scripts/verifyDocument.js"
```
