# easonchai/proof-of-interaction architecture

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

- Interactive diagram: https://gitdiagram.com/easonchai/proof-of-interaction
- Repository: https://github.com/easonchai/proof-of-interaction

## Overview

##### Project Type and Purpose
- This repository is a full-stack blockchain-integrated project with three core segments: a Frontend (built using Next.js and React), a Backend (using NestJS with modules for oracles, validation, and Prisma for database access), and a Smart Contracts suite managed via Hardhat.
- As explained in the README, the solution implements “Proof of Interaction” where off-chain interactions are signed, stored on-chain, and then verified via oracle mechanisms. It targets use cases like event participation, rewards, and trustless verification.

##### High-Level Architecture Components
- Frontend:
- Built with Next.js (evidenced by next.config.js, React components in the src directory, and Tailwind CSS configuration).
- Provides interactive user interfaces (pages, modals, components) that allow users to sign transactions and view real time data.
- Handles API calls (e.g., from files in src/apis, axios utilities) to interact with the backend.
- Backend:
- A Node.js service using NestJS (as seen in files like app.module.ts, main.ts, and multiple module directories including oracle and validation).
- Integrates with a database via Prisma (with schema and migration files in the prisma folder).
- Contains business logic to facilitate the storage of signed interactions, verification via oracles (Oracle.ts implementations), and validation of user-submitted data.
- Containerized using Docker (Dockerfile and docker-compose configurations are present).
- Smart Contracts:
- Managed in the smart-contracts folder. Uses Hardhat for deployment (hardhat.config.ts) and includes Solidity contracts under contracts directories.
- Contains scripts and tests to deploy and validate core blockchain logic (e.g., handling ProofOfInteraction logic and oracle behavior).
- Acts as the decentralized mechanism where interactions are recorded and verified on-chain.

##### Relationships and Interactions
- Users interact with the Frontend which sends API requests to the Backend.
- The Backend processes these requests, interacts with the database (using Prisma) for off-chain data management, and calls out to Smart Contracts for recording the signed interactions on the blockchain.
- The smart contracts (deployed on Ethereum or a testnet) interact with external oracles (also implemented in both backend modules and contract interfaces) to verify data integrity.

##### Architectural Patterns and Key Technologies
- Separation of Concerns / Modular Architecture: The division into frontend, backend (with distinct modules for validation, oracle functions, and database interactions), and blockchain components is key.
- Containerization: The use of Docker implies that the backend deployment is containerized, which might be represented as a separate deployment unit.
- Blockchain-Oriented Design: Smart contract interactions, oracle verification, and the signature-based proofing mechanism underpin the design.
- Relevant libraries & frameworks include NestJS (backend), Prisma (ORM), Next.js/React (frontend), and Hardhat (smart contract development).

- Frontend:
- Components such as pages, API utilities, and UI components.
- How it interacts with backend APIs.
- Backend:
- Configuration files, testing, and middleware.
- How the API server handles incoming requests and orchestrates smart contract interactions.
- Smart Contracts:
- Core contracts (ProofOfInteraction, Oracle) and any scripts used to deploy them.
- Testing flow in the smart-contracts/test directory.
- Infrastructure:
- Optionally, indicate Docker as a deployment container for the backend.
- Interconnections with Ethereum networks (based on the proof mechanism described).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    USR("User"):::external

    %% Frontend Subgraph
    subgraph "Frontend (Next.js + React UI)"
        FE_Config("Next.js Config"):::frontend
        FE_Pages("Pages (React)"):::frontend
        FE_Components("Components"):::frontend
        FE_Styles("Styles"):::frontend
    end

    %% Backend Subgraph
    subgraph "Backend (NestJS API Service)"
        BE_AppModule("NestJS App Module"):::backend
        BE_Main("NestJS Main"):::backend
        BE_Dockerfile("Dockerfile"):::docker
        BE_DockerCompose("Docker Compose"):::docker
        Oracle_Module("Oracle Module"):::backend
        Validation_Module("Validation Module"):::backend
        Prisma_Module("Prisma Module"):::backend
    end

    %% Smart Contracts Subgraph
    subgraph "Smart Contracts (Hardhat & Solidity)"
        SC_Hardhat("Hardhat Config"):::smart
        SC_Contracts("Solidity Contracts"):::smart
        SC_Scripts("Deployment Scripts & Tests"):::smart
    end

    %% Database Subgraph
    subgraph "Database"
        DB("Prisma Database"):::database
    end

    %% Relationships
    USR -->|"interacts"| FE_Config
    USR -->|"interacts"| FE_Pages
    USR -->|"interacts"| FE_Components
    USR -->|"interacts"| FE_Styles

    FE_Config -->|"calls"| BE_AppModule
    FE_Pages -->|"calls"| BE_AppModule
    FE_Components -->|"calls"| BE_AppModule
    FE_Styles -->|"calls"| BE_AppModule

    BE_AppModule -->|"initializes"| BE_Main
    BE_Main -->|"routes to"| Oracle_Module
    BE_Main -->|"routes to"| Validation_Module
    BE_Main -->|"calls"| Prisma_Module
    BE_Main -->|"triggers"| SC_Contracts

    BE_Dockerfile --- BE_AppModule
    BE_DockerCompose --- BE_AppModule

    Prisma_Module -->|"accesses"| DB

    Oracle_Module -->|"verifies"| SC_Contracts

    SC_Hardhat -->|"configures"| SC_Contracts
    SC_Scripts -->|"deploys"| SC_Contracts

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef docker fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef smart fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef database fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    %% Click Events for Frontend
    click FE_Config "https://github.com/easonchai/proof-of-interaction/blob/main/frontend/next.config.js"
    click FE_Pages "https://github.com/easonchai/proof-of-interaction/tree/main/frontend/src/pages"
    click FE_Components "https://github.com/easonchai/proof-of-interaction/tree/main/frontend/src/components"
    click FE_Styles "https://github.com/easonchai/proof-of-interaction/tree/main/frontend/src/styles"

    %% Click Events for Backend
    click BE_AppModule "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/app.module.ts"
    click BE_Main "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/main.ts"
    click BE_Dockerfile "https://github.com/easonchai/proof-of-interaction/tree/main/backend/Dockerfile"
    click BE_DockerCompose "https://github.com/easonchai/proof-of-interaction/blob/main/backend/docker-compose.yml"

    click Oracle_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/oracle/oracle.module.ts"
    click Oracle_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/oracle/oracle.service.ts"
    click Oracle_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/contract/Oracle.ts"

    click Validation_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/validation/validation.controller.ts"
    click Validation_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/validation/validation.service.ts"
    click Validation_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/validation/validation.interface.ts"

    click Prisma_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/prisma/schema.prisma"
    click Prisma_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/prisma/prisma.module.ts"
    click Prisma_Module "https://github.com/easonchai/proof-of-interaction/blob/main/backend/src/prisma/prisma.service.ts"

    %% Click Events for Smart Contracts
    click SC_Hardhat "https://github.com/easonchai/proof-of-interaction/blob/main/smart-contracts/hardhat.config.ts"
    click SC_Contracts "https://github.com/easonchai/proof-of-interaction/tree/main/smart-contracts/contracts/"
    click SC_Scripts "https://github.com/easonchai/proof-of-interaction/tree/main/smart-contracts/scripts/"
    click SC_Scripts "https://github.com/easonchai/proof-of-interaction/tree/main/smart-contracts/test/"
    click SC_Scripts "https://github.com/easonchai/proof-of-interaction/blob/main/smart-contracts/utils/oracle.arguments.js"
```
