# forez0/coursework architecture

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

- Interactive diagram: https://gitdiagram.com/forez0/coursework
- Repository: https://github.com/forez0/coursework

## Overview

##### Project type and purpose
- This is a full-stack web application built on Django that implements a personalized film recommendation system.
- It uses Celery + Redis for asynchronous tasks (model training), LightFM as the recommendation algorithm, a SQLite database for user/movie data, and Django templates (and optional DRF endpoints) for the UI.

##### File structure
Top-level
- main.py, run_worker.py – entry points for web and worker processes
- film_recommender/ – root Django project (settings, ASGI/WSGI, Celery config, manage.py)
- recommender/ – the core Django app with models, views, serializers, Celery tasks, ML code and custom management commands
- ml_models/ – pickled LightFM data and model artifacts
- templates/ – Django HTML templates for UI
- db.sqlite3 – development database
- venv/ – Python virtual environment
- requirements.txt – Python dependencies

Patterns & frameworks
- Django MVC (Models, Views, Templates)
- Django REST Framework serializers and viewsets
- Celery tasks for training and batch recommendation generation
- Custom management commands (generate_test_data)
- LightFM pipeline under recommender/ml/lightfm_model.py

##### README for additional insights
- Confirms use of Redis (via Docker) as Celery broker, Celery worker invocation, and Django dev server.
- Describes high-level flow: user interactions → stored in DB → Celery-triggered model retraining → persisted model → user recommendation generation.
- Lists relevant endpoints: web UI at `/`, admin at `/admin/`, and internal DRF endpoints under `recommender/urls.py`.

a. Main components
1. User Browser / Frontend (Django Templates + optional AJAX)
2. Django Web Server (Gunicorn/Runserver)
3. SQLite Database (or RDBMS in production)
4. Celery Worker(s)
5. Redis Broker
6. LightFM Model Store (ml_models folder or object storage)
7. External TMDb API (for movie metadata)

b. Relationships & Data Flow
1. User submits rating or requests recommendations → HTTP POST/GET to Django views
2. Django writes user/movie/rating to SQLite through models
3. On schedule or admin action, Django (via Celery beat or management command) enqueues a `train_recommendation_model` task to Redis
4. Celery Worker pulls task from Redis, loads historical data, calls LightFM training logic, writes updated `.pkl` files to ml_models
5. When a user requests fresh recommendations, Django view or DRF endpoint loads pickled model, generates ranked list, stores UserRecommendation records, and returns HTML/JSON to user
6. (Optional) Django contacts TMDb API via utils.py to fetch or cache movie details

c. Architectural patterns & design principles
- Separation of concerns: Web handling in Django, asynchronous ML in Celery
- Modular ML pipeline: data prep, training, serialization isolated under recommender/ml
- Reusable management commands for data setup
- Use of DRF serializers for API clients, enabling both web and programmatic access

d. Key technologies and libraries
- Django (ORM, URL routing, templates)
- Django REST Framework (serializers, viewsets)
- Celery (task queue) + eventlet pool
- Redis (message broker)
- LightFM (recommendation algorithm)
- SQLite (dev DB)
- Docker (for Redis in local setup)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interaction
    Browser["User Browser"]:::external
    Browser -->|HTTP GET/POST| DjangoServer

    %% Web server entry
    MainPy["main.py\n(Web Server Entry)"]:::web
    click MainPy "https://github.com/forez0/coursework/blob/main/main.py"
    Browser --> DjangoServer["Gunicorn/Django Server"]:::web
    DjangoServer --> ASGIWSGI["ASGI/WSGI\n(film_recommender/asgi.py,\nwsgi.py)"]:::web
    click ASGIWSGI "https://github.com/forez0/coursework/blob/main/film_recommender/film_recommender/asgi.py"
    click ASGIWSGI "https://github.com/forez0/coursework/blob/main/film_recommender/film_recommender/wsgi.py"

    %% Django project configuration
    subgraph "Django Project Configuration"
        Settings["settings.py"]:::web
        click Settings "https://github.com/forez0/coursework/blob/main/film_recommender/film_recommender/settings.py"
        URLRouting["urls.py (root)"]:::web
        click URLRouting "https://github.com/forez0/coursework/blob/main/film_recommender/film_recommender/urls.py"
        CeleryConfig["celery.py"]:::web
        click CeleryConfig "https://github.com/forez0/coursework/blob/main/film_recommender/film_recommender/celery.py"
    end
    ASGIWSGI --> Settings
    Settings --> URLRouting
    Settings --> CeleryConfig

    %% URL routing to app
    URLRouting --> AppUrls

    AppUrls["recommender/urls.py"]:::web
    click AppUrls "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/urls.py"
    AppUrls --> Views

    %% Django App Components
    subgraph "Core Django App\n(recommender)"
        Models["models.py"]:::web
        click Models "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/models.py"
        Views["views.py"]:::web
        click Views "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/views.py"
        Serializers["serializers.py"]:::web
        click Serializers "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/serializers.py"
        Admin["admin.py"]:::web
        click Admin "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/admin.py"
        Forms["forms.py"]:::web
        click Forms "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/forms.py"
        Utils["utils.py"]:::web
        click Utils "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/utils.py"
        Filters["custom_filters.py"]:::web
        click Filters "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/templatetags/custom_filters.py"
        Templates["Django Templates"]:::web
    end
    Views -->|uses| Models
    Views -->|renders| Templates
    Views -->|serializes| Serializers
    Views -->|enqueues task| Redis
    Views -->|calls| Utils

    %% Database
    SQLite["SQLite Database"]:::db
    click SQLite "https://github.com/forez0/coursework/blob/main/film_recommender/db.sqlite3"
    Models -->|read/write| SQLite
    Tasks -->|read historical data| SQLite

    %% Async components
    subgraph "Asynchronous Layer"
        Redis["Redis Broker"]:::async
        RunWorker["run_worker.py\n(Celery Worker Entry)"]:::async
        click RunWorker "https://github.com/forez0/coursework/blob/main/film_recommender/run_worker.py"
        Tasks["tasks.py"]:::async
        click Tasks "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/tasks.py"
    end
    CeleryConfig --> Redis
    Redis --> RunWorker
    RunWorker --> Tasks

    %% ML pipeline
    subgraph "Machine Learning Pipeline"
        LightFMCode["lightfm_model.py"]:::async
        click LightFMCode "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/ml/lightfm_model.py"
        ModelStore["Model Store\n(ml_models/*.pkl)"]:::db
        click ModelStore "https://github.com/forez0/coursework/blob/main/film_recommender/ml_models/lightfm_model.pkl"
        click ModelStore "https://github.com/forez0/coursework/blob/main/film_recommender/ml_models/lightfm_data.pkl"
    end
    Tasks -->|trains/saves model| ModelStore
    Tasks -->|uses training logic| LightFMCode

    %% Recommendation flow
    Views -->|loads model| ModelStore
    Views -->|generates recommendations| Models

    %% External service
    TMDb["TMDb API"]:::external
    Utils -->|fetches metadata| TMDb

    %% Entry commands
    generateTest["generate_test_data\n(command)"]:::async
    click generateTest "https://github.com/forez0/coursework/blob/main/film_recommender/recommender/management/commands/generate_test_data.py"
    generateTest --> Models

    %% Legend
    subgraph "Legend"
        W["Blue = Web Components"]:::web
        D["Green = Databases/Storage"]:::db
        A["Orange = Async Components"]:::async
        E["Gray = External Services"]:::external
    end

    classDef web fill:#ADD8E6,stroke:#000;
    classDef db fill:#90EE90,stroke:#000;
    classDef async fill:#FFA500,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
