# sinnytk/recommander architecture

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

- Interactive diagram: https://gitdiagram.com/sinnytk/recommander
- Repository: https://github.com/sinnytk/recommander

## Overview

##### Project type and purpose
- ReCommander is a full-stack web application built with Django that delivers content-based movie recommendations using a Random Forest model (scikit-learn).
- Its primary function is to serve a survey UI (asking users for favorite and watched movies) and compute recommendations from a pre-trained RF model querying a Postgres database populated from the MovieLens dataset.

##### File structure
- Top-level:
- Pipfile & Pipfile.lock → Python dependencies via pipenv
- manage.py → Django command-line entry point
- Two Django apps under `recommander/`:
– `recommander/` (project settings, URL router, WSGI, base templates/static)
– `survey/` (survey views, URLconf, models.py, migrations, templates/static for favorite/watched/movies)
- Static & templates directories follow Django’s MVC pattern (Templates in `/templates`, static assets in `/static`).
- `survey/models.py` defines how survey responses and Movie data map to the DB (Postgres).
- No explicit training script here but “proximity matrix logic” and RF model likely run offline or via a Django management command.

##### README
- Tech stack: Django, scikit-learn (Random Forest), Postgres, MovieLens dataset.
- Workflow hints:
1. Denormalize and select features from raw dataset → populate Postgres
2. Survey web app collects user preferences
3. Proximity matrix / RF logic computes recommendations
4. Serve results via Django views & templates

a. Main components
- User Browser (Client)
- Django Web Server (WSGI application)
- URL Router → `survey.views` → business logic
- Templates & Static File Server
- Database (Postgres) storing denormalized MovieLens data & survey responses
- ML Component
- Offline Trainer (Python/Scikit-Learn script or management command)
- Prediction Engine (RF model loaded in memory for inference)
- External Dataset Source (MovieLens CSVs, IMDbPY API)
b. Relationships & interactions
- User submits survey → HTTP POST → Django view
- View retrieves user input & DB data → calls Prediction Engine → fetches top-N recommendations → writes/reads survey instance in DB → renders HTML
- Offline Trainer periodically reads raw CSVs, performs feature selection, trains RF model → persists serialized model (e.g., pickle) to a model store or file system
- At startup or on demand, Prediction Engine loads the serialized model
c. Architectural patterns/design principles
- MVC (Django): Models ←→ Views ←→ Templates
- Separation of concerns:
- Presentation layer (HTML/CSS/JS in templates/static)
- Business logic layer (views and RF inference)
- Data layer (Django ORM & Postgres)
- Offline vs. online processing: training (batch) vs. inference (real-time)
d. Key technologies
- Django (URL routing, ORM, templating)
- Postgres (persistent storage)
- Scikit-Learn Random Forest (ML algorithm)
- pipenv (environment & dependency management)
- MovieLens dataset (CSV source)
- IMDbPY (optional enrichment via API)

##### Detailed Checklist
- Offline vs. online distinction is visually clear

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend (UI)"
        UB["User Browser"]:::frontend
    end

    subgraph "Static & Templates"
        FavTemplate["favorite.html"]:::frontend
        WatchedTemplate["watched.html"]:::frontend
        MoviesTemplate["movies.html"]:::frontend
        BaseTemplate["base.html"]:::frontend
        FavCSS["favorite.css"]:::frontend
        FavJS["favorite.js"]:::frontend
        WatchedCSS["watched.css"]:::frontend
        BaseCSS["base.css"]:::frontend
    end

    subgraph "Django Application"
        Manage["manage.py"]:::backend
        RouterProject["Project URL Router"]:::backend
        RouterSurvey["Survey URL Router"]:::backend
        Views["Survey Views"]:::backend
        Models["Survey Models"]:::backend
        Admin["Survey Admin"]:::backend
    end

    subgraph "Database"
        DB[(Postgres)]:::database
    end

    subgraph "ML Pipeline"
        MLData["MovieLens CSVs"]:::external
        Trainer["Offline Trainer"]:::ml
        ModelStore["model.pkl"]:::ml
        Predictor["Inference Engine"]:::ml
    end

    %% Online Request Flow
    UB -->|"GET /survey/"| RouterProject
    RouterProject --> RouterSurvey
    RouterSurvey --> Views
    Views -->|"SELECT * FROM movies"| DB
    Views --> Predictor
    Predictor --> ModelStore
    Views -->|"Render recommendations"| MoviesTemplate
    MoviesTemplate --> UB

    UB -->|"POST /survey/results/"| RouterProject
    RouterProject --> RouterSurvey
    RouterSurvey --> Views

    %% Offline Training Flow
    MLData -->|"TRAIN on CSVs"| Trainer
    Trainer -->|"Populate DB"| DB
    Trainer -->|"Save model"| ModelStore

    %% Click Events
    click Manage "https://github.com/sinnytk/recommander/blob/master/recommander/manage.py"
    click RouterProject "https://github.com/sinnytk/recommander/blob/master/recommander/recommander/urls.py"
    click RouterSurvey "https://github.com/sinnytk/recommander/blob/master/recommander/survey/urls.py"
    click Views "https://github.com/sinnytk/recommander/blob/master/recommander/survey/views.py"
    click Models "https://github.com/sinnytk/recommander/blob/master/recommander/survey/models.py"
    click Admin "https://github.com/sinnytk/recommander/blob/master/recommander/survey/admin.py"
    click FavTemplate "https://github.com/sinnytk/recommander/blob/master/recommander/survey/templates/survey/favorite.html"
    click WatchedTemplate "https://github.com/sinnytk/recommander/blob/master/recommander/survey/templates/survey/watched.html"
    click MoviesTemplate "https://github.com/sinnytk/recommander/blob/master/recommander/survey/templates/survey/movies.html"
    click BaseTemplate "https://github.com/sinnytk/recommander/blob/master/recommander/recommander/templates/recommander/base.html"
    click FavCSS "https://github.com/sinnytk/recommander/blob/master/recommander/survey/static/survey/favorite.css"
    click FavJS "https://github.com/sinnytk/recommander/blob/master/recommander/survey/static/survey/favorite.js"
    click WatchedCSS "https://github.com/sinnytk/recommander/blob/master/recommander/survey/static/survey/watched.css"
    click BaseCSS "https://github.com/sinnytk/recommander/blob/master/recommander/recommander/static/recommander/base.css"

    classDef frontend fill:#e0f7fa,stroke:#006064
    classDef backend fill:#e8f5e9,stroke:#1b5e20
    classDef database fill:#ffe0b2,stroke:#e65100
    classDef ml fill:#f3e5f5,stroke:#6a1b9a
    classDef external fill:#eeeeee,stroke:#757575
```
