# yesidmg/smart-search architecture

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

- Interactive diagram: https://gitdiagram.com/yesidmg/smart-search
- Repository: https://github.com/yesidmg/smart-search

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-based web application (“Smart Search”) whose goal is to collect user preferences, process them through an LLM, scrape product URLs, and return personalized recommendations.

##### Key Architectural Components
a. Frontend Service (React + Vite)
- Lives in the `front/` directory.
- Captures user input via UI and publishes messages to RabbitMQ (`solicitudes`).
- Subscribes to RabbitMQ queues (`respuestas` for status updates and `scraped_urls_queue` for final recommendations).
b. Backend Workers (`back/`)
- **Request Processor** (`index.py`):
– Consumer of `solicitudes` queue.
– Persists user/test data to PostgreSQL.
– Publishes a status message to `respuestas`.
– Publishes a user-profile message to `peticiones_ia`.
- **Scraper** (`scraper.py`):
– Consumer of `scrapper_peticiones_queue`.
– Performs web scraping on MercadoLibre Colombia.
– Publishes scraped URLs to `scraped_urls_queue`.
- These two processes run under Supervisor.
c. AI Service (`ai_service/`)
- **Flask Proxy** (`app.py`): health endpoint + direct proxy to OpenRouter API.
- **RabbitMQ Consumer** (`rabbitmq_client.py`):
– Listens on `peticiones_ia`.
– Calls the LLM via `openrouter_client.py`.
– Publishes generated search terms to `scrapper_peticiones_queue`.
d. Message Broker (RabbitMQ)
- Manages asynchronous message queues: `solicitudes`, `respuestas`, `peticiones_ia`, `scrapper_peticiones_queue`, `scraped_urls_queue`.
e. Database (PostgreSQL)
- Stores user data, tests, requests. Initialized by `Postgres/init.sql`.
f. Reverse Proxy (Traefik)
- Routes HTTP traffic to frontend and can expose AI service.

##### Interactions & Data Flows
1. **User → Frontend UI** (HTTP)
2. **Frontend → RabbitMQ** (`solicitudes`) (AMQP)
3. **Request Processor → PostgreSQL** (SQL)
4. **Request Processor → RabbitMQ** (`respuestas` & `peticiones_ia`) (AMQP)
5. **AI Consumer → OpenRouter LLM** (HTTP)
6. **AI Consumer → RabbitMQ** (`scrapper_peticiones_queue`) (AMQP)
7. **Scraper → External Website** (HTTP)
8. **Scraper → RabbitMQ** (`scraped_urls_queue`) (AMQP)
9. **Frontend → RabbitMQ** (listening to `respuestas` & `scraped_urls_queue`)

##### Architectural Patterns & Design Principles
- Microservices with clear service boundaries.
- Asynchronous, event-driven communication via message broker.
- Separation of concerns: UI, business logic (workers), ML orchestration, data persistence.
- Containerization (Docker Compose) for orchestration and process isolation.
- Process supervision (Supervisor) for worker resilience.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Docker Compose"
        subgraph "front (React + Vite)"
            FE["Frontend Service"]:::frontend
        end
        subgraph "back (Supervisor Workers)"
            RP["Request Processor"]:::backend
            SW["Scraper Worker"]:::backend
        end
        subgraph "ai_service (Flask + Consumer)"
            AI["AI Service"]:::ai
        end
        MQ["RabbitMQ\nQueues"]:::mq
        PG["PostgreSQL"]:::db
        TR["Traefik"]:::proxy
    end

    User["User Browser"]:::external
    OR["OpenRouter API"]:::external
    ML["MercadoLibre"]:::external

    User -->|"HTTP"| TR
    TR -->|"HTTP"| FE

    FE -->|"AMQP solicitudes"| MQ
    MQ -->|"respuestas & scraped_urls_queue"| FE

    RP -->|"SQL"| PG
    RP -->|"AMQP respuestas"| MQ
    RP -->|"AMQP peticiones_ia"| MQ

    MQ -->|"peticiones_ia"| AI
    AI -->|"HTTP to LLM"| OR
    AI -->|"AMQP scrapper_peticiones_queue"| MQ

    MQ -->|"scrapper_peticiones_queue"| SW
    SW -->|"HTTP scrape"| ML
    SW -->|"AMQP scraped_urls_queue"| MQ

    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef ai fill:#fff3cd,stroke:#856404,color:#856404;
    classDef mq fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef proxy fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#fff3cd,stroke:#856404,color:#856404;

    click FE "https://github.com/yesidmg/smart-search/tree/main/front/"
    click FE "https://github.com/yesidmg/smart-search/blob/main/front/src/main.jsx"
    click FE "https://github.com/yesidmg/smart-search/blob/main/front/src/App.jsx"
    click FE "https://github.com/yesidmg/smart-search/blob/main/front/src/services/rabbitmq.js"
    click FE "https://github.com/yesidmg/smart-search/tree/main/front/Dockerfile"
    click FE "https://github.com/yesidmg/smart-search/blob/main/front/package.json"

    click RP "https://github.com/yesidmg/smart-search/blob/main/back/index.py"
    click RP "https://github.com/yesidmg/smart-search/blob/main/back/database_utils.py"
    click RP "https://github.com/yesidmg/smart-search/blob/main/back/rabbitmq_utils.py"
    click RP "https://github.com/yesidmg/smart-search/tree/main/back/Dockerfile"
    click RP "https://github.com/yesidmg/smart-search/blob/main/back/supervisor.conf"

    click SW "https://github.com/yesidmg/smart-search/blob/main/back/scraper.py"
    click SW "https://github.com/yesidmg/smart-search/blob/main/back/rabbitmq_utils.py"
    click SW "https://github.com/yesidmg/smart-search/tree/main/back/Dockerfile"
    click SW "https://github.com/yesidmg/smart-search/blob/main/back/supervisor.conf"

    click AI "https://github.com/yesidmg/smart-search/blob/main/ai_service/app.py"
    click AI "https://github.com/yesidmg/smart-search/blob/main/ai_service/rabbitmq_client.py"
    click AI "https://github.com/yesidmg/smart-search/blob/main/ai_service/openrouter_client.py"
    click AI "https://github.com/yesidmg/smart-search/tree/main/ai_service/Dockerfile"
    click AI "https://github.com/yesidmg/smart-search/blob/main/ai_service/requirements.txt"

    click PG "https://github.com/yesidmg/smart-search/blob/main/Postgres/init.sql"
    click PG "https://github.com/yesidmg/smart-search/tree/main/Postgres/Dockerfile"

    click MQ "https://github.com/yesidmg/smart-search/tree/main/rabbitmq/enabled_plugins"

    click TR "https://github.com/yesidmg/smart-search/blob/main/docker-compose.yml"
```
