# ridabayi/e-commerce_ia_agent_for_product_recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/ridabayi/e-commerce_ia_agent_for_product_recommendation
- Repository: https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation

## Overview

##### Project Type and Purpose
- This is a cloud-native, full-stack **AI-driven recommendation system** for e-commerce platforms.
- Core goal: deliver context-aware product recommendations using Retrieval-Augmented Generation (RAG) with LLMs and a vector database, wrapped in a Flask web app and deployed on Kubernetes with full observability and CI/CD.

##### File Structure
- Top level:
- app.py – Flask entry point and HTTP routes
- Ecommerce_agent/ – core modules:
– Data_ingestion.py, Data_converter.py – ETL into vector DB
– rag_chain.py – RAG orchestration (retrieval + LLM call)
– config.py – environment and secret management
- Data/ – sample/raw data (ebay_reviews.csv)
- static/, templates/ – UI assets (CSS, HTML)
- Dockerfile, flask-deploy.yml – container + K8s manifest for the Flask service
- Grafana/, Prometheus/ – monitoring manifests (deployments, ConfigMaps)
- .github/workflows – CI/CD pipelines (lint, test, security scans)
- utils/ – logging and custom exceptions

##### Extract Insights from README
- AI stack: Groq API, Hugging Face embeddings, Datastax Astra DB (vector store)
- Deployment target: Google Cloud (VM & Kubernetes)
- Observability: Prometheus metrics + Grafana dashboards
- CI/CD: GitHub Actions with code quality and security gates

##### Main Components & Their Relationships
a.  User Interface (Browser)
→ Sends HTTP requests to the Flask service.
b.  Flask Service (Kubernetes Deployment)
– Exposes REST endpoints (app.py + routes).
– Invokes Ecommerce_agent.rag_chain to handle “ask” requests.
– Reads configuration & secrets (config.py).
c.  RAG Chain Module
– Queries the vector database (Datastax Astra) for context.
– Calls external LLM APIs (Groq, Hugging Face) to generate recommendations.
– Returns response to Flask.
d.  Data Pipeline
– Batch or ad-hoc ingestion (Data_ingestion.py → Data_converter.py → vector DB).
e.  Vector Database (Datastax Astra)
– Stores embeddings & metadata for retrieval.
f.  External AI Services
– Groq API, Hugging Face embeddings endpoint.
g.  Monitoring & Logging
– Flask and module logs (utils/logger → logs/).
– Prometheus scrapes metrics from the Flask service and K8s endpoints.
h.  CI/CD & Quality Gates
– GitHub Actions workflows run linting, tests, SonarCloud scans.
– Deployment manifests applied via “flask-deploy.yml” and K8s manifests.

##### Architectural Patterns & Design Principles
- Microservice: Flask app encapsulates all backend logic.
- RAG Pattern: separation of retrieval (vector DB) and generation (LLM).
- Infrastructure as Code: Dockerfile, K8s YAML (flask-deploy.yml, Grafana-deploy.yml, Prometheus-deploy.yml).
- Observability: metrics + logs + dashboards.
- Secure-by-design: secret management in config maps, container best practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Browser"]:::client
        Template["templates/index.html"]:::static
        Style["static/style.css"]:::static
    end
    Browser -->|"renders"| Template
    Browser -->|"loads CSS"| Style
    Browser -->|"HTTP Request"| FlaskAPI

    %% API Layer
    subgraph "API Layer"
        FlaskAPI["Flask API"]:::service
    end
    click FlaskAPI "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/app.py"

    %% Application Layer
    subgraph "Application Layer"
        RAG["RAG Chain Module"]:::service
        Config["Config & Secrets"]:::service
        Ingest["Data_ingestion.py"]:::script
        Convert["Data_converter.py"]:::script
        Logger["Logging & Exceptions"]:::service
        ExceptionNode["Custom Exceptions"]:::service
    end
    click RAG "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Ecommerce_agent/rag_chain.py"
    click Config "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Ecommerce_agent/config.py"
    click Ingest "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Ecommerce_agent/Data_ingestion.py"
    click Convert "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Ecommerce_agent/Data_converter.py"
    click Logger "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/utils/logger.py"
    click ExceptionNode "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/utils/custom_exception.py"
    FlaskAPI -->|"invoke"| RAG
    FlaskAPI -->|"load"| Config
    FlaskAPI -->|"log via"| Logger
    RAG -->|"may raise"| ExceptionNode
    Ingest -->|"uses"| Config
    Convert -->|"uses"| Config

    %% Data Layer
    subgraph "Data Layer"
        Astra[("Datastax Astra DB")]:::datastore
        Groq["Groq API"]:::external
        HF["Hugging Face Embeddings API"]:::external
    end
    RAG -->|"query"| Astra
    RAG -->|"call"| Groq
    RAG -->|"call"| HF
    Ingest -->|"ingest to"| Astra
    Convert -->|"convert to embeddings"| Astra

    %% Infrastructure & Ops
    subgraph "Infrastructure & Ops"
        subgraph "Monitoring & Observability"
            Prom["Prometheus"]:::ops
            Graf["Grafana"]:::ops
        end
        subgraph "CI/CD & Quality Gates"
            Quality[".github/workflows/quality.yml"]:::ops
            Sonar[".github/workflows/sonar.yml"]:::ops
            PytestIni["pytest.ini"]:::ops
            Pyproject["pyproject.toml"]:::ops
            SonarProj["sonar-project.properties"]:::ops
        end
        subgraph "Containerization & IaC"
            DockerfileNode["Dockerfile"]:::ops
            DeployManifest["flask-deploy.yml"]:::ops
        end
    end
    click Prom "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Prometheus/Prometheus-deploy.yml"
    click Prom "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Prometheus/Prometheus-ConfigMap.yml"
    click Graf "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/Grafana/Grafana-deploy.yml"
    click Quality "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/.github/workflows/quality.yml"
    click Sonar "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/.github/workflows/sonar.yml"
    click PytestIni "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/pytest.ini"
    click Pyproject "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/pyproject.toml"
    click SonarProj "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/sonar-project.properties"
    click DeployManifest "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/blob/main/flask-deploy.yml"
    click DockerfileNode "https://github.com/ridabayi/e-commerce_ia_agent_for_product_recommendation/tree/main/Dockerfile"

    FlaskAPI -->|"exposes metrics"| Prom
    Prom -->|"feeds metrics"| Graf
    Quality -->|"triggers build"| DockerfileNode
    Sonar -->|"triggers scan"| SonarProj
    DockerfileNode -->|"build image"| DeployManifest
    DeployManifest -->|"deploys to"| FlaskAPI

    %% Styles
    classDef client fill:#B3E5FC,stroke:#0277BD,color:#000;
    classDef service fill:#BBDEFB,stroke:#0D47A1,color:#000;
    classDef datastore fill:#C8E6C9,stroke:#2E7D32,color:#000;
    classDef external fill:#FFE0B2,stroke:#E65100,color:#000;
    classDef ops fill:#E1BEE7,stroke:#6A1B9A,color:#000;
    classDef script fill:#F5F5F5,stroke:#9E9E9E,color:#000;
    classDef static fill:#FFF9C4,stroke:#F9A825,color:#000;
```
