# oniichan-maulik/filmy-duniya architecture

> Architecture diagram of the GitHub repository oniichan-maulik/filmy-duniya, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oniichan-maulik/filmy-duniya
- Repository: https://github.com/oniichan-maulik/filmy-duniya

## Overview

Filmy Duniya combines a Streamlit movie-discovery interface with a FastAPI backend. Its main workflow is to acquire a TMDB movie catalog, build a local recommendation index, and return title-, genre-, or mood-oriented suggestions; users can also record feedback that informs personalized ranking. Separate capabilities include webcam mood detection and feedback-data import. The graph reflects README documentation and indexed or excerpted source references; some UI/API wiring and storage details were not fully sampled.

Main entry points: [`src/recommender.py`](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/recommender.py) (Recommendation engine), [`web/app_streamlit.py`](https://github.com/oniichan-maulik/filmy-duniya/blob/main/web/app_streamlit.py) (Streamlit app), [`src/api.py`](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/api.py) (FastAPI service), [`src/scraper.py`](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/scraper.py) (TMDB scraper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience and API"]
  node_streamlit["Streamlit app<br/>[app_streamlit.py]"]
  node_api["FastAPI service<br/>[api.py]"]
end

subgraph group_catalog["Catalog ingestion and data"]
  node_scraper["TMDB scraper<br/>[scraper.py]"]
  node_catalog_csv[("Movie catalog")]
  node_data_loader["Catalog loader<br/>[data_loader.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_recommendations["Recommendation engine"]
  node_preprocess["Text preprocessing<br/>[preprocess.py]"]
  node_vectorize["Vectorization<br/>[vectorize.py]"]
  node_similarity["Similarity index<br/>[similarity.py]"]
  node_recommender["Recommendation engine<br/>[recommender.py]"]
end

subgraph group_personalization["Feedback and personalization"]
  node_user_store["User feedback store<br/>[user_store.py]"]
  node_feedback_events[("Feedback events")]
  node_feedback_importer["Feedback importer"]
  node_personalizer["Personalization model"]
  node_model_artifact[("Model artifact")]
end

subgraph group_mood["Mood detection"]
  node_mood_detector["Webcam mood detector"]
  node_onnx_models["ONNX models"]
end

node_viewer(("Movie viewer"))
node_tmdb{{"TMDB"}}

node_viewer -->|"explores movies"| node_streamlit
node_streamlit -->|"requests recommendations"| node_api
node_api -->|"refreshes catalog"| node_scraper
node_scraper -->|"fetches popular titles"| node_tmdb
node_scraper -->|"persists movie data"| node_catalog_csv
node_api -->|"loads catalog"| node_data_loader
node_data_loader -.->|"reads catalog"| node_catalog_csv
node_api -->|"builds recommendation index"| node_recommender
node_recommender -->|"loads movies"| node_data_loader
node_recommender -->|"builds text features"| node_preprocess
node_recommender -->|"creates vectors"| node_vectorize
node_recommender -->|"computes similarity"| node_similarity
node_recommender -->|"reads settings"| node_config
node_streamlit -.->|"requests suggestions"| node_recommender
node_streamlit -.->|"records feedback"| node_user_store
node_user_store -->|"appends events"| node_feedback_events
node_feedback_importer -->|"imports interactions"| node_feedback_events
node_personalizer -->|"trains from events"| node_feedback_events
node_personalizer -->|"saves model"| node_model_artifact
node_user_store -->|"scores candidates"| node_personalizer
node_streamlit -->|"requests mood scan"| node_mood_detector
node_api -->|"analyzes frames"| node_mood_detector
node_mood_detector -->|"loads weights"| node_onnx_models

click node_streamlit "https://github.com/oniichan-maulik/filmy-duniya/blob/main/web/app_streamlit.py"
click node_api "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/api.py"
click node_scraper "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/scraper.py"
click node_data_loader "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/data_loader.py"
click node_config "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/config.py"
click node_preprocess "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/preprocess.py"
click node_vectorize "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/vectorize.py"
click node_similarity "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/similarity.py"
click node_recommender "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/recommender.py"
click node_user_store "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/user_store.py"
click node_feedback_importer "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/import_feedback_events.py"
click node_personalizer "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/personalization_model.py"
click node_mood_detector "https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/emotion_detection.py"
click node_onnx_models "https://github.com/oniichan-maulik/filmy-duniya/tree/main/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit,node_api,node_viewer toneBlue
class node_scraper,node_catalog_csv,node_data_loader,node_config toneAmber
class node_preprocess,node_vectorize,node_similarity,node_recommender toneMint
class node_user_store,node_feedback_events,node_feedback_importer,node_personalizer,node_model_artifact toneRose
class node_mood_detector,node_onnx_models,node_tmdb toneIndigo
```

## Components

### User experience and API

- [Streamlit app](https://github.com/oniichan-maulik/filmy-duniya/blob/main/web/app_streamlit.py): `web/app_streamlit.py`
- [FastAPI service](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/api.py): `src/api.py`

### Catalog ingestion and data

- [TMDB scraper](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/scraper.py): `src/scraper.py`
- **Movie catalog**
- [Catalog loader](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/data_loader.py): `src/data_loader.py`
- [Configuration](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/config.py): `src/config.py`

### Recommendation engine

- [Text preprocessing](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/preprocess.py): `src/preprocess.py`
- [Vectorization](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/vectorize.py): `src/vectorize.py`
- [Similarity index](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/similarity.py): `src/similarity.py`
- [Recommendation engine](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/recommender.py): `src/recommender.py`

### Feedback and personalization

- [User feedback store](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/user_store.py): `src/user_store.py`
- **Feedback events**
- [Feedback importer](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/import_feedback_events.py): `src/import_feedback_events.py`
- [Personalization model](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/personalization_model.py): `src/personalization_model.py`
- **Model artifact**

### Mood detection

- [Webcam mood detector](https://github.com/oniichan-maulik/filmy-duniya/blob/main/src/emotion_detection.py): `src/emotion_detection.py`
- [ONNX models](https://github.com/oniichan-maulik/filmy-duniya/tree/main/models): `models`

### Other components

- **Movie viewer**
- **TMDB**

## Connections

- Movie viewer → Streamlit app: explores movies (evidence: `README.md`)
- Streamlit app → FastAPI service: requests recommendations (evidence: `README.md`)
- FastAPI service → TMDB scraper: refreshes catalog (evidence: `src/api.py`)
- TMDB scraper → TMDB: fetches popular titles (evidence: `src/scraper.py`)
- TMDB scraper → Movie catalog: persists movie data (evidence: `src/scraper.py`)
- FastAPI service → Catalog loader: loads catalog (evidence: `src/api.py`)
- Catalog loader → Movie catalog: reads catalog
- FastAPI service → Recommendation engine: builds recommendation index (evidence: `src/api.py`)
- Recommendation engine → Catalog loader: loads movies (evidence: `src/recommender.py`)
- Recommendation engine → Text preprocessing: builds text features (evidence: `src/recommender.py`)
- Recommendation engine → Vectorization: creates vectors (evidence: `src/recommender.py`)
- Recommendation engine → Similarity index: computes similarity (evidence: `src/recommender.py`)
- Recommendation engine → Configuration: reads settings (evidence: `src/recommender.py`)
- Streamlit app → Recommendation engine: requests suggestions (evidence: `web/app_streamlit.py`)
- Streamlit app → User feedback store: records feedback (evidence: `web/app_streamlit.py`)
- User feedback store → Feedback events: appends events (evidence: `src/user_store.py`)
- Feedback importer → Feedback events: imports interactions (evidence: `README.md`)
- Personalization model → Feedback events: trains from events (evidence: `README.md`)
- Personalization model → Model artifact: saves model (evidence: `src/personalization_model.py`)
- User feedback store → Personalization model: scores candidates (evidence: `src/user_store.py`)
- Streamlit app → Webcam mood detector: requests mood scan (evidence: `web/app_streamlit.py`)
- FastAPI service → Webcam mood detector: analyzes frames (evidence: `src/api.py`)
- Webcam mood detector → ONNX models: loads weights (evidence: `src/emotion_detection.py`)