CineMind Movie Exploration Platform

Timothy Chen

Completed work

Fullstack Engineer

Astro

Flask

SQLite

CineMind

CineMind is a comprehensive movie exploration and data platform that helps users discover and explore films through rich data from The Movie Database (TMDB) API and intelligent insights. Built as a full-stack application with a custom Flask API backend, it provides detailed movie information, analytics, and features an AI-powered smart review section that uses Google's Gemini API to summarize reviews and provide intelligent commentary.

🎥 Demo

Watch CineMind in action - showcasing movie search, AI-powered reviews, and data visualizations.

✨ Features

Movie search and discovery with trailers, posters, and backdrops

Comprehensive movie metadata including cast, crew, and financial performance

User reviews integration

AI-powered review summaries (via Gemini API)

Interactive analytical charts and database visualizations

Custom Flask API for data management and processing

Movie analytics and insights

Responsive web interface built with Astro

Accessibility features including dyslexia-friendly fonts, font size slider, high contrast mode, reduced motion options, and keyboard navigation

🛠️ Tech Stack

Frontend

Astro - Modern web framework for content-focused websites

React - Interactive UI components

Tailwind CSS - Utility-first CSS framework

Backend

Python Flask - Lightweight web framework

SQLite - Local database for movie data storage

Google Gemini API - AI-powered review summarization

Data & Analytics

Pandas - Data manipulation and analysis

Chart.js - Interactive data visualizations

TMDB API - Movie metadata and information

📁 Project Directories

Frontend (`/frontend`)

src/pages/ - Astro page components and routing

src/components/ - Reusable React components

src/layouts/ - Page layout templates

src/styles/ - CSS and styling files

src/utils/ - Utility functions and helpers

src/hooks/ - Custom React hooks

src/assets/ - SVG logos and graphics used in the about section

public/ - Static assets (images, icons, etc.)

Backend (`/backend`)

app/ - Main Flask application code and development notebooks

app.py - Main Flask application entry point

api_and_db_testing.ipynb - Initial API testing and database implementation work from the start of the project

cinemind_toolkit.ipynb - Well-formatted utilities and commands for regular database operations and API management

cinemind_ai.ipynb - Testing and experimentation with the Gemini AI API for review analysis

data/ - CSV datasets and raw data files

tmdb_5000_movies.csv - Core movie dataset with metadata, budget, revenue, and ratings

tmdb_5000_credits.csv - Cast and crew information for movies

models/ - Original SQLite database files (now legacy - replaced by migration system)

tests/ - Unit testing files and test notebooks

test_database.ipynb - Comprehensive unit tests for database functionality and data integrity

requirements.txt - Python dependencies

Other

diagrams/ - Project documentation and diagrams, mainly showing the backend database structure with Mermaid diagrams

migration_project/ - Current active database - SQLAlchemy-based implementation with Alembic migrations (more powerful than the original cinemind.db)

🛠️ Setup Instructions

Prerequisites

Node.js (v18 or higher)

npm or yarn

Git

Python 3.8 or higher

Flask

Frontend Setup

Clone the repository

git clone https://github.com/t1anzn/cinemind
# OR download the ZIP file from GitHub and extract it
cd cinemind/frontend

Install dependencies

npm install

Start development server

npm run dev

The frontend will be available at http://localhost:4321

Backend Setup

[Optional] Create a virtual environment (from project root)

# From the cinemind root directory
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

Install Python dependencies

pip install -r requirements.txt

Configure environment variables

# Create a .env file in the root directory (or other supported locations)
# The Flask app will automatically detect .env files in multiple locations
# Add your API keys as shown in the Environment Variables section below

Start Flask server

cd backend/app
flask run

Full-Stack Development

Start both frontend and backend manually

# Terminal 1 - Backend
cd backend/app && flask run

# Terminal 2 - Frontend
cd frontend && npm run dev

Alternative: Use the convenience script (Windows only)

# Run the batch script from the project root
start-servers.bat

Note: The start-servers.bat script only works if your virtual environment is located at cinemind/venv (created in the project root as shown in the Backend Setup instructions).

🌐 Environment Variables

Create a .env file in one of the following supported locations:

Root directory: cinemind/.env (recommended)

Backend app directory: cinemind/backend/app/.env

Frontend directory: cinemind/frontend/.env

Backend directory: cinemind/backend/.env

The Flask app will automatically detect and load the .env file from any of these locations.

Add the following variables to your .env file:

TMdb_api_key=your_tmdb_bearer_token_here
GEMINI_API_KEY=your_gemini_api_key_here
VITE_API_URL=http://localhost:5000

Getting API Keys:

TMDB API: Get your bearer token from TMDB API Settings

Gemini API: Get your API key from Google AI Studio

🤝 Contributing

Fork the repository

Create a feature branch (git checkout -b feature/amazing-feature)

Commit your changes (git commit -m 'Add some amazing feature')

Push to the branch (git push origin feature/amazing-feature)

Open a Pull Request

🎨 Design & Planning

Miro Board - Project Planning & Wireframes

Figma - UI/UX Design System

📚 Learn More

Astro Documentation

Movie Database API Documentation

👥 Credits

This project was developed by:

Timothy Chen - Lead Full-Stack Developer & AI Engineer

BSc Computer Science Student at University of the Arts London (UAL)

Full-stack development with frontend leadership, backend architecture, AI integration with Gemini API, and system design

GitHub | LinkedIn

Balmee Hunumunt - Backend Lead Developer