# immanuel-peter/semantic-image-search architecture

> Architecture diagram of the GitHub repository immanuel-peter/semantic-image-search, 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/immanuel-peter/semantic-image-search
- Repository: https://github.com/immanuel-peter/semantic-image-search

## Overview

##### Project Type and Purpose
- The project is a full-stack application with separate backend and frontend components.
- It performs text-based semantic image searches by leveraging OpenAI CLIP, PyTorch, and FastAPI on the backend, and offers a responsive user interface using Next.js, React, and Tailwind CSS on the frontend.
- Additionally, a folder (“random-images”) holds preloaded images and there is a script (get-random-images.py) to update them, showing integration with external image sources (e.g., Unsplash).

##### Main Components to Highlight
a. Backend:
- FastAPI Server: Represented by files like call.py and model.py. This is the core service that handles API requests.
- Image Processing Module: The integration with PyTorch and OpenAI CLIP is primarily handled here for semantic image search capabilities.
- Utility Scripts: Such as get-random-images.py, which fetches and updates image data from an external source (Unsplash).
- Dependencies: Mention that it uses Python 3.10+, and key libraries like PyTorch and Hugging Face Transformers.

b. Frontend:
- Next.js Application: Located under the frontend/semantic-image-search directory. It consists of several files and components (like SemanticImageSearch.tsx, layout.tsx, and various UI components such as button.tsx, card.tsx, etc.) which build the user interface.
- Styling: Tailwind CSS integration is evident from configuration files (tailwind.config.ts) and the use of globals.css.

c. Data and Miscellaneous:
- Random Images: A dedicated folder (“random-images”) that stores sample images used for demonstration. It ties into the backend operation through the image fetching script.
- External Dependencies: Reference to external services like Unsplash (for fetching image data) and the use of FastAPI for the API layer.

##### Relationships and Interactions
- The frontend sends text-based search queries to the backend API.
- The backend processes these requests using PyTorch and the CLIP model to semantically match the search query with stored/random images.
- The response (a set of images that semantically match the query) is sent back to the frontend, which then renders the images dynamically.
- The get-random-images.py script updates or maintains the image dataset in the “random-images” folder, ensuring that the demo and search functionalities have fresh data when needed.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly distinguish between frontend (user interaction) and backend (business logic, image processing) responsibilities.
- REST API Design: The FastAPI backend is built as a service that exposes RESTful endpoints where the frontend communicates via HTTP requests.
- Modular Design: The project is partitioned into logically well-organized modules – backend utilities, model handling, and frontend UI components – enabling scalability and maintainability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE1["Next.js Application (SemanticImageSearch)"]:::frontend
        FE2["Layout & Styling (Tailwind CSS)"]:::frontend
        FE3["UI Components (Buttons, Cards, Input Fields)"]:::frontend
    end

    subgraph "Backend Layer"
        BE1["FastAPI Server (call.py)"]:::backend
        BE2["Model Logic (PyTorch & CLIP, model.py)"]:::backend
        BE3["Utility Script (get-random-images.py)"]:::backend
    end

    IMG["Random Images Storage"]:::storage
    EXT["Unsplash External Service"]:::external

    FE1 -->|"text_query"| BE1
    BE1 -->|"process_request"| BE2
    BE2 -->|"fetch_images"| IMG
    IMG -->|"results_returned"| BE2
    BE1 -->|"API_response"| FE1

    BE3 -->|"update_images"| IMG
    BE3 -->|"fetch_external"| EXT

    classDef frontend fill:#ffebcd,stroke:#8b4513,stroke-width:2px;
    classDef backend fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef storage fill:#98fb98,stroke:#006400,stroke-width:2px;
    classDef external fill:#ffe4e1,stroke:#ff4500,stroke-width:2px;

    click BE1 "https://github.com/immanuel-peter/semantic-image-search/blob/main/backend/call.py"
    click BE2 "https://github.com/immanuel-peter/semantic-image-search/blob/main/backend/model.py"
    click BE3 "https://github.com/immanuel-peter/semantic-image-search/blob/main/backend/get-random-images.py"
    click FE1 "https://github.com/immanuel-peter/semantic-image-search/blob/main/frontend/semantic-image-search/app/SemanticImageSearch.tsx"
    click FE2 "https://github.com/immanuel-peter/semantic-image-search/blob/main/frontend/semantic-image-search/app/layout.tsx"
    click FE2 "https://github.com/immanuel-peter/semantic-image-search/blob/main/frontend/semantic-image-search/app/globals.css"
    click FE3 "https://github.com/immanuel-peter/semantic-image-search/tree/main/frontend/semantic-image-search/components/ui"
    click IMG "https://github.com/immanuel-peter/semantic-image-search/tree/main/random-images"
```
