# souhaib-ia/recommendation-engine architecture

> Architecture diagram of the GitHub repository souhaib-ia/recommendation-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/souhaib-ia/recommendation-engine
- Repository: https://github.com/souhaib-ia/recommendation-engine

## Overview

##### Project Type and Purpose
- This is the **backend microservice** of a full-stack Movie Recommendation System. It exposes a REST API (Flask) that computes content-based movie suggestions (cosine similarity) and persists/reads data from a Supabase (PostgreSQL) database. It is deployed as an Azure Web App and packaged via GitHub Actions.

##### File Structure
- Top-Level Files:
- `serve.py` (entrypoint for Flask)
- `requirements.txt` (Python deps)
- `Procfile` (Azure/Gunicorn startup)
- `.github/workflows/azure-webapps-python.yml` (CI/CD to Azure)
- Implied Directories (from README):
- `utils/` (data processing, feature extraction)
- `models/` (cosine similarity, pre-trained artifacts)
- `artifacts/` (precomputed matrices, uploads to Azure Storage)

##### README for Additional Insights
- Technology stack: Flask, Scikit-Learn, Supabase, Azure Web Apps
- API Endpoints: `/recommend`
- Deployment: GitHub Actions → Azure Web App, uses Gunicorn via `Procfile`

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client / Frontend"]:::external
    TMDB["TMDB API"]:::external
    GitHub["GitHub Actions CI/CD"]:::external

    subgraph "Backend Microservice"
        direction TB
        API["Flask Recommendation API"]:::compute
        Serve["serve.py"]:::compute
        Req["requirements.txt"]:::compute
        Proc["Procfile"]:::compute
        README["README.md"]:::compute

        subgraph "API Modules"
            direction TB
            Utils["utils/"]:::compute
            Models["models/"]:::compute
            Artifacts["artifacts/"]:::compute
        end

        Gunicorn["Gunicorn"]:::compute
    end

    Supabase["Supabase (PostgreSQL)"]:::database
    Blob["Azure Blob Storage"]:::database
    AzureApp["Azure Web App"]:::compute

    Client -->|"POST /recommend"| API
    API -->|"load artifacts"| Artifacts
    API -->|"process data"| Utils
    Utils -->|"feature extraction"| Models
    API -->|"query data"| Supabase
    API -->|"fetch artifacts"| Blob
    API -->|"call metadata"| TMDB
    API -->|"return JSON"| Client

    GitHub -->|"deploy code"| AzureApp
    AzureApp -->|"hosts API"| API
    AzureApp -->|"runs via"| Gunicorn

    click Serve "https://github.com/souhaib-ia/recommendation-engine/blob/main/serve.py"
    click Req "https://github.com/souhaib-ia/recommendation-engine/blob/main/requirements.txt"
    click Proc "https://github.com/souhaib-ia/recommendation-engine/tree/main/Procfile"
    click README "https://github.com/souhaib-ia/recommendation-engine/blob/main/README.md"
    click GitHub "https://github.com/souhaib-ia/recommendation-engine/blob/main/.github/workflows/azure-webapps-python.yml"

    classDef compute fill:#e0f7e9,stroke:#34a853,stroke-width:2px
    classDef database fill:#e8f0fe,stroke:#4285f4,stroke-width:2px
    classDef external fill:#fff4e5,stroke:#f9ab00,stroke-width:2px
```
