# dangdailoi/recommendation-system architecture

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

- Interactive diagram: https://gitdiagram.com/dangdailoi/recommendation-system
- Repository: https://github.com/dangdailoi/recommendation-system

## Overview

##### Project type and purpose
- This is a full-stack web application (Flask) that provides product recommendations and search capabilities for an e-commerce site.
- It implements deep learning (CNN‐based content filtering) and reinforcement learning (Deep Q-Learning) for personalization, plus text and image search (Whoosh, FAISS).

##### File structure
- Top-level:
- app.py – Flask entrypoint/routes
- db/ – data persistence (SQLAlchemy ORM, raw SQL schema)
- recommendation_system/ – ML-based recommender modules (dcbf.py, dqn.py)
- search_engine/ – search modules (text_search.py, image_search.py, Whoosh schema)
- static/ & templates/ – UI assets (CSS, JS, HTML)
- model.json – configuration for model paths or parameters
- Patterns:
- MVC-style division: templates+static = View, app.py = Controller, db & ML modules = Model & Services
- ML components separated into their own packages
- Config files (requirements.txt, model.json) and scripts (db/dbo.sql)

##### Key insights from README
- Application flow: user → Flask app → (search_engine OR recommendation_system) → database & ML model files
- Dependencies: Flask, SQLAlchemy, TensorFlow, FAISS, Whoosh
- External assets: large pre-trained models stored externally (`.h5`, `.npy`)

##### Main components
a. Frontend (Browser):
- HTML templates + static CSS/JS
b. Web Server (Flask App):
- app.py (routes, REST endpoints)
- model.json (config loader)
c. Data Layer:
- Relational DB (SQLAlchemy ORM via db/dbo.py)
- Raw SQL scripts (db/dbo.sql)
d. Search Engine Services:
- Text search (Whoosh via search_engine/text_search.py + schema.py)
- Image search (FAISS or custom via search_engine/image_search.py)
e. Recommendation Services:
- Deep content-based filtering (recommendation_system/dcbf.py)
- Deep Q-Learning RL recommender (recommendation_system/dqn.py)
- Pre-trained model storage (`.h5`, `.npy`, user‐provided)
f. External & Auxiliary:
- Model storage on file system or object storage
- Optional data crawl/ingestion component

##### Relationships & interactions
- User → (HTTP) → Flask App
- Flask App routes
- “/search” → invokes search_engine modules → queries Whoosh index or FAISS index
- “/recommend” → invokes recommendation_system modules → loads models → computes suggestions
- Database reads/writes for user profiles, product metadata, logs
- Flask App ↔ Database via SQLAlchemy
- Search Engines ↔ Search Index (Whoosh files or FAISS vectors on disk)
- Recommenders ↔ Model files on disk

##### Architectural patterns & principles
- Layered Architecture: Presentation → Application → Services (Search, Recommendation) → Data
- Separation of concerns: distinct packages for search vs. recommendation vs. persistence
- Dependency injection/config via model.json
- Stateless web server; stateful data & index storage

##### Detail
- Both text and image search flows.
- How user interactions (search vs. recommendation) trigger different services.
- Where configuration (model.json) is read.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Templates["HTML Templates"]:::presentation
        Static["Static Assets (CSS/JS)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        FlaskApp["Flask App\n(app.py)"]:::service
        Config["Config\n(model.json)"]:::config
        Requirements["Dependencies\n(requirements.txt)"]:::config
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        subgraph "Search Engine"
            direction TB
            TextSearch["Text Search\n(text_search.py)"]:::service
            Schema["Whoosh Schema\n(schema.py)"]:::service
            ImageSearch["Image Search\n(image_search.py)"]:::service
            SearchInit["__init__.py"]:::service
        end
        subgraph "Recommendation Engine"
            direction TB
            DCBF["Content-based Model\n(dcbf.py)"]:::service
            DQN["DQN Model\n(dqn.py)"]:::service
            RecInit["__init__.py"]:::service
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB[(Relational DB)]:::data
        SQLScript["SQL Schema\n(dbo.sql)"]:::data
        WhooshIndex[(Whoosh Index)]:::data
        FAISSIndex[(FAISS Index)]:::data
        ModelFiles[(Model Files)]:::data
    end

    %% Connections
    Templates -->|renders| FlaskApp
    Static -->|assets| FlaskApp
    FlaskApp -->|"reads config"| Config
    FlaskApp -->|"loads deps"| Requirements
    FlaskApp -->|"/search"| TextSearch
    FlaskApp -->|"/search"| ImageSearch
    FlaskApp -->|"/recommend"| DCBF
    FlaskApp -->|"/recommend"| DQN
    FlaskApp -->|ORM| DB
    FlaskApp -->|executes| SQLScript

    TextSearch -->|indexes| WhooshIndex
    Schema -->|defines| WhooshIndex
    ImageSearch -->|queries| FAISSIndex

    DCBF -->|loads model| ModelFiles
    DQN -->|loads model| ModelFiles

    %% Click Events
    click Templates "https://github.com/dangdailoi/recommendation-system/tree/main/templates/"
    click Static "https://github.com/dangdailoi/recommendation-system/tree/main/static/"
    click FlaskApp "https://github.com/dangdailoi/recommendation-system/blob/main/app.py"
    click Config "https://github.com/dangdailoi/recommendation-system/blob/main/model.json"
    click Requirements "https://github.com/dangdailoi/recommendation-system/blob/main/requirements.txt"
    click TextSearch "https://github.com/dangdailoi/recommendation-system/blob/main/search_engine/text_search.py"
    click Schema "https://github.com/dangdailoi/recommendation-system/blob/main/search_engine/schema.py"
    click ImageSearch "https://github.com/dangdailoi/recommendation-system/blob/main/search_engine/image_search.py"
    click SearchInit "https://github.com/dangdailoi/recommendation-system/blob/main/search_engine/__init__.py"
    click DCBF "https://github.com/dangdailoi/recommendation-system/blob/main/recommendation_system/dcbf.py"
    click DQN "https://github.com/dangdailoi/recommendation-system/blob/main/recommendation_system/dqn.py"
    click RecInit "https://github.com/dangdailoi/recommendation-system/blob/main/recommendation_system/__init__.py"
    click DB "https://github.com/dangdailoi/recommendation-system/blob/main/db/dbo.py"
    click SQLScript "https://github.com/dangdailoi/recommendation-system/blob/main/db/dbo.sql"

    %% Styles
    classDef presentation fill:#D0E6FA,stroke:#333,stroke-width:1px
    classDef service fill:#D5F5D5,stroke:#333,stroke-width:1px
    classDef data fill:#FDEBD0,stroke:#333,stroke-width:1px
    classDef config fill:#FCF3CF,stroke:#333,stroke-width:1px
```
