# gaurav-163/news-recommender-system architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav-163/news-recommender-system
- Repository: https://github.com/gaurav-163/news-recommender-system

## Overview

##### Project type and purpose
- This is a lightweight full-stack application with a single Flask/Gradio web front end, a machine-learning pipeline for embeddings, and a FAISS similarity search back end.
- Its purpose: accept a user’s news query, embed it, search for similar articles, and display recommendations.

##### File structure
- Top-level scripts:
- app.py – orchestrates the web UI and ML pipeline
- Articles.py – likely holds or loads the news article corpus
- Config/manifests:
- requirements.txt / pyproject.toml
- Web assets:
- templates/index.html
- static/styles.css
- No dedicated database directory—FAISS is used as the index store.

##### README insights
- Core libraries: Flask (or Gradio), sentence-transformers, FAISS, numpy
- Steps: preprocess → build FAISS index → encode query → search → display results
- Future scope: integrate live feeds, deploy via Flask/FastAPI

a. User Interface Layer
- Browser (static + templates served by Flask) or Gradio widget
- Endpoint: HTTP GET/POST or Gradio API call
b. Backend / Application Layer
- Flask application (app.py)
- Request handler: receives query, calls embedding service, queries FAISS, formats response
c. Embedding Service
- Sentence Transformer model: loads pre-trained weights, computes embeddings for articles and queries
d. FAISS Index Store
- FAISS index: stores article embeddings, supports nearest-neighbor search
e. Data Layer
- Articles.py or flat files: initial corpus of news articles
- (Future) Live Feed Ingestor microservice or scheduled loader
f. External Dependencies
- Docker/hosting (if deployed)
- Libraries: sentence-transformers, faiss-cpu, flask, numpy

##### Architectural patterns & design principles
- Separation of concerns: UI vs. business logic vs. ML vs. storage
- Modular pipeline: data ingestion → embedding → indexing → querying
- Stateless web layer + in-memory (or persisted) FAISS index

##### Elements
- Component labels: “Browser / Gradio UI”, “Flask App (app.py)”, “Sentence Transformer Model”, “FAISS Index”, “Articles Corpus”
- Optional: a note on future enhancements (live feed ingestor, deployment layer)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User((User)):::user

    %% UI Layer
    subgraph "UI Layer"
        HTML["templates/index.html"]:::frontend
        CSS["static/styles.css"]:::frontend
        UI["Browser / Gradio UI"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        App["Flask App (app.py)"]:::app
    end

    %% ML Layer
    subgraph "ML Layer"
        Model["Sentence Transformer Model"]:::ml
    end

    %% Storage Layer
    subgraph "Storage Layer"
        Articles["Articles Corpus\n(Articles.py)"]:::storage
        FAISS["FAISS Index"]:::storage
    end

    %% External & Configs
    subgraph "External & Configurations"
        Req["requirements.txt"]:::external
        Pyproj["pyproject.toml"]:::external
        Readme["Readme.md"]:::external
    end

    %% Initialization Flow
    App -->|"preprocess & build index"| Model
    Model -->|"store embeddings"| FAISS

    %% Query Flow
    User -->|"submit query"| UI
    UI -->|"HTTP GET/POST or Gradio API Call"| App
    App -->|"encode(query)"| Model
    App -->|"search(nearest_neighbors)"| FAISS
    FAISS -->|"results"| App
    App -->|"render(template)"| UI
    UI -->|"display results"| User

    %% Data Source
    Articles -->|"load corpus"| Model

    %% Dependencies Usage
    App --- Req
    App --- Pyproj
    App --- Readme
    Model --- Req
    FAISS --- Req

    %% Click Events
    click HTML "https://github.com/gaurav-163/news-recommender-system/blob/main/templates/index.html"
    click CSS "https://github.com/gaurav-163/news-recommender-system/blob/main/static/styles.css"
    click App "https://github.com/gaurav-163/news-recommender-system/blob/main/app.py"
    click Articles "https://github.com/gaurav-163/news-recommender-system/blob/main/Articles.py"
    click Req "https://github.com/gaurav-163/news-recommender-system/blob/main/requirements.txt"
    click Pyproj "https://github.com/gaurav-163/news-recommender-system/blob/main/pyproject.toml"
    click Readme "https://github.com/gaurav-163/news-recommender-system/blob/main/Readme.md"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:1px
    classDef app fill:#f0e68c,stroke:#000,stroke-width:1px
    classDef ml fill:#90ee90,stroke:#000,stroke-width:1px
    classDef storage fill:#ffcc80,stroke:#000,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#000,stroke-width:1px
    classDef user fill:#ffffff,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
