# mdlarson/moviepeers architecture

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

- Interactive diagram: https://gitdiagram.com/mdlarson/moviepeers
- Repository: https://github.com/mdlarson/moviepeers

## Overview

##### Project Type and Purpose
- MoviePeers is a full-stack web application built with Python and Flask.
- Its purpose is to allow users to discover movies and roles where actors were the same age as the user by comparing actor ages.
- It incorporates a data pipeline that fetches data from the TMDb API and processes it using GraphQL and SQLAlchemy for managing and querying the data.

##### File Structure
- Top-Level Files:
- app.py: Likely the main Flask application entry point that sets up web routes.
- models.py: Contains SQLAlchemy models defining the database schema.
- schema.py: Houses the GraphQL schema and possibly resolvers connecting the API to the data models.
- fetch_actor_data.py & fetch_archives.py: Modules responsible for retrieving and processing actor and movie data from TMDb.
- requirements.txt: Lists dependencies like Flask, SQLAlchemy, and GraphQL libraries.
- Procfile: Indicates deployment details (likely for platforms like Heroku).
- .gitignore: Standard source control exclusions.
- Instance Folder:
- instance/moviedata.db: The SQLite database file storing movie and actor data.
- Templates and Static:
- templates/index.html: The HTML template for the user interface.
- static/style.css: Styling information for the UI.
- This structure suggests an MVC-like design:
- Models (models.py)
- Views (templates, static)
- Controller/Business Logic (app.py and data fetching scripts)

##### Components
- Client/User Interface:
- Web browser interacting with the website.
- Served HTML from templates and styled by static assets.
- Flask Application (app.py):
- Acts as the web server and route handler.
- Potentially integrates endpoint for GraphQL queries.
- GraphQL Layer (schema.py):
- Provides a query interface to interact with the backend data.
- Connects to the SQLAlchemy models.
- Data Models (models.py):
- Represents the database tables and relationships.
- Database (instance/moviedata.db):
- SQLite database that stores actor and movie information.
- External Data Pipeline:
- Scripts (fetch_actor_data.py & fetch_archives.py) that fetch and process data from the TMDb API.
- These could be shown as a data ingestion module feeding the database.
- External Services:
- TMDb API as the source of movie and actor data.

##### Relationships and Interactions
- User requests via the browser hit Flask routes in app.py.
- These routes render the HTML interface and trigger GraphQL queries when needed.
- The GraphQL layer processes queries by interacting with SQLAlchemy models (in models.py) which query the database.
- Data fetching scripts interact with the TMDb API, then update/populate the local database.
- Client → Flask App (HTTP Requests/Responses)
- Flask App → GraphQL API (Query handling)
- GraphQL → Database (CRUD operations)
- Data Pipeline Scripts → TMDb API (Data fetching)
- TMDb API → Data Pipeline Scripts → Database (Data ingestion)

##### Key Architectural Patterns and Technologies
- MVC Pattern: Separation of views (templates/static), models (SQLAlchemy in models.py), and business logic/controller (Flask in app.py and data fetching scripts).
- Data Pipeline: Integration with external TMDb API to pull and process movie data.
- GraphQL API: Used to query the processed data in a flexible way.
- Deployment Consideration: Use of Procfile for deployment (likely Heroku).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    ClientUI["Client Browser (Templates & Static)"]:::client

    %% Backend Layer
    FlaskWeb["Flask Web Server (app.py)"]:::server
    GraphQL["GraphQL API (schema.py)"]:::api
    DataModels["Data Models (models.py)"]:::model
    Database["Database (moviedata.db)"]:::database

    %% Data Pipeline Layer
    subgraph "Data Pipeline"
        FetchActor["Data Pipeline: fetch_actor_data.py"]:::script
        FetchArchives["Data Pipeline: fetch_archives.py"]:::script
    end

    %% External Service
    TMDbAPI["TMDb API"]:::external

    %% Relationships
    ClientUI -->|"HTTP_Request/Response"| FlaskWeb
    FlaskWeb -->|"Executes_Query"| GraphQL
    GraphQL -->|"Uses_ORM"| DataModels
    DataModels -->|"Queries_DB"| Database

    FetchActor -->|"Fetch_Data"| TMDbAPI
    FetchArchives -->|"Fetch_Data"| TMDbAPI
    FetchActor -->|"Store_Data"| Database
    FetchArchives -->|"Store_Data"| Database

    %% Click Events
    click ClientUI "https://github.com/mdlarson/moviepeers/blob/main/templates/index.html"
    click ClientUI "https://github.com/mdlarson/moviepeers/blob/main/static/style.css"
    click FlaskWeb "https://github.com/mdlarson/moviepeers/blob/main/app.py"
    click GraphQL "https://github.com/mdlarson/moviepeers/blob/main/schema.py"
    click DataModels "https://github.com/mdlarson/moviepeers/blob/main/models.py"
    click Database "https://github.com/mdlarson/moviepeers/blob/main/instance/moviedata.db"
    click FetchActor "https://github.com/mdlarson/moviepeers/blob/main/fetch_actor_data.py"
    click FetchArchives "https://github.com/mdlarson/moviepeers/blob/main/fetch_archives.py"

    %% Styles
    classDef client fill:#a2d9ce,stroke:#333,stroke-width:2px;
    classDef server fill:#f7dc6f,stroke:#333,stroke-width:2px;
    classDef api fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef model fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef database fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef script fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
```
