ScreenStats

ScreenStats is a web application that allows users to compare the careers of movie actors side-by-side. It visualizes data such as box office performance, genre distribution, and critical reception, providing insights into an actor's filmography.

🚀 Features

• Actor Comparison: Compare two actors to see who has higher box office gross, more movies, or better ratings.
• Data Visualization: Interactive charts powered by Plotly to visualize career trajectories.
• Comprehensive Data: Sourced from The Movie Database (TMDB), covering movies, genres, budgets, and revenue.
• Responsive Design: Built with Bootstrap 5 for a seamless experience on desktop and mobile.

🛠 Tech Stack

• Backend: Django 5 (Python)
• Database: PostgreSQL
• Frontend: Django Templates, Bootstrap 5, Plotly.js
• Data Collection: Custom Python pipeline with psycopg2 and requests
• Infrastructure: Google Cloud Platform (Cloud Run, Cloud SQL, Cloud Build, Secret Manager)

📦 Project Structure

ScreenStats/
├── screen_stats/           # Main Django application
│   ├── models.py           # Database models (Actor, Movie, etc.)
│   ├── views.py            # View logic for comparisons
│   └── settings.py         # Project settings
├── data_collection/        # Data pipeline scripts
│   ├── main.py             # Main scraper script (TMDB -> Postgres)
│   └── testing/            # Data integrity tests
├── templates/              # HTML templates
├── static/                 # Static assets (CSS, JS, Images)
├── build_and_deploy_app.sh # Cloud Run deployment script
└── deploy_local.sh         # Script for running locally with Cloud SQL

⚡ Quick Start (Local Development)

Prerequisites

• Python 3.10+
• PostgreSQL installed and running locally
• A TMDB API Key (Get one here)

1. Clone the Repository

git clone https://github.com/SYusupov/ScreenStats.git
cd ScreenStats

2. Set up Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the root directory or export these variables:

export DB_NAME="screenstats_db"
export DB_USER="your_db_user"
export DB_PASS="your_db_password"
export DB_HOST="127.0.0.1"
export DB_PORT="5432"
export TMDB_ACCESS_TOKEN="your_tmdb_token"
export SECRET_KEY="your_django_secret_key"
export DEBUG="True"

4. Database Setup

# Create the database (if not exists)
createdb screenstats_db

# Run migrations
python manage.py migrate

# Populate initial data (Genres)
python manage.py populate_genres

5. Run Data Collection (Optional)

To populate your local database with movie/actor data:

cd data_collection
# Ensure DB env vars are set for this script too
python main.py

6. Run the Server

python manage.py runserver

Visit http://127.0.0.1:8000 in your browser.

🧪 Testing

The project includes a comprehensive test suite for the data collection pipeline.

cd data_collection/testing
./run_tests.sh

See data_collection/testing/TEST_README.md for more details on testing.

☁️ Deployment

The application is designed to be deployed on Google Cloud Run.

Deployment Script

The build_and_deploy_app.sh script handles:

1. Installing dependencies
2. Submitting the build to Cloud Build (using Buildpacks)
3. Running migrations (via Cloud Run Jobs)
4. Deploying the service to Cloud Run

./build_and_deploy_app.sh

Hybrid Local Run

To run locally but connect to the production Cloud SQL database:

./deploy_local.sh

Note: This requires GCP credentials and the Cloud SQL Auth Proxy.

📄 License

MIT License