# nhipixel/comparavision-integration architecture

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

- Interactive diagram: https://gitdiagram.com/nhipixel/comparavision-integration
- Repository: https://github.com/nhipixel/comparavision-integration

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“ComparaVision”) for benchmarking and comparing vision models (YOLO, EfficientNet, Detectron2, etc.) on accuracy, speed, memory, and environmental impact.
- The frontend is built with Next.js/React/TypeScript; the backend uses Node.js/Express; data is stored in Supabase (PostgreSQL); heavy AI workloads run on RunPod GPU containers and a Python “Vellum” integration.

##### File Structure
- Top-level:
- frontend/ — Next.js app with pages, API routes, React components, hooks, Tailwind CSS
- backend/ — Express server, local-server UI, Supabase setup, RunPod integration, Vellum Python module
- docker-compose.yml, deploy scripts (deploy.sh/.bat), root package.json
- backend/runpod/ contains Dockerfiles, worker scripts (vision_benchmark_worker.py, enhanced_vision_benchmark_worker.py), integration helpers, and helper-docs describing architecture.
- backend/vellum/ is a standalone Python package that implements additional AI capabilities.

##### README for Architecture Insights
- External services: RunPod (GPU compute), Supabase for real-time DB and authentication.

##### Main Components & Interactions
a. Frontend
- Next.js pages for upload, compare, dashboard, stats; React components + custom hooks.
- Communicates via REST/Fetch to Backend API at `http://localhost:3001` (or Next.js API routes if proxied).
b. Backend API Server
- Express.js routes under backend/server.js (e.g., /api/models, /api/comparisons, /api/auth).
- Handles authentication (Supabase), model uploads, triggers RunPod jobs.
c. Supabase (PostgreSQL + Auth + Real-time)
- Stores user profiles, model metadata, comparison results.
- Backend uses `backend/setup-database.js`, supabase-schema.sql, seeds, and `initSupabase.js`.
- Frontend access via supabase.js library for real-time updates.
d. RunPod AI Processing
- Node.js integration (backend/runpod/runpod_integration.js & backend/runpod/backend_api_integration.js).
- Python workers (benchmark, validation, vision_benchmark_worker.py) run inside Docker containers.
- Workers load specified vision model, run benchmarks, measure metrics (accuracy, FPS, memory, CO2), and return results via API callback.
e. Vellum Integration
- Python package under backend/vellum/ invoked for complementary AI tasks or summarization.
f. Local Server Component (for testing/demo)
- backend/local-server.js with React dashboard components under backend/src/components/LocalServerDashboard.jsx.
- Hooks under backend/src/hooks pull real-time data.
g. Deployment & Orchestration
- docker-compose.yml orchestrates frontend, backend, Supabase (if self-hosted), and optionally worker containers.
- deploy.sh/.bat scripts build images and start services.

##### Architectural Patterns & Design Principles
- Separation of concerns: Frontend UI, Backend API, Database, AI compute are distinct.
- API-driven: REST endpoints for all operations, decoupling UI from compute.
- Containerization: Docker for consistent environments across local, dev, prod.
- Event-driven / real-time: Supabase real-time DB pushes updates to frontend.
- Polyglot: JavaScript/TypeScript for web layers; Python for heavy AI workloads.

1. Sketch a high-level flow: User → Frontend → Backend → (Supabase & RunPod) → Backend → Frontend.
- Frontend: pages, components, hooks
- Backend: auth, model management, comparison service
- AI Layer: Python + GPU container pool
3. Data stores: Supabase with tables for organizations, models, comparisons, results.
4. Environment variables/config (e.g., RUNPOD_API_KEY, SUPABASE_URL).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & Browser Layer
    User["User"]:::external
    Browser["Web Browser"]:::external
    User -->|interacts with| Browser

    %% Frontend Layer
    subgraph "Next.js Frontend"
        direction TB
        NextJS["Next.js App"]:::frontend
        Pages["Pages & API routes"]:::frontend
        Components["React Components"]:::frontend
        Hooks["Custom Hooks"]:::frontend
        APIClient["API Client (api.ts)"]:::frontend
    end
    Browser -->|HTTP/Fetch| NextJS
    NextJS --> Pages
    NextJS --> Components
    NextJS --> Hooks
    NextJS --> APIClient

    %% Backend Layer
    subgraph "Express API Server"
        direction TB
        ExpressAPI["Express API Server"]:::backend
        InitSupabase["Supabase Init (initSupabase.js)"]:::backend
        Schema["DB Schema (supabase-schema.sql)"]:::backend
        SeedData["Seed Data (supabase-seed-data.sql)"]:::backend
        VellumSchema["Vellum Schema (supabase-vellum-schema.sql)"]:::backend
        SetupDB["Setup DB Script (setup-database.js)"]:::backend
        SetupSh["Setup Script (setup.sh)"]:::backend
        SetupBat["Setup Script (setup.bat)"]:::backend
        SupaLib["Supabase Client Lib"]:::backend
    end
    NextJS -->|REST API| ExpressAPI

    %% AI Compute Layer
    subgraph "AI Compute"
        direction TB
        subgraph "RunPod Integration"
            direction TB
            RPHelper1["runpod_integration.js"]:::ai
            RPHelper2["backend_api_integration.js"]:::ai
            Worker1["vision_benchmark_worker.py"]:::ai
            Worker2["enhanced_vision_benchmark_worker.py"]:::ai
            Worker3["test_worker.py"]:::ai
            RPDocker["Dockerfile"]:::ai
            RPDCompose["docker-compose.yml"]:::ai
            RPDeploySh["deploy.sh"]:::ai
            RPDeployBat["deploy.bat"]:::ai
        end
        subgraph "Vellum Integration"
            direction TB
            Vellum["Vellum Python Package"]:::ai
        end
    end
    ExpressAPI -->|invoke| RPHelper1
    ExpressAPI -->|invoke| RPHelper2
    ExpressAPI -->|invoke| Vellum
    RPHelper1 -->|dispatch jobs| Worker1
    RPHelper2 -->|dispatch jobs| Worker2
    RPHelper2 -->|dispatch jobs| Worker3
    Worker1 -->|callback| ExpressAPI
    Worker2 -->|callback| ExpressAPI
    Worker3 -->|callback| ExpressAPI

    %% Data & Real-time Layer
    subgraph "Supabase (DB & Auth)"
        direction TB
        SupabaseDB["PostgreSQL Database"]:::db
        SupabaseAuth["Auth & Real-time"]:::db
    end
    ExpressAPI -->|SQL/REST| SupabaseDB
    ExpressAPI -->|Auth API| SupabaseAuth
    SupabaseDB -->|real-time| NextJS
    SupabaseAuth -->|real-time| NextJS

    %% Local Server Component
    subgraph "Local Server (Demo/Test)"
        direction TB
        LocalServer["local-server.js"]:::backend
        LSDash["LocalServerDashboard.jsx"]:::frontend
        VellumDash["VellumDashboard.jsx"]:::frontend
        Hook1["useLocalServerData.js"]:::frontend
        Hook2["useVellumData.js"]:::frontend
    end
    ExpressAPI -->|provides data| LocalServer
    LocalServer --> LSDash
    LocalServer --> VellumDash
    LocalServer --> Hook1
    LocalServer --> Hook2

    %% External Services
    subgraph "External Services"
        direction TB
        RunPodAPI["RunPod API"]:::external
        SupabaseHost["Supabase Hosted Service"]:::external
    end
    ExpressAPI -->|HTTP/gRPC| RunPodAPI
    ExpressAPI -->|client lib| SupabaseHost

    %% Deployment & Orchestration
    subgraph "Deployment & Orchestration"
        direction TB
        ComposeRoot["docker-compose.yml"]:::deploy
        DeployShRoot["deploy.sh"]:::deploy
        DeployBatRoot["deploy.bat"]:::deploy
        BackendDocker["backend/Dockerfile"]:::deploy
        FrontendDocker["frontend/Dockerfile"]:::deploy
    end
    ComposeRoot --> FrontendDocker
    ComposeRoot --> BackendDocker
    ComposeRoot --> RPDCompose
    ComposeRoot --> SupabaseHost
    DeployShRoot --> ComposeRoot
    DeployBatRoot --> ComposeRoot

    %% Click Events
    click NextJS "https://github.com/nhipixel/comparavision-integration/tree/main/frontend/"
    click Pages "https://github.com/nhipixel/comparavision-integration/tree/main/frontend/src/app/"
    click Components "https://github.com/nhipixel/comparavision-integration/tree/main/frontend/src/components/"
    click Hooks "https://github.com/nhipixel/comparavision-integration/tree/main/frontend/src/hooks/"
    click APIClient "https://github.com/nhipixel/comparavision-integration/blob/main/frontend/src/lib/api.ts"
    click ExpressAPI "https://github.com/nhipixel/comparavision-integration/blob/main/backend/server.js"
    click InitSupabase "https://github.com/nhipixel/comparavision-integration/blob/main/backend/initSupabase.js"
    click Schema "https://github.com/nhipixel/comparavision-integration/blob/main/backend/supabase-schema.sql"
    click SeedData "https://github.com/nhipixel/comparavision-integration/blob/main/backend/supabase-seed-data.sql"
    click VellumSchema "https://github.com/nhipixel/comparavision-integration/blob/main/backend/supabase-vellum-schema.sql"
    click SetupDB "https://github.com/nhipixel/comparavision-integration/blob/main/backend/setup-database.js"
    click SetupSh "https://github.com/nhipixel/comparavision-integration/blob/main/backend/setup.sh"
    click SetupBat "https://github.com/nhipixel/comparavision-integration/blob/main/backend/setup.bat"
    click SupaLib "https://github.com/nhipixel/comparavision-integration/blob/main/backend/src/lib/supabase.js"
    click RPHelper1 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/runpod_integration.js"
    click RPHelper2 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/backend_api_integration.js"
    click Worker1 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/vision_benchmark_worker.py"
    click Worker2 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/enhanced_vision_benchmark_worker.py"
    click Worker3 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/test_worker.py"
    click RPDocker "https://github.com/nhipixel/comparavision-integration/tree/main/backend/runpod/Dockerfile"
    click RPDCompose "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/docker-compose.yml"
    click RPDeploySh "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/deploy.sh"
    click RPDeployBat "https://github.com/nhipixel/comparavision-integration/blob/main/backend/runpod/deploy.bat"
    click Vellum "https://github.com/nhipixel/comparavision-integration/tree/main/backend/vellum/"
    click LocalServer "https://github.com/nhipixel/comparavision-integration/blob/main/backend/local-server.js"
    click LSDash "https://github.com/nhipixel/comparavision-integration/blob/main/backend/src/components/LocalServerDashboard.jsx"
    click VellumDash "https://github.com/nhipixel/comparavision-integration/blob/main/backend/src/components/VellumDashboard.jsx"
    click Hook1 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/src/hooks/useLocalServerData.js"
    click Hook2 "https://github.com/nhipixel/comparavision-integration/blob/main/backend/src/hooks/useVellumData.js"
    click ComposeRoot "https://github.com/nhipixel/comparavision-integration/blob/main/docker-compose.yml"
    click DeployShRoot "https://github.com/nhipixel/comparavision-integration/blob/main/deploy.sh"
    click DeployBatRoot "https://github.com/nhipixel/comparavision-integration/blob/main/deploy.bat"
    click BackendDocker "https://github.com/nhipixel/comparavision-integration/tree/main/backend/Dockerfile"
    click FrontendDocker "https://github.com/nhipixel/comparavision-integration/tree/main/frontend/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef ai fill:#FFE5B4,stroke:#333,stroke-width:1px
    classDef db fill:#E7C6FF,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef deploy fill:#F0E68C,stroke:#333,stroke-width:1px
```
