# aethermaker/nlp-movie-recommender-streamlit architecture

> Architecture diagram of the GitHub repository aethermaker/nlp-movie-recommender-streamlit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aethermaker/nlp-movie-recommender-streamlit
- Repository: https://github.com/aethermaker/nlp-movie-recommender-streamlit

## Overview

This is a Streamlit mood-based movie recommender. A user enters a mood or plot description; the app loads movie data and a sentence model, requests similarity-ranked recommendations, then displays movie details and fetches posters from TMDB. The sampled code shows the recommendation and poster-fetching flow; the README documents the precomputed embeddings and metadata. External library internals are not represented.

Main entry points: [`app.py`](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/app.py) (Streamlit app), [`recommender_logic.py`](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py) (Query matching), [`movie_embeddings.npy`](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_embeddings.npy) (Movie embeddings), [`movie_metadata.parquet`](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_metadata.parquet) (Movie metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Streamlit app<br/>[app.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_recommend["Query matching"]
  node_model_loader["Model loading"]
end

subgraph group_catalog["Movie data"]
  node_data_loader["Data loading"]
  node_embeddings[("Movie embeddings")]
  node_metadata[("Movie metadata")]
end

subgraph group_integrations["External services"]
  node_poster_fetcher["Poster details"]
  node_sentence_transformers["Sentence Transformers"]
  node_similarity["Cosine similarity"]
  node_tmdb["TMDB API"]
end

node_user(("Movie seeker"))

node_user -->|"enters query"| node_app
node_app -->|"loads model"| node_model_loader
node_app -->|"loads data"| node_data_loader
node_data_loader -->|"reads vectors"| node_embeddings
node_data_loader -->|"reads metadata"| node_metadata
node_app -->|"requests matches"| node_recommend
node_recommend -->|"encodes query"| node_sentence_transformers
node_model_loader -->|"loads model"| node_sentence_transformers
node_recommend -->|"scores vectors"| node_similarity
node_app -->|"fetches details"| node_poster_fetcher
node_poster_fetcher -->|"requests details"| node_tmdb
node_app -->|"displays results"| node_user

click node_app "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/app.py"
click node_recommend "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py"
click node_model_loader "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py"
click node_data_loader "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py"
click node_embeddings "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_embeddings.npy"
click node_metadata "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_metadata.parquet"
click node_poster_fetcher "https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py"

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_app toneBlue
class node_recommend,node_model_loader toneAmber
class node_data_loader,node_embeddings,node_metadata toneMint
class node_poster_fetcher,node_sentence_transformers,node_similarity,node_tmdb toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Streamlit app](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/app.py): `app.py`

### Recommendation

- [Query matching](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py): `recommender_logic.py`
- [Model loading](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py): `recommender_logic.py`

### Movie data

- [Data loading](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py): `recommender_logic.py`
- [Movie embeddings](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_embeddings.npy): `movie_embeddings.npy`
- [Movie metadata](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/movie_metadata.parquet): `movie_metadata.parquet`

### External services

- [Poster details](https://github.com/aethermaker/nlp-movie-recommender-streamlit/blob/mehran/recommender_logic.py): `recommender_logic.py`
- **Sentence Transformers**
- **Cosine similarity**
- **TMDB API**

### Other components

- **Movie seeker**

## Connections

- Movie seeker → Streamlit app: enters query (evidence: `README.md`)
- Streamlit app → Model loading: loads model (evidence: `app.py`)
- Streamlit app → Data loading: loads data (evidence: `app.py`)
- Data loading → Movie embeddings: reads vectors (evidence: `recommender_logic.py`)
- Data loading → Movie metadata: reads metadata (evidence: `recommender_logic.py`)
- Streamlit app → Query matching: requests matches (evidence: `app.py`)
- Query matching → Sentence Transformers: encodes query (evidence: `recommender_logic.py`)
- Model loading → Sentence Transformers: loads model (evidence: `recommender_logic.py`)
- Query matching → Cosine similarity: scores vectors (evidence: `recommender_logic.py`)
- Streamlit app → Poster details: fetches details (evidence: `app.py`)
- Poster details → TMDB API: requests details (evidence: `recommender_logic.py`)
- Streamlit app → Movie seeker: displays results (evidence: `app.py`)
