# ayoubchamakhi/blogrecommendation architecture

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

- Interactive diagram: https://gitdiagram.com/ayoubchamakhi/blogrecommendation
- Repository: https://github.com/ayoubchamakhi/blogrecommendation

## Overview

##### Project Type and Purpose
- This is a full-stack recommendation application with:
- A Streamlit-based frontend (app/app.py)
- A Python “backend” that handles data preprocessing, model training, inference, and evaluation (src/)
- File-based data persistence (data/raw → data/processed) and model storage (models/*.pkl)
- External dependency on the OpenAI API for personalized pitches

##### File Structure
- Top-level directories:
- app/: the Streamlit UI
- src/: core logic modules (preprocess, train, evaluate, inference, embedding_rec)
- data/: raw CSVs, Jupyter notebooks, processed pickle files
- models/: trained model artifacts (embedding_model.pkl, collaborative_model.pkl)
- Dockerfile & docker-compose.yaml: deployment configuration
- environment.yml: Python environment specification
- Notice the clear separation of concerns:
- Data ingestion & preprocessing (src/preprocess.py → data/processed)
- Model training & evaluation (src/train.py, src/evaluate.py → models/)
- Inference & recommendation logic (src/inference.py, src/embedding_rec.py)

##### Extract Key Architectural Insights from README
- Hybrid recommendation flow: content-based vs. collaborative fallback
- Streamlit UI flows: landing → guest vs. login → sidebar filters → main recommendations area
- External service: OpenAI for LLM-generated summaries
- No relational database—data lives in pickled files and in-memory Pandas DataFrames

##### Main Components and Their Interactions
1. Streamlit Frontend
- app/app.py renders UI, captures user input (login or guest) and filter settings
2. Inference Service
- src/inference.py & src/embedding_rec.py
- Loads models from models/*.pkl and processed data from data/processed
- Applies hybrid logic (content vs. collaborative)
3. OpenAI API
- External LLM call for personalized pitch generation
4. Data Layer
- data/raw → src/preprocess.py → data/processed
- Models directory for pickled artifacts
5. Training & Evaluation Pipelines
- src/train.py builds embedding and collaborative models
- src/evaluate.py runs grid search and evaluation → results/grid_search_results.csv
6. Deployment Infrastructure
- Dockerfile: containerizes the app
- docker-compose.yaml: orchestrates service with environment variables

- UI → Inference Service: user requests → recommendation results
- Inference Service → Data Layer: load processed data & models
- Inference Service → OpenAI API: HTTP call for text summaries
- Training Pipeline → Data Layer: reads raw data, writes processed data & model artifacts
- Evaluation Pipeline ↔ Models & Results: reads models & writes evaluation metrics
- Deployment Layer envelops the entire application stack

c. Architectural Patterns & Design Principles
- Layered architecture: UI, business logic (inference), data persistence, external services
- Pipeline pattern for data preprocessing and model training
- Modular code organization (one module per responsibility)
- Hybrid recommendation strategy implemented as decision logic in inference layer

d. Key Technologies & Frameworks
- Python 3.8+, Streamlit for UI
- Pandas, scikit-learn, scikit-surprise for ML pipelines
- SentenceTransformers (embedding_model.pkl) for content-based filtering
- OpenAI API for LLM summaries
- Docker & Docker Compose for containerized deployment
- Conda (environment.yml) for reproducible environments

##### Essential Elements but Keep It Readable
- Don’t overcrowd: group related src/ modules under a single “Recommendation Engine” block with sub-labels
- Hybrid logic decision point: “If user_ratings ≥ 5 → Collaborative Model else → Embedding Model”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Deployment Container
    subgraph "Docker Deployment" 
        direction TB
        Container["Docker Container"]:::conf
        subgraph "Renderable Application"
            direction TB
            UI["Streamlit UI"]:::ui
            subgraph "Recommendation Engine"
                direction TB
                Inference["Inference Service"]:::service
                Embedding["Embedding-Based Submodule"]:::service
            end
        end
        Env["environment.yml"]:::conf
        DockerfileNode["Dockerfile"]:::conf
        Compose["docker-compose.yaml"]:::conf
    end

    %% Data Pipeline
    subgraph "Data Pipeline" 
        direction TB
        RawData["Raw Data Store"]:::data
        Preprocess["Data Preprocessing Module"]:::service
        ProcessedData["Processed Data Store"]:::data
    end

    %% Model Pipeline
    subgraph "Model Lifecycle" 
        direction TB
        Training["Training Pipeline Module"]:::service
        ModelArtifacts["Model Artifacts Directory"]:::data
        Evaluation["Evaluation Pipeline Module"]:::service
        EvalResults["Evaluation Results Output"]:::data
    end

    %% External Service
    OpenAI["OpenAI API"]:::external

    %% Flows
    RawData -->|ingest| Preprocess
    Preprocess -->|output| ProcessedData
    ProcessedData -->|train data| Training
    Training -->|writes| ModelArtifacts
    ModelArtifacts -->|load for eval| Evaluation
    Evaluation -->|writes| EvalResults
    ModelArtifacts -->|load for inference| Inference
    ProcessedData -->|load for inference| Inference
    Inference -->|calls| OpenAI
    UI -->|user request| Inference

    %% Deployment flows
    UI -->|runs in| Container
    Inference -->|runs in| Container

    %% Click Events
    click UI "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/app/app.py"
    click RawData "https://github.com/ayoubchamakhi/blogrecommendation/tree/main/data/raw/"
    click ProcessedData "https://github.com/ayoubchamakhi/blogrecommendation/tree/main/data/processed/"
    click Preprocess "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/src/preprocess.py"
    click Training "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/src/train.py"
    click Evaluation "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/src/evaluate.py"
    click Inference "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/src/inference.py"
    click Embedding "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/src/embedding_rec.py"
    click ModelArtifacts "https://github.com/ayoubchamakhi/blogrecommendation/tree/main/models/"
    click EvalResults "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/results/grid_search_results.csv"
    click DockerfileNode "https://github.com/ayoubchamakhi/blogrecommendation/tree/main/Dockerfile"
    click Compose "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/docker-compose.yaml"
    click Env "https://github.com/ayoubchamakhi/blogrecommendation/blob/main/environment.yml"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#F08080,stroke:#333,stroke-width:1px
    classDef conf fill:#D3D3D3,stroke:#333,stroke-width:1px
```
