# amwt24/ahorrec architecture

> Architecture diagram of the GitHub repository amwt24/ahorrec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amwt24/ahorrec
- Repository: https://github.com/amwt24/ahorrec

## Overview

##### Project Type & Purpose
- Full-stack, microservices-style platform for real-time supermarket price comparison + AI-powered cooking assistant.
- Frontend: React/TypeScript SPA.
- Backend: FastAPI REST service.
- Data/IA pipeline: Scrapy spiders, filtering, vectorization scripts.
- Persistence: relational or document DB + vector store.
- External AI: LLM (Gemini, etc.) for recipe generation.

##### High-Level File Structure Analysis
- Top level
- backend/ – FastAPI app
- frontend/ – React SPA
- scrapersAhorrEC/ – Scrapy ETL service
- docker-compose.yml – orchestrates containers
- CI configs (GitHub Actions, Jenkinsfile)
- backend/
- routes.py – HTTP controllers
- services/ – business logic modules (shopping, recipes, ranking, embeddings, etc.)
- chef_service.py – LLM integration
- database.py – DB connectivity
- scripts/ – offline utilities (vectorize_products.py)
- frontend/
- src/app/components – UI widgets and views
- config.ts, hooks/, styles/ – configuration, state hooks, styling
- scrapersAhorrEC/
- spiders/ – one per supermarket
- pipelines.py, middlewares.py – data processing
- scripts/ – filter_food.py, upload_recetas.py

##### Key Components
a. Client Layer
– Browser/mobile running React SPA
b. API Layer
– FastAPI service (routes → service modules → DB / vector store / LLM)
c. Data Pipeline
– Scrapy container: spiders → raw JSON
– Filter/ETL scripts → Database + Vector DB
– Vectorization script → Vector DB
d. Persistence
– Primary DB (Postgres/Mongo) for products, users, history
– Vector store (e.g., Pinecone) for embedding-based ranking
e. External AI Service
– Gemini/OpenAI APIs for recipe generation
f. DevOps & Infra
– Docker/Docker Compose
– CI/CD pipelines (GitHub Actions, Jenkins)
– (Optional) Cloud load balancer, container registry

##### Data Flows & Interactions
- User → Frontend (UI) → HTTP(S) → FastAPI routes
- FastAPI → Services → Database (CRUD)
- FastAPI → Embedding Service → Vector store (k-NN queries)
- FastAPI → Chef Service → LLM API → response → UI
- Scheduled ETL: Scrapy spiders → raw JSON → filter_food → upload_recetas → DB & Vector DB
- Scripts/vectorize_products run offline or on CI trigger → update vector store

##### Architectural Patterns & Principles
- Microservices / separation of concerns
- Layered architecture in backend (Controller → Service → Data)
- Asynchronous ETL vs. synchronous API
- SPA decoupled from backend API
- Containerization for environment consistency

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/UI Layer
    subgraph "Client / UI" 
        direction TB
        Browser["Browser / Mobile"]:::frontend
        ReactSPA["React SPA"]:::frontend
        EntryPoint["main.tsx"]:::frontend
        HTMLTemplate["index.html"]:::frontend
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        Routes["routes.py"]:::backend
        DatabaseConn["database.py"]:::backend
        ChefService["chef_service.py"]:::backend
        subgraph "Business Logic Services"
            direction TB
            ComparisonSvc["comparison_service.py"]:::backend
            EmbeddingSvc["embedding_service.py"]:::backend
            ProductSvc["product_service.py"]:::backend
            RankingSvc["ranking_service.py"]:::backend
            RecipeSvc["recipe_service.py"]:::backend
            ShoppingSvc["shopping_service.py"]:::backend
            UomSvc["uom_service.py"]:::backend
            CanastaSvc["canasta_basica.py"]:::backend
        end
        VectorizeScript["vectorize_products.py"]:::backend
    end

    %% Data Pipeline / ETL
    subgraph "Data Pipeline / ETL" 
        direction TB
        subgraph "Scrapy Spiders" 
            direction TB
            SpiderFolder["spiders/"]:::etl
            Aki["aki.py"]:::etl
            Santa["santaMaria.py"]:::etl
            Supermaxi["supermaxi.py"]:::etl
            Tia["tia.py"]:::etl
        end
        Middleware["middlewares.py"]:::etl
        Pipelines["pipelines.py"]:::etl
        FilterScript["filter_food.py"]:::etl
        UploadScript["upload_recetas.py"]:::etl
    end

    %% Persistence
    subgraph "Persistence" 
        direction TB
        PrimaryDB["Postgres/Mongo"]:::db
        VectorStore["Vector Store"]:::db
    end

    %% External Services
    subgraph "External AI Services" 
        direction TB
        LLMAPI["Gemini/OpenAI API"]:::external
    end

    %% DevOps & CI
    subgraph "DevOps / CI" 
        direction TB
        DockerCompose["docker-compose.yml"]:::devops
        GHBackendCI[".github/workflows/backend-cicd.yml"]:::devops
        GHFrontendCI[".github/workflows/frontend-cicd.yml"]:::devops
        GHScrapersCI[".github/workflows/scrapers-cicd.yml"]:::devops
        Jenkinsfile["Jenkinsfile"]:::devops
    end

    %% Data Flows
    Browser -->|uses| ReactSPA
    ReactSPA -->|starts at| EntryPoint
    ReactSPA -->|loads| HTMLTemplate
    ReactSPA -->|HTTP GET/POST| Routes
    Routes -->|calls| ComparisonSvc
    Routes -->|calls| ProductSvc
    Routes -->|calls| ShoppingSvc
    Routes -->|calls| RankingSvc
    Routes -->|calls| RecipeSvc
    Routes -->|calls| EmbeddingSvc
    Routes -->|calls| UomSvc
    Routes -->|calls| CanastaSvc
    Routes -->|CRUD| PrimaryDB
    EmbeddingSvc -->|k-NN query| VectorStore
    Routes -->|calls| ChefService
    ChefService -->|API call| LLMAPI

    %% ETL Flows
    SpiderFolder --> Aki
    SpiderFolder --> Santa
    SpiderFolder --> Supermaxi
    SpiderFolder --> Tia
    Aki --> Middleware --> Pipelines --> FilterScript --> UploadScript
    UploadScript -->|writes| PrimaryDB
    FilterScript -->|writes| VectorStore
    VectorizeScript -->|updates| VectorStore

    %% DevOps arrows
    DockerCompose --> ReactSPA
    DockerCompose --> Routes
    GHBackendCI --> VectorizeScript
    GHScrapersCI --> SpiderFolder
    GHFrontendCI --> ReactSPA

    %% Click Events
    click ReactSPA "https://github.com/amwt24/ahorrec/tree/main/frontend/src/app"
    click EntryPoint "https://github.com/amwt24/ahorrec/blob/main/frontend/src/main.tsx"
    click HTMLTemplate "https://github.com/amwt24/ahorrec/blob/main/frontend/index.html"
    click Routes "https://github.com/amwt24/ahorrec/blob/main/backend/routes.py"
    click DatabaseConn "https://github.com/amwt24/ahorrec/blob/main/backend/database.py"
    click ChefService "https://github.com/amwt24/ahorrec/blob/main/backend/chef_service.py"
    click ComparisonSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/comparison_service.py"
    click EmbeddingSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/embedding_service.py"
    click ProductSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/product_service.py"
    click RankingSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/ranking_service.py"
    click RecipeSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/recipe_service.py"
    click ShoppingSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/shopping_service.py"
    click UomSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/uom_service.py"
    click CanastaSvc "https://github.com/amwt24/ahorrec/blob/main/backend/services/canasta_basica.py"
    click VectorizeScript "https://github.com/amwt24/ahorrec/blob/main/backend/scripts/vectorize_products.py"
    click SpiderFolder "https://github.com/amwt24/ahorrec/tree/main/scrapersAhorrEC/scrapersAhorrEC/spiders/"
    click Aki "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/spiders/aki.py"
    click Santa "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/spiders/santaMaria.py"
    click Supermaxi "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/spiders/supermaxi.py"
    click Tia "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/spiders/tia.py"
    click Middleware "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/middlewares.py"
    click Pipelines "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scrapersAhorrEC/pipelines.py"
    click FilterScript "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/scripts/filter_food.py"
    click UploadScript "https://github.com/amwt24/ahorrec/blob/main/scrapersAhorrEC/upload_recetas.py"
    click DockerCompose "https://github.com/amwt24/ahorrec/blob/main/docker-compose.yml"
    click GHBackendCI "https://github.com/amwt24/ahorrec/blob/main/.github/workflows/backend-cicd.yml"
    click GHFrontendCI "https://github.com/amwt24/ahorrec/blob/main/.github/workflows/frontend-cicd.yml"
    click GHScrapersCI "https://github.com/amwt24/ahorrec/blob/main/.github/workflows/scrapers-cicd.yml"
    click Jenkinsfile "https://github.com/amwt24/ahorrec/tree/main/Jenkinsfile"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef backend fill:#d4edda,stroke:#155724,color:#155724
    classDef etl fill:#fff3cd,stroke:#856404,color:#856404
    classDef db fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24
    classDef devops fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
