# evin009/verifypto architecture

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

- Interactive diagram: https://gitdiagram.com/evin009/verifypto
- Repository: https://github.com/evin009/verifypto

## Overview

##### Project Type and Purpose
- Verifypto is a full-stack web application (Python/Flask backend + static HTML frontend) that lets users verify the credibility of Ethereum wallets and smart contracts by combining on-chain data analysis with AI summarization.

##### File-Structure Analysis
Top-level components:
- app.py – Flask application entry point with REST endpoints
- config_example.py – placeholder for API keys and configuration
- etherscan_helper.py – code that fetches transactions, token data, contract source from Etherscan APIs
- gemini_helper.py – code that wraps calls to Google Gemini AI for risk summarization
- verifier.py – orchestrates the risk-scoring logic, applies heuristics (blacklist checks, onlyOwner flags, etc.)
- mongodb_setup.py – establishes connection to MongoDB Atlas and defines history schema
- frontend/ – static HTML files (index.html, auth.html, dashboard.html)
- requirements.txt – Python dependencies (Flask, pymongo, requests, etc.)
External services/tools: Ngrok (for dev tunneling), MongoDB Atlas, Etherscan API, Google Gemini API.

##### README Insights
- Backend: Flask + custom Python modules
- AI Analysis: Google Gemini for human-friendly verdicts
- Data persistence: MongoDB Atlas for lookup history
- Core challenges: on-chain data interpretation, prompt engineering, API integration

##### Main Components
a. Client Side
- Web Browser → Static HTML/CSS/JS pages served by Flask
b. Backend/API Layer (Flask)
- Endpoint “/verify” accepts wallet/contract addresses
- Relies on helper modules
c. Helper Modules (Internal Services)
- EtherscanHelper: fetches on-chain data
- Verifier: computes risk scores and flags
- GeminiHelper: sends on-chain summary to Google Gemini → receives risk verdict
- MongoDBSetup: records and fetches verification history
d. External Services
- Etherscan REST API
- Google Gemini AI API
- MongoDB Atlas (cloud database)
- (Ngrok for development exposure)

##### Interactions and Data Flow
1. User enters address → frontend form submits to Flask
2. Flask “/verify” handler invokes EtherscanHelper → on-chain data
3. Verifier processes raw data, applies heuristics
4. GeminiHelper sends summary prompt → receives narrative verdict
5. Combined result saved via MongoDBSetup into Atlas
6. Flask returns verdict + risk level to frontend dashboard
7. User can view past lookups from history endpoint

##### Architectural Patterns and Design Principles
- Separation of concerns:
- Presentation layer (static frontend)
- Application/API layer (Flask)
- Domain logic (verifier, helper modules)
- Data layer (MongoDB)
- Single-responsibility in helper modules
- External integration points clearly separated

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Frontend (Static)" 
        style Frontend fill:#D5D8DC,stroke:#999,stroke-width:1px
        Browser["Web Browser"]:::frontend
        Index["index.html"]:::frontend
        Auth["auth.html"]:::frontend
        Dashboard["dashboard.html"]:::frontend
    end

    %% Flask API Layer
    Flask["Flask API Layer\n(app.py)"]:::flask

    %% Configuration
    Config["Configuration\n(config_example.py)"]:::internal

    %% Helper Modules
    subgraph "Helper Modules"
        style Helpers fill:#D6EAF8,stroke:#999,stroke-width:1px
        EtherscanHelper["EtherscanHelper\n(etherscan_helper.py)"]:::internal
        Verifier["Verifier\n(verifier.py)"]:::internal
        GeminiHelper["GeminiHelper\n(gemini_helper.py)"]:::internal
        MongoDBSetup["MongoDBSetup\n(mongodb_setup.py)"]:::internal
    end

    %% External Services
    subgraph "External Services"
        style External fill:#ABEBC6,stroke:#999,stroke-width:1px
        EtherscanAPI["Etherscan REST API"]:::external
        GeminiAPI["Google Gemini AI API"]:::external
        MongoDBAtlas[(MongoDB Atlas)]:::external
        Ngrok["Ngrok (Dev Tunnel)"]:::external
    end

    %% Documents
    subgraph "Project Docs"
        style Docs fill:#F2F3F4,stroke:#999,stroke-width:1px
        Requirements["requirements.txt"]:::docs
        Readme["README.md"]:::docs
        Gitignore[".gitignore"]:::docs
    end

    %% Data Flows
    Browser -->|HTTP POST /verify| Flask
    Flask -->|uses| Config
    Flask -->|invokes| EtherscanHelper
    EtherscanHelper -->|HTTPS| EtherscanAPI
    EtherscanAPI -->|data| EtherscanHelper
    EtherscanHelper -->|raw data| Verifier

    Verifier -->|summary prompt| GeminiHelper
    GeminiHelper -->|HTTPS| GeminiAPI
    GeminiAPI -->|verdict| GeminiHelper
    GeminiHelper -->|verdict data| Verifier

    Verifier -->|store/fetch| MongoDBSetup
    MongoDBSetup -->|HTTPS| MongoDBAtlas
    MongoDBAtlas -->|response| MongoDBSetup

    Verifier -->|result| Flask
    Flask -->|HTTP response| Browser

    %% History Retrieval
    Browser -->|HTTP GET /history| Flask
    Flask -->|query| MongoDBSetup
    MongoDBSetup -->|HTTPS| MongoDBAtlas
    MongoDBAtlas -->|history| MongoDBSetup
    MongoDBSetup -->|history data| Flask
    Flask -->|HTTP response| Browser

    %% Static Files Served
    Flask -->|serves| Index
    Flask -->|serves| Auth
    Flask -->|serves| Dashboard

    %% Dev Tool
    Ngrok -->|tunnels| Flask

    %% Click Events
    click Flask "https://github.com/evin009/verifypto/blob/main/app.py"
    click Config "https://github.com/evin009/verifypto/blob/main/config_example.py"
    click EtherscanHelper "https://github.com/evin009/verifypto/blob/main/etherscan_helper.py"
    click GeminiHelper "https://github.com/evin009/verifypto/blob/main/gemini_helper.py"
    click Verifier "https://github.com/evin009/verifypto/blob/main/verifier.py"
    click MongoDBSetup "https://github.com/evin009/verifypto/blob/main/mongodb_setup.py"
    click Index "https://github.com/evin009/verifypto/blob/main/frontend/index.html"
    click Auth "https://github.com/evin009/verifypto/blob/main/frontend/auth.html"
    click Dashboard "https://github.com/evin009/verifypto/blob/main/frontend/dashboard.html"
    click Requirements "https://github.com/evin009/verifypto/blob/main/requirements.txt"
    click Readme "https://github.com/evin009/verifypto/blob/main/README.md"
    click Gitignore "https://github.com/evin009/verifypto/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#D5D8DC,stroke:#555,stroke-width:1px
    classDef flask fill:#FAD7A0,stroke:#555,stroke-width:1px
    classDef internal fill:#D6EAF8,stroke:#555,stroke-width:1px
    classDef external fill:#ABEBC6,stroke:#555,stroke-width:1px
    classDef docs fill:#F2F3F4,stroke:#555,stroke-width:1px
```
