# vaggala/movie-revenue-predictor architecture

> Architecture diagram of the GitHub repository vaggala/movie-revenue-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vaggala/movie-revenue-predictor
- Repository: https://github.com/vaggala/movie-revenue-predictor

## Overview

##### Project type and purpose
- It reads structured CSV data, applies preprocessing and feature engineering (including NLP on the “overview” text), trains a Random Forest regression model, evaluates performance, and produces visualizations.

##### File structure
- Top level:
- data/ – raw CSV inputs (`tmdb_5000_movies.csv`, `tmdb_5000_credits.csv`)
- notebooks/ – exploratory Jupyter notebooks
- src/ – core pipeline modules (`load_data.py`, `preprocessing.py`, `train_model.py`, `evaluate_model.py`)
- main.py – orchestrator script that ties all stages together
- visualizations/ – output plots (Actual vs. Predicted, etc.)
- Configs & metadata: README.md, .gitignore, .gitattributes

##### README for additional insights
- Tech stack: scikit-learn, pandas, numpy, matplotlib, Hugging Face Transformers
- Model: Random Forest Regression, plus sentiment analysis on the “overview” field
- Metrics: R², MAE, RMSE
- Future improvements hint at model persistence (`joblib`), hyperparameter tuning, more features

##### Main components
a. Data Ingestion Layer
– Source: CSV files in data/
– Module: src/load_data.py
b. Preprocessing & Feature Engineering
– Structured: budget, cast size, runtime, genres, popularity, votes
– Unstructured/NLP: text embedding & sentiment analysis via Hugging Face Transformers (src/preprocessing.py)
c. Model Training
– Algorithm: Random Forest Regressor (src/train_model.py)
d. Model Evaluation
– Metrics calculation (R², MAE, RMSE) in src/evaluate_model.py
e. Visualization
– Plot generation in visualizations/ (Actual vs. Predicted)
f. Orchestration

##### Relationships and interactions
- CSV files → Data Loader → preprocessed Data
- Preprocessed Data → Feature Engineering → Feature Set
- Feature Set → Model Training → Trained Model
- Trained Model + Test Set → Evaluation → Metrics
- Metrics + Predictions → Visualization → Plots
- External service: Hugging Face Transformers called during NLP feature step

##### Architectural patterns & design principles
- Modular pipeline: each Python module has a single responsibility
- Clear separation of concerns: data ingestion, transformation, modeling, evaluation
- Reproducibility: orchestration via a single entrypoint (main.py)
- Extensibility: easy to swap in new models (e.g., XGBoost), add features, or persist models with joblib

##### Technologies & frameworks to annotate
- Python 3.x
- pandas / numpy (data manipulation)
- scikit-learn (Random Forest)
- transformers (Hugging Face)
- matplotlib (visualization)
- Jupyter notebooks (exploration)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        dataMovies(("tmdb_5000_movies.csv")):::data
        dataCredits(("tmdb_5000_credits.csv")):::data
        loader["Data Loader\n(src/load_data.py)"]:::module
    end

    %% Preprocessing & Feature Engineering
    subgraph "Preprocessing & Feature Engineering"
        preprocessing["Preprocessing & Feature Engineering\n(src/preprocessing.py)"]:::transform
    end

    %% Model Training
    subgraph "Model Training"
        trainer["Random Forest Trainer\n(src/train_model.py)"]:::model
    end

    %% Model Evaluation
    subgraph "Model Evaluation"
        evaluator["Evaluation & Metrics\n(src/evaluate_model.py)"]:::model
        metrics["Metrics\n(R², MAE, RMSE)"]:::model
    end

    %% Visualization
    subgraph "Visualization"
        visualDir(("visualizations/")):::data
        plots(("Plots\n(Actual vs Predicted)")):::data
    end

    %% Orchestration
    main["Orchestrator\n(main.py)"]:::module

    %% Exploratory Analysis
    subgraph "Exploratory Analysis"
        notebooksDir(("notebooks/")):::external
        testNotebook["testcsv.ipynb"]:::external
    end

    %% Project Metadata & Config
    README["README.md"]:::external
    GITIGNORE[".gitignore"]:::external
    GITATTR[".gitattributes"]:::external

    %% Data Flow
    dataMovies --> loader
    dataCredits --> loader
    loader --> rawData(("Raw Combined Data")):::data
    rawData --> preprocessing
    preprocessing --> structuredFeatures(("Structured Features")):::transform
    preprocessing --> nlpFeatures(("NLP Features\n(Transformers)")):::external
    structuredFeatures --> features(("Feature Set")):::transform
    nlpFeatures --> features
    features --> trainer
    trainer --> modelArtifact(("Trained Model")):::data
    modelArtifact --> evaluator
    evaluator --> metrics
    metrics --> visualDir
    visualDir --> plots

    %% Orchestration Flow
    main --> loader
    main --> preprocessing
    main --> trainer
    main --> evaluator
    main --> visualDir

    %% Exploratory Flow
    notebooksDir --> testNotebook

    %% Click Events
    click dataMovies "https://github.com/vaggala/movie-revenue-predictor/blob/main/data/tmdb_5000_movies.csv"
    click dataCredits "https://github.com/vaggala/movie-revenue-predictor/blob/main/data/tmdb_5000_credits.csv"
    click loader "https://github.com/vaggala/movie-revenue-predictor/blob/main/src/load_data.py"
    click preprocessing "https://github.com/vaggala/movie-revenue-predictor/blob/main/src/preprocessing.py"
    click trainer "https://github.com/vaggala/movie-revenue-predictor/blob/main/src/train_model.py"
    click evaluator "https://github.com/vaggala/movie-revenue-predictor/blob/main/src/evaluate_model.py"
    click visualDir "https://github.com/vaggala/movie-revenue-predictor/tree/main/visualizations/"
    click main "https://github.com/vaggala/movie-revenue-predictor/blob/main/main.py"
    click notebooksDir "https://github.com/vaggala/movie-revenue-predictor/tree/main/notebooks/"
    click testNotebook "https://github.com/vaggala/movie-revenue-predictor/blob/main/notebooks/testcsv.ipynb"
    click README "https://github.com/vaggala/movie-revenue-predictor/blob/main/README.md"
    click GITIGNORE "https://github.com/vaggala/movie-revenue-predictor/blob/main/.gitignore"
    click GITATTR "https://github.com/vaggala/movie-revenue-predictor/blob/main/.gitattributes"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef transform fill:#98FB98,stroke:#000,stroke-width:1px;
    classDef model fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef module fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:1px;
```
