# teomesrkhani/full-stack-painting-recommender-platform architecture

> Architecture diagram of the GitHub repository teomesrkhani/full-stack-painting-recommender-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teomesrkhani/full-stack-painting-recommender-platform
- Repository: https://github.com/teomesrkhani/full-stack-painting-recommender-platform

## Overview

##### Project type and purpose
- This is a full-stack MERN (MongoDB, Express, React, Node.js) web application augmented with two Python-based microservices (a Flask image-generation service using PyTorch and a Chroma-based recommendation service).
- Purpose: Let users browse and save paintings, generate AI-driven new paintings via WikiArt prompts, and get personalized painting recommendations.

##### File structure
Top-level:
- client/ – React frontend (Vite)
- server/ – Node.js/Express backend plus two Python microservices
server/ subfolders:
- db/ – MongoDB connection helper
- routes/ – Express API routes (record.js)
- generate_painting/ – Flask service for AI painting generation
- recommend/ – Python services for embeddings and Chromadb recommendation
- server.js – Express app entry point

##### Key insights from README
- Frontend: React components under client/src
- Backend: REST API via Express, connects to MongoDB Atlas
- Two separate Python processes:
- Flask on port 5001 running generate_painting.py
- Python Chroma recommendation scripts
- LocalStorage fallback in client for unsaved state

##### Main components
a. Client (React SPA)
– Components: Home, Content, GenAI, Paintings, SavedPaintings
– Utilities: db.js (API client), localStorageDb.js, userSession.js
b. API Gateway (Node/Express server.js + routes)
– Endpoints:
- POST /record – log user interactions
- GET /paintings, /recommend – fetch data
c. MongoDB Atlas
d. Python Flask Microservice (generate_painting)
– Endpoint: /generate → runs PyTorch model using prompt_template.txt
e. Python Recommendation Service (ChromaDB)
– chroma_service.py serves recommendation queries via embedding lookup
– generate_embeddings.py prepares embeddings from WikiArt dataset
f. External services
– WikiArt API for painting metadata
– PyTorch model weights

##### Component relationships & data flows
1. User clicks “Generate AI Painting” in React → React calls Express API (e.g., POST /generate).
2. Express forwards request to Flask microservice (HTTP call to localhost:5001).
3. Flask returns generated image URL/base64 → Express returns to React.
4. User browses paintings → React calls Express (GET /paintings) → Express queries MongoDB Atlas → returns list.
5. For recommendations → React calls Express (GET /recommend) → Express invokes Python Chroma service or reads from local chroma.sqlite3 → returns recommended painting IDs → React displays results.
6. User actions (save, view) → React stores locally and via Express POST /record → Express writes to MongoDB.

##### Architectural patterns & design principles
- Separation of concerns:
- UI layer (React SPA)
- API layer (Express)
- Data layer (MongoDB, SQLite/Chroma for embeddings)
- AI/compute layer (Flask+PyTorch, Chroma recommendation scripts)
- Microservices for heavy ML workloads, keeping Node process lightweight
- LocalStorage fallback for offline UX

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        SPA["React App (Vite)"]:::frontend
        Main["main.jsx"]:::frontend
        subgraph "Components"
            direction TB
            Content["Content.jsx"]:::frontend
            GenAI["GenAI.jsx"]:::frontend
            Paintings["Paintings.jsx"]:::frontend
            SavedPaintings["SavedPaintings.jsx"]:::frontend
        end
        subgraph "Pages"
            direction TB
            Home["home.jsx"]:::frontend
        end
        subgraph "Utils"
            direction TB
            APIClient["db.js"]:::frontend
            LocalDB["localStorageDb.js"]:::frontend
            UserSession["userSession.js"]:::frontend
        end
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIServer["Express API Gateway"]:::backend
        RecordRoute["record.js"]:::backend
    end

    %% Databases
    subgraph "Databases"
        direction TB
        MongoDB["MongoDB Atlas"]:::db
        ChromaDB["chroma.sqlite3"]:::db
    end

    %% ML Services
    subgraph "ML Services"
        direction TB
        FlaskService["Flask Image-Gen Service:5001"]:::ml
        PromptTemplate["prompt_template.txt"]:::ml
        LambdaHandler["lambda_handler.py"]:::ml
        ChromaService["Chroma Recommendation Service"]:::ml
        RecoLogic["chroma_recommendation_service.py"]:::ml
        Embeddings["generate_embeddings.py"]:::ml
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WikiArtAPI["WikiArt API"]:::external
        PyTorchWeights["PyTorch Model Weights"]:::external
    end

    %% Data Flows
    Browser["Browser"]:::external
    Browser -->|"5373 HTTP"| SPA
    SPA -->|"/generate"| APIServer
    SPA -->|"/paintings"| APIServer
    SPA -->|"/recommend"| APIServer
    SPA -->|"/record"| APIServer

    APIServer --> RecordRoute
    APIServer -->|TCP| MongoDB
    APIServer -->|"HTTP:5001"| FlaskService
    APIServer -->|"HTTP"| ChromaService

    FlaskService --> PromptTemplate
    FlaskService --> PyTorchWeights

    ChromaService --> RecoLogic
    RecoLogic --> ChromaDB
    Embeddings --> ChromaDB

    SPA --> APIClient
    SPA --> LocalDB
    SPA --> UserSession

    %% Click Events
    click SPA "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/tree/main/client/"
    click Main "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/main.jsx"
    click Content "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/components/Content.jsx"
    click GenAI "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/components/GenAI.jsx"
    click Paintings "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/components/Paintings.jsx"
    click SavedPaintings "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/components/SavedPaintings.jsx"
    click Home "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/pages/home.jsx"
    click APIClient "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/utils/db.js"
    click LocalDB "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/utils/localStorageDb.js"
    click UserSession "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/client/src/utils/userSession.js"
    click APIServer "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/server.js"
    click RecordRoute "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/routes/record.js"
    click MongoDB "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/db/connection.js"
    click FlaskService "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/generate_painting/generate_painting.py"
    click PromptTemplate "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/generate_painting/data/prompt_template.txt"
    click LambdaHandler "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/generate_painting/lambda_handler.py"
    click ChromaService "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/recommend/chroma_service.py"
    click RecoLogic "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/recommend/chroma_recommendation_service.py"
    click Embeddings "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/recommend/generate_embeddings.py"
    click ChromaDB "https://github.com/teomesrkhani/full-stack-painting-recommender-platform/blob/main/server/recommend/chroma_db/chroma.sqlite3"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#DFFFD0,stroke:#228B22,color:#228B22
    classDef db fill:#FFE0B2,stroke:#FF8C00,color:#FF8C00
    classDef ml fill:#E1BEE7,stroke:#8E24AA,color:#8E24AA
    classDef external fill:#F0F0F0,stroke:#999,color:#666
```
