# neonwatty/meme-search architecture

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

- Interactive diagram: https://gitdiagram.com/neonwatty/meme-search
- Repository: https://github.com/neonwatty/meme-search

## Overview

##### Main Components
- Meme Search Web Application:
- This is the Ruby on Rails application located in meme_search_pro/meme_search_app.
- It handles user interactions (views, controllers), business logic, integration with the database, and operations such as meme tag editing, search, and settings.
- It also manages interactions with static assets (memes directory), and may communicate with the image-to-text service when auto-generating descriptions.
- Image-to-Text Generator Service:
- This is the Python service located in meme_search_pro/image_to_text_generator.
- It is responsible for processing images to extract text and generate descriptions using diverse (and configurable) models (Florence, SmolVLM, Moondream2, etc.).
- It contains its own job queues and processing routines, and runs inside its own Docker container.
- Database:
- A Postgres instance (with pgvector extension) that stores image data, textual descriptions, embeddings, tag metadata, and information linking images with their file paths.
- Supporting Infrastructure:
- Docker environment: Use Docker-compose files (docker-compose.yml and docker-compose-local-build.yml) to orchestrate the multi-container environment.
- Configuration and Environment Management: .env and other configuration files that allow customization of ports/hosts and external volume mounts for memes.
- External volumes and file mounts: Mount points for locally stored meme images, ensuring that both the Rails app and image-to-text generator have access to the meme assets.

##### How the Components Interact
- The Rails app renders the front-end (HTML, JavaScript) and communicates with the Postgres database to store and retrieve metadata.
- When a user triggers an action to auto-generate meme descriptions (or when indexing is initiated), the Rails app sends a request (for example, via an API call) to the image-to-text generator service.
- The Python service processes the image using AI models and returns a generated description back to the Rails app.
- The Rails app then updates the database with the new descriptions and any associated vector embeddings, enabling semantic search.
- Both services access shared file volumes where memes are stored (as specified in the Docker volumes configuration). The Rails app accesses memes in its public directory, while the image-to-text service mounts similar volumes to access the same image files.

##### Architectural Patterns and Design Principles
- Service Separation / Microservices: Each service runs in its own container with a clearly defined role, communicating via HTTP/API requests.
- Containerization: The entire system is orchestrated through Docker, allowing isolation of services and scalable configurations.
- MVC (for Rails): The Rails application follows the Model-View-Controller pattern to manage data, business logic, and presentation.
- Asynchronous Processing: The image-to-text generator might implement job queues (see job_queue.py) to handle the potentially lengthy process of model inference asynchronously.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User"]:::user

    %% Docker & Compose Orchestration
    Docker["Docker & Compose Orchestration"]:::docker

    %% Main Services
    Rails["Rails Meme Search Application"]:::rails
    Python["Image-to-Text Generator (Python)"]:::python
    DB["PostgreSQL Database (with pgvector)"]:::database

    %% Shared File Volumes Subgraph
    subgraph "Shared Meme Files"
        PublicMemes["Public Memes"]:::volume
        MemeDir["Meme Directory"]:::volume
    end

    %% Interactions
    User -->|"interaction"| Rails
    Rails -->|"DBQueryUpdate"| DB
    Rails -->|"APIRequest"| Python
    Python -->|"APIResponse"| Rails

    %% Volume Access
    Rails ---|"VolumeMountAccess"| PublicMemes
    Python ---|"VolumeMountAccess"| MemeDir

    %% Docker Orchestration Links
    Docker ---|"orchestrates"| Rails
    Docker ---|"orchestrates"| Python
    Docker ---|"orchestrates"| DB

    %% Click Events
    click Rails "https://github.com/neonwatty/meme-search/tree/main/meme_search_pro/meme_search_app"
    click Python "https://github.com/neonwatty/meme-search/tree/main/meme_search_pro/image_to_text_generator"
    click DB "https://github.com/neonwatty/meme-search/blob/main/meme_search_pro/meme_search_app/config/database.yml"
    click Docker "https://github.com/neonwatty/meme-search/blob/main/docker-compose.yml"
    click PublicMemes "https://github.com/neonwatty/meme-search/tree/main/meme_search_pro/meme_search_app/public/memes"
    click MemeDir "https://github.com/neonwatty/meme-search/tree/main/meme_search_pro/memes"

    %% Styles
    classDef user fill:#fceabb,stroke:#d79b00,stroke-width:2px;
    classDef rails fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef python fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
    classDef database fill:#ffe082,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5 5;
    classDef docker fill:#d1c4e9,stroke:#673ab7,stroke-width:2px,stroke-dasharray: 3 3;
    classDef volume fill:#ffcdd2,stroke:#e53935,stroke-width:2px,stroke-dasharray: 2 2;
```
