# data-wrangling-and-visualisation/renai architecture

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

- Interactive diagram: https://gitdiagram.com/data-wrangling-and-visualisation/renai
- Repository: https://github.com/data-wrangling-and-visualisation/renai

## Overview

##### Project Type and Purpose
- R.E.N.A.I is a full-stack, data-driven web application for AI-based art exploration and analysis.
- Frontend: React + Material UI for interactive visualizations.
- Backend: Flask API orchestrating ML models, caching results, serving data.
- Auxiliary pipelines: data collection (JSON/image ingestion), pre-processing, embedding and map generation.

##### File-Structure Analysis
- Top-level:
- react-renai/ → React frontend (Vite config, server.js for production, components, utils).
- server/ → Flask backend (api.py, processing modules, data cache under server/data).
- processing-data/ → standalone scripts generating embeddings and attention maps.
- сollection-data/ → data-ingestion scripts fetching MET JSON batches, saving images, uploading to Mongo.
- docker-compose.yml, Dockerfiles → container setup.
- Patterns: clear client/server separation, offline pipelines for data collection and processing, file-based caching (.npy, .json).

##### Key README Insights
- Machine-learning modules: EfficientNetB0/DINOv2 (embeddings), ResNet50 (Grad-CAM), ViT (attention).
- Lazy loading & virtualization on frontend.
- REST API endpoints under /api/* for metadata, analysis, visualizations.
- External dependency: Metropolitan Museum of Art Collection API.

##### Main Components
a. Frontend Layer (React-RenAI)
- Browser client (JS/CSS)
- React components: EmbeddingProjection, ArtSimilarityGraph, AttentionVisualizer, StyleAnalysis, Sidebar, etc.
- Client-side state & session storage
- Dev server (Vite) or production static server (server.js)
b. Backend Layer (Flask API)
- api.py routes
- Processing modules: embeddings.py, Gradcam.py, hitmaps.py, improved_analysis.py, preprocess_artworks.py
- Utilities (utils.py, color_names_ru.py)
- Data cache (server/data/embeddings, server/data/images)
c. Data Ingestion & Pre-Processing Pipelines
- collection-data scripts: JSON fetcher, image_saver, upload_to_mongo
- processing-data scripts producing .npy heatmaps and embedding arrays
d. External Services & Storage
- Metropolitan Museum of Art API (metadata + raw images)
- (Optional) MongoDB for raw JSON storage
- Docker containers for frontend/backend

##### Interactions & Data Flow
- Data-Ingestion Pipeline:
MET API → collection-data/ → raw JSON, images → (optional) MongoDB
- Pre-Processing Pipeline:
raw images → processing-data/ → .npy embeddings & maps → server/data
- Runtime Backend:
Client ↔ Flask API endpoints → on-demand processing or cached lookup → returns JSON, images, .npy data
- Frontend:
React UI → REST calls → renders visualizations (charts, force graphs, heatmaps)
- Caching/lazy-loading: only fetch analysis data when requested

##### Architectural Patterns & Principles
- Layered architecture: Data pipelines → ML processing → API layer → Client UI
- Separation of concerns: distinct components for ingestion, processing, serving, visualization
- Caching to avoid redundant ML inference (.npy files)
- Lazy-loading and virtualization for performance
- Containerization: Docker Compose defines services and dependencies

##### Technologies & Frameworks
- Frontend: React, Vite, Material UI, Recharts, Nivo, Chart.js, react-force-graph-3d, react-window
- Backend: Flask, Python 3.10+, PyTorch, TensorFlow, Timm, Transformers, NumPy, OpenCV, Pillow
- External API: The Met Collection API
- Containers: Docker, Docker Compose

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services / Storage" 
        direction TB
        MET["Met Museum API"]:::external
        MongoDB[(MongoDB)]:::storage
    end

    %% Data Ingestion Pipeline
    subgraph "Data Ingestion Pipeline" 
        direction TB
        Parser["JSON Parser"]:::pipeline
        Saver["Image Saver"]:::pipeline
        Uploader["MongoDB Uploader"]:::pipeline
        JSONDir[(Batch JSON Dir)]:::storage
    end

    %% Pre-Processing Pipeline
    subgraph "Pre-Processing Pipeline"
        direction TB
        EmbPipeline["Embeddings Pipeline"]:::pipeline
        GradcamPipeline["Grad-CAM Pipeline"]:::pipeline
        HitmapPipeline["Attention/Hitmap Pipeline"]:::pipeline
    end

    %% Storage Cache
    subgraph "File System Cache" 
        direction TB
        EmbCache[(Embeddings .npy)]:::storage
        ImgCache[(Images Cache)]:::storage
    end

    %% Backend Layer
    subgraph "Flask Backend" 
        direction TB
        API["Flask api.py"]:::backend
        Preproc["preprocess_artworks.py"]:::backend
        Improve["improved_analysis.py"]:::backend
        EmbModule["embeddings.py"]:::backend
        GradcamModule["Gradcam.py"]:::backend
        HitmapModule["hitmaps.py"]:::backend
        Utils["utils.py / color_names_ru.py"]:::backend
    end

    %% Frontend Layer
    subgraph "React Frontend" 
        direction TB
        Browser["Browser Client"]:::frontend
        DevServer["Vite Dev Server"]:::frontend
        ProdServer["Static Prod Server"]:::frontend
        subgraph "UI Components"
            direction TB
            EmbComp["EmbeddingProjection.jsx"]:::frontend
            GraphComp["ArtSimilarityGraph.jsx"]:::frontend
            AttnComp["AttentionVisualizer.jsx"]:::frontend
            StyleComp["StyleAnalysis.jsx"]:::frontend
            SidebarComp["Sidebar.jsx"]:::frontend
        end
        subgraph "Utils"
            direction TB
            DataUtil["dataProcessing.js"]:::frontend
            DimUtil["dimensionReduction.jsx"]:::frontend
        end
    end

    %% Container Orchestration
    subgraph "Containerization"
        direction TB
        Compose["docker-compose.yml"]:::config
        FE_Docker["Dockerfile.frontend"]:::config
        BE_Docker["Dockerfile.backend"]:::config
    end

    %% Data Flow Arrows
    MET -->|"GET JSON"| Parser
    MET -->|"GET Images"| Saver
    Parser --> JSONDir
    Saver --> ImgCache
    JSONDir --> Uploader
    Uploader --> MongoDB

    Saver -->|"/images"| EmbPipeline
    EmbPipeline -->|".npy"| EmbCache
    GradcamPipeline -->|".npy"| EmbCache
    HitmapPipeline -->|".npy"| EmbCache

    %% Runtime Flow
    Browser -->|"HTTP" | DevServer
    Browser -->|"HTTP" | ProdServer
    DevServer -->|"REST/JSON"| API
    ProdServer -->|"REST/JSON"| API

    API -->|"calls"| Preproc
    API -->|"calls"| Improve
    API -->|"calls"| EmbModule
    API -->|"calls"| GradcamModule
    API -->|"calls"| HitmapModule
    API -->|"imports"| Utils

    EmbModule -->|"load .npy"| EmbCache
    GradcamModule -->|"load .npy"| EmbCache
    HitmapModule -->|"load .npy"| EmbCache

    API -->|"returns JSON/images"| Browser

    %% UI Components Data Flow
    Browser --> EmbComp
    Browser --> GraphComp
    Browser --> AttnComp
    Browser --> StyleComp
    Browser --> SidebarComp
    EmbComp --> DataUtil
    GraphComp --> DataUtil
    AttnComp --> DimUtil
    StyleComp --> DataUtil

    %% Containers
    Compose --> FE_Docker
    Compose --> BE_Docker
    Compose --> API
    Compose --> DevServer

    %% Click Events
    click Parser "https://github.com/data-wrangling-and-visualisation/renai/blob/main/сollection-data/data_parser.py"
    click Saver "https://github.com/data-wrangling-and-visualisation/renai/blob/main/сollection-data/image_saver.py"
    click Uploader "https://github.com/data-wrangling-and-visualisation/renai/blob/main/сollection-data/upload_to_mongo.py"
    click JSONDir "https://github.com/data-wrangling-and-visualisation/renai/tree/main/сollection-data/json_data/"
    click EmbPipeline "https://github.com/data-wrangling-and-visualisation/renai/blob/main/processing-data/embeddings.py"
    click GradcamPipeline "https://github.com/data-wrangling-and-visualisation/renai/blob/main/processing-data/Gradcam.py"
    click HitmapPipeline "https://github.com/data-wrangling-and-visualisation/renai/blob/main/processing-data/hitmaps.py"
    click EmbCache "https://github.com/data-wrangling-and-visualisation/renai/tree/main/server/data/embeddings/"
    click ImgCache "https://github.com/data-wrangling-and-visualisation/renai/tree/main/server/data/images/"
    click API "https://github.com/data-wrangling-and-visualisation/renai/blob/main/server/api.py"
    click Preproc "https://github.com/data-wrangling-and-visualisation/renai/blob/main/server/preprocess_artworks.py"
    click Improve "https://github.com/data-wrangling-and-visualisation/renai/blob/main/server/improved_analysis.py"
    click Utils "https://github.com/data-wrangling-and-visualisation/renai/blob/main/server/utils.py"
    click EmbComp "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/components/EmbeddingProjection.jsx"
    click GraphComp "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/components/ArtSimilarityGraph.jsx"
    click AttnComp "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/components/AttentionVisualizer.jsx"
    click StyleComp "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/components/StyleAnalysis.jsx"
    click SidebarComp "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/components/Sidebar.jsx"
    click DataUtil "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/utils/dataProcessing.js"
    click DimUtil "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/src/utils/dimensionReduction.jsx"
    click DevServer "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/vite.config.js"
    click ProdServer "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/server.js"
    click Compose "https://github.com/data-wrangling-and-visualisation/renai/blob/main/docker-compose.yml"
    click FE_Docker "https://github.com/data-wrangling-and-visualisation/renai/blob/main/react-renai/Dockerfile.frontend"
    click BE_Docker "https://github.com/data-wrangling-and-visualisation/renai/blob/main/server/Dockerfile.backend"

    %% Styles
    classDef pipeline fill:#FFA500,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef frontend fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#FFD700,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
