This project is a mood-based movie recommendation web app that helps users find films based on how they feel, what genres they enjoy, and the kind of experience they want. Instead of making people scroll endlessly through streaming platforms, I built a system that turns human emotion into useful movie suggestions.
I wanted to build something practical, creative, and relatable. A lot of recommendation tools only ask for genre, but real people often do not think that way. Most people say things like, “I want something exciting,” “I need a feel-good movie,” or “I want something deep but not sad.” That inspired me to create a recommendation system that starts with emotion, not just category.
People waste time browsing because streaming platforms often give too many options without enough personal context. Even when a platform recommends something, the user may not understand why it was chosen. My goal was to reduce decision fatigue and make movie discovery feel more human.
In simple terms: I built a tool that listens to what kind of mood the user is in and then helps them find movies that match that feeling.
This is not just a genre filter. It is a hybrid recommendation idea that combines movie metadata with AI-driven interpretation. That means the system does more than read direct keywords. It tries to understand the user’s intent, emotional tone, and viewing preference before searching for matches.
That makes the experience feel more like talking to a smart assistant than clicking random filters.
I designed this project so that each part had a clear job. That is important because good software is not just about using tools. It is about knowing why each tool is there.
I used The Movie Database API to pull movie information such as titles, genres, overviews, ratings, release details, and other metadata that helps compare one movie against another.
I used an LLM to help interpret free-form user input. This was useful because users may describe the same mood in very different ways. AI helped turn those natural phrases into cleaner search and recommendation signals.
I built recommendation logic that sits between the user input and the final result. This layer decides how to rank or narrow movies based on mood, genre preferences, and other filters.
The front end gives users a simple way to describe what they want. The focus was making the app feel easy and conversational instead of technical.
The backend handles requests, communicates with external APIs, cleans up the returned data, and sends a structured result back to the user.
The main idea behind the app is recommendation quality. I focused on how to move from raw data to a result that actually feels relevant to a person.
Below is the full flow of what happens when someone uses the app. I am explaining it in a simple way first, then I break each part down in more detail.
The app takes human language, turns it into structured search ideas, fetches movie candidates, evaluates them, and returns the best matches.
The user enters a mood, preferred genres, or a short description of the type of movie they want.
The system turns that messy human wording into clearer recommendation signals.
The app queries TMDB to retrieve possible movie matches and supporting metadata.
The candidates are compared and scored using mood fit, genre relevance, and overall quality.
The user receives recommended movies plus an explanation of why those movies match.
This is the part of the case study that explains the project like a real build process, not just a final summary.
Before thinking deeply about code, I thought about the actual user. I asked myself: what would make this useful in real life? I realized most people do not always know the exact movie title they want. They usually know the feeling they want.
So I designed the app around inputs like mood, vibe, or genre preference. That made the project more human-centered. Instead of forcing users to think like a database, the app meets them where they are.
To recommend movies well, the system needed rich movie data. That includes things like title, genre, description, release year, popularity, and ratings. I used TMDB because it provides structured movie information that is useful for building recommendation logic.
In non-technical terms, TMDB acted like the movie library behind the app. My system could not recommend anything without first having a reliable place to look up films.
This was one of the most important parts of the project. People might say:
“I want something emotional but not depressing.”
“I need a fun movie for girls’ night.”
“Give me something intense and mind-bending.”
Those phrases are meaningful to a person, but they are not perfect database queries. So I used AI to bridge that gap. The model helps interpret what the user likely means and turns it into cleaner categories the rest of the system can work with.
This is like having a translator between human emotion and machine logic.
Once the input is interpreted, the app needs to find possible movies and decide which ones are strongest. I designed the logic so the system would not simply return random movies from a genre. It tries to match multiple signals at once.
That ranking layer is what turns the project from a basic search tool into a recommendation system.
A recommendation feels stronger when the user understands why they got it. So part of the project idea was not only to return titles, but also to explain the match in a human-friendly way.
For example, instead of only saying “Watch this movie,” the app can say something closer to: this film fits because it combines emotional depth, suspense, and the reflective tone you asked for.
That makes the system feel more trustworthy and personal.
Even though this project is presented as a movie app, I also viewed it as a data workflow. The system pulls data from a source, enriches it using AI, transforms it into decision-ready signals, and then serves a result back to the user.
That is part of why this project is meaningful for my portfolio. It shows not just app building, but also data thinking: ingestion, transformation, enrichment, ranking, and delivery.
At a high level, the app follows a simple idea:
Take emotional input → convert it into movie traits → search for candidates → rank the best ones → return recommendations.
The user does not see all of that complexity. They just feel like the app “understood” them. That is the goal of good product design: keep the hard work behind the scenes and make the front-end experience feel easy.
In a more technical sense, this project combines retrieval and interpretation. Retrieval gets the movie options. Interpretation makes the options more meaningful.
This project demonstrates several skills at once:
It shows that I can take an everyday problem, break it into technical parts, and build a solution that is both useful and engaging.
Good projects are not just about what worked. They are also about what had to be solved.
People describe the same feeling in different ways. One person may say “comfort movie,” another may say “something warm and easy,” and another may say “I do not want anything heavy.” The challenge was teaching the system to treat those as related ideas instead of completely different searches.
If I only relied on popularity, the system would recommend famous movies that may not match the user’s mood. I had to think about fit, not just fame.
Some users may give almost no detail, while others give long descriptions. The system needs to handle both gracefully. That is why AI interpretation was useful.
If an app gives suggestions without context, it can feel random. I wanted the results to feel thoughtful, almost like a person made them, which is why explanation mattered so much.
This project taught me that a strong application is not just code connected to an API. It is about understanding users, designing logic around their behavior, and presenting output in a way that feels useful.
This page is written as a standalone step by step process on how the application was created. It is meant to be read from top to bottom as a single case study. However, if you want to link to this project from a portfolio site, you could do it in a few ways:
Live Demo: Click Here To View The Project
GitHub: https://github.com/gloriamafor