# oscar-defelice/recommender-systems-course architecture

> Architecture diagram of the GitHub repository oscar-defelice/recommender-systems-course, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oscar-defelice/recommender-systems-course
- Repository: https://github.com/oscar-defelice/recommender-systems-course

## Overview

##### Project type and purpose
- This is an educational code‐repository for a “Recommender Systems” course.
- It consists primarily of Jupyter notebooks illustrating successive recommendation algorithms (from non‐personalized to deep learning), plus a Python package under src/FinalProject and utility modules under src/utils, with accompanying tests.

##### File structure
- Top‐level files: README, environment.yml/requirements.txt (environment and dependency management), .github (CI/badges), LICENSE.
- src/ directory:
- A sequence of numbered notebooks (01…11) showing individual lectures.
- src/FinalProject: packaged student projects for 2023 and 2024.
- src/exercises: exercise notebooks and solutions.
- src/tests: pytest test suites for utility functions and algorithms.
- Configuration files: environment.yml (Conda), requirements.txt (pip), _config.yml (likely GitHub Pages).

##### README for additional insights
- Describes the course scope: introduction to various recommender algorithms, use of Binder for interactive execution, Python ≥3.7, pip install -r requirements.txt.

a. Main components
1. Lecture Notebooks Layer
– src/01…11: algorithm walkthroughs
– src/exercises: practice notebooks
2. Core Library Layer
– src/FinalProject: project scaffolding for students
– src/utils: shared functions and modules
3. Testing Layer
– src/tests: automated tests of utils and algorithms
4. Environment & Delivery Layer
– environment.yml / requirements.txt
– Binder badge (mybinder.org)
– GitHub repository, GitHub Pages site
b. Relationships & interactions
– Notebooks import functions from src/utils and, where applicable, src/FinalProject.
– Tests import and validate modules in src/utils and project code.
– environment files define which libraries are installed and ensure reproducibility for notebooks, tests, and projects.
– Binder leverages environment.yml to launch a live JupyterLab pointing at notebooks and code.
c. Architectural patterns & principles
– Layered architecture: presentation (notebooks), domain logic (utils + project code), verification (tests).
– Modular code: each algorithm has its encapsulated utility module.
– Separation of concerns: notebooks focus on pedagogy, utils focus on reusable implementation, tests ensure correctness.
d. Key technologies & frameworks
– Jupyter Notebook / Lab
– Python ≥3.7, pandas, numpy, scikit-learn, TensorFlow/PyTorch (depending on “DeepLove” notebook)
– pytest for test automation
– Conda/pip for environment management
– Binder for cloud deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph "Lecture Notebooks"
            N1["01.Introduction.ipynb"]:::presentation
            N2["02.Non-Personalised-Recommendation.ipynb"]:::presentation
            N3["03.KNN-basedRecommendations.ipynb"]:::presentation
            N4["04.CollaborativeFiltering.ipynb"]:::presentation
            N5["05.KMeansRecommendations.ipynb"]:::presentation
            N6["06.MatrixFactorisationAlgorithm.ipynb"]:::presentation
            N7["07.ALSMatrixFactorisationAlgorithm.ipynb"]:::presentation
            N8["08.NNEncoding.ipynb"]:::presentation
            N9["09.BayesianPersonalisedRanking.ipynb"]:::presentation
            N10["10.TransformerEncoding.ipynb"]:::presentation
            N11["11.DeepLove.ipynb"]:::presentation
        end
        subgraph "Exercise Notebooks"
            E1["BookRecommender.ipynb"]:::presentation
            E2["BookRecommender-ProposedSolution.ipynb"]:::presentation
        end
    end

    %% Core Library
    subgraph "Core Library"
        subgraph "FinalProject"
            FP1["__init__.py"]:::core
            FP2["README.md"]:::core
            FP3["project_2023/README.md"]:::core
            FP4["project_2024/README.md"]:::core
        end
        subgraph "Utils"
            U1["data_utils.py"]:::core
            U2["data_split.py"]:::core
            U3["non_pers_rec.py"]:::core
            U4["collab_filter.py"]:::core
            U5["recsysNN_utils.py"]:::core
            U6["tf_utils.py"]:::core
            U7["exceptions.py"]:::core
            subgraph "style"
                U8["colours.py"]:::core
            end
        end
    end

    %% Testing Layer
    subgraph "Testing Layer"
        T1["non_pers_tests.py"]:::tests
        T2["test_coll_filter.py"]:::tests
        T3["test_nn_content_based.py"]:::tests
    end

    %% Environment & Deployment
    subgraph "Environment & Deployment"
        G1["environment.yml"]:::env
        G2["requirements.txt"]:::env
        G3["_config.yml"]:::env
        G4[".github/FUNDING.yml"]:::env
        G5[".gitignore"]:::env
        G6["README.md"]:::env
        G7["LICENSE"]:::env
        B["Binder Badge"]:::env
    end

    %% Dependencies
    subgraph Dependencies
        N1 -->|imports| U1
        N2 -->|imports| U3
        N3 -->|imports| U4
        N4 -->|imports| U4
        N5 -->|imports| U6
        N6 -->|imports| U6
        N7 -->|imports| U6
        N8 -->|imports| U5
        N9 -->|imports| U5
        N10 -->|imports| U6
        N11 -->|imports| U5
        E1 -->|imports| U1
        E1 -->|imports| U2
        E2 -->|imports| U1
        T1 -->|validates| U3
        T2 -->|validates| U4
        T3 -->|validates| U5
        N1 -->|may use| FP1
        E1 -->|may use| FP1
        G1 -->|defines env for| N1
        G1 -->|defines env for| T1
        G1 -->|defines env for| FP1
        G1 -->|launches| B
        B -->|serves| N1
    end

    %% Click Events
    click N1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/01.Introduction.ipynb"
    click N2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/02.Non-Personalised-Recommendation.ipynb"
    click N3 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/03.KNN-basedRecommendations.ipynb"
    click N4 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/04.CollaborativeFiltering.ipynb"
    click N5 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/05.KMeansRecommendations.ipynb"
    click N6 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/06.MatrixFactorisationAlgorithm.ipynb"
    click N7 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/07.ALSMatrixFactorisationAlgorithm.ipynb"
    click N8 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/08.NNEncoding.ipynb"
    click N9 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/09.BayesianPersonalisedRanking.ipynb"
    click N10 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/10.TransformerEncoding.ipynb"
    click N11 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/11.DeepLove.ipynb"
    click E1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/exercises/BookRecommender.ipynb"
    click E2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/exercises/BookRecommender-ProposedSolution.ipynb"
    click FP1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/FinalProject/__init__.py"
    click FP2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/FinalProject/README.md"
    click FP3 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/FinalProject/project_2023/README.md"
    click FP4 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/FinalProject/project_2024/README.md"
    click U1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/data_utils.py"
    click U2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/data_split.py"
    click U3 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/non_pers_rec.py"
    click U4 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/collab_filter.py"
    click U5 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/recsysNN_utils.py"
    click U6 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/tf_utils.py"
    click U7 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/exceptions.py"
    click U8 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/utils/style/colours.py"
    click T1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/tests/non_pers_tests.py"
    click T2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/tests/test_coll_filter.py"
    click T3 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/src/tests/test_nn_content_based.py"
    click G1 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/environment.yml"
    click G2 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/requirements.txt"
    click G3 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/_config.yml"
    click G4 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/.github/FUNDING.yml"
    click G5 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/.gitignore"
    click G6 "https://github.com/oscar-defelice/recommender-systems-course/blob/main/README.md"
    click G7 "https://github.com/oscar-defelice/recommender-systems-course/tree/main/LICENSE"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085
    classDef core fill:#d4edda,stroke:#155724,color:#155724
    classDef tests fill:#fff3cd,stroke:#856404,color:#856404
    classDef env fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
