# mjacobs95/cinefile architecture

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

- Interactive diagram: https://gitdiagram.com/mjacobs95/cinefile
- Repository: https://github.com/mjacobs95/cinefile

## Overview

##### Project type and purpose
- Cinephile is a standalone Python CLI/tool (not a web-app), whose sole purpose is to find the shortest link between two movies or two actors by querying The Movie Database (TMDB) API and building an in-memory graph.

##### File structure
Top-level files and folders:
- src/
– api.py      → contains DataLoader, handles all HTTP interactions to TMDB
– app.py      → CLI entry-point, orchestrates the workflow (parses inputs, invokes NetworkBuilder)
- outputs/      → destination for results of graph building or any serialized output
- tests/        → test suite invoking functions in src/
- requirements.txt → external Python dependencies
There is no persistent database—data lives only in memory during runtime.

##### README for additional insights
- Cinephile uses an iterative graph-expansion algorithm (in NetworkBuilder)
- The flow is: start with two seed nodes (movie or actor) → expand each node via TMDB API calls → add actors and movies to the graph → repeat until connected or iteration limit reached
- The code references two core modules: DataLoader (api.py) and NetworkBuilder (presumed in src/network.py)

a. Presentation/CLI Layer
– app.py: Parses command-line arguments (seed nodes, iteration limits), kicks off the graph-building process
b. Service/Processing Layer
– NetworkBuilder: Maintains the graph data structure, runs the expansion loop, checks for connectivity
c. Data Access Layer
– DataLoader (in api.py): Sends HTTP requests to TMDB, parses JSON responses into node/edge objects
d. External Service
– TMDB REST API: external HTTP endpoint providing movie/actor data
e. Output
– Graph serialization or image export into outputs/ (could be DOT, JSON, PNG)

##### Relationships and interactions
1. User invokes app.py (CLI)
2. app.py instantiates NetworkBuilder, passes seed nodes and config
3. NetworkBuilder calls DataLoader for each unexpanded node
4. DataLoader issues REST calls to TMDB and returns structured movie/actor records
5. NetworkBuilder incorporates new nodes/edges into its in-memory graph
6. Loop until graph is connected or iteration limit reached
7. app.py writes final graph or path to outputs/

##### Architectural patterns and design principles
- Layered architecture: CLI → service → data access → external API
- Single-process, in-memory graph traversal (no database)
- Separation of concerns:
- DataLoader solely responsible for HTTP & parsing
- NetworkBuilder focused on graph logic and search algorithm
- app.py coordinates, without embedding business logic
- Testable units: api.py and network logic can be tested independently in tests/test_all.py

##### Technologies/Frameworks
- Python 3.x
- requests (or similar) for HTTP in requirements.txt
- Possibly networkx (if used) or custom graph structures
- pytest or unittest for tests

##### Final touches
User/CLI → Application Layer → Graph Logic Layer → Data Access Layer → External API
→ File System Output

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation/CLI Layer
    subgraph "Presentation/CLI Layer"
        CLI["CLI – app.py"]:::internal
    end

    %% Service/Processing Layer
    subgraph "Graph Logic Layer"
        NB["Graph Service – NetworkBuilder"]:::internal
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        DL["HTTP Client – DataLoader"]:::internal
    end

    %% External Service
    TMDB(["TMDB REST API"]):::external

    %% File System Outputs and Resources
    subgraph "File System"
        OUT["outputs/"]:::filesystem
        IMG["images/"]:::filesystem
        REQ["requirements.txt"]:::filesystem
    end

    %% Test Suite
    TEST["Test Suite – tests/test_all.py"]:::test

    %% Connections
    CLI -->|"instantiate with seeds & config"| NB
    NB -->|"for each unexpanded node"| DL
    DL -->|"GET /movie/{id} or /person/{id}"| TMDB
    TMDB -->|"JSON response"| DL
    DL -->|"parsed Node/Edge objects"| NB
    NB -->|"loop until connected or iter_lim reached"| NB
    NB -->|"serialize graph/path"| OUT

    %% Side Resources
    CLI -.-> IMG
    CLI -.-> REQ
    TEST -.-> DL
    TEST -.-> NB

    %% Click Events
    click CLI "https://github.com/mjacobs95/cinefile/blob/master/src/app.py"
    click DL "https://github.com/mjacobs95/cinefile/blob/master/src/api.py"
    click TEST "https://github.com/mjacobs95/cinefile/blob/master/tests/test_all.py"
    click OUT "https://github.com/mjacobs95/cinefile/tree/master/outputs/"
    click IMG "https://github.com/mjacobs95/cinefile/tree/master/images/"
    click REQ "https://github.com/mjacobs95/cinefile/blob/master/requirements.txt"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#2b6cb0,color:#000
    classDef external fill:#c6f6d5,stroke:#276749,color:#000
    classDef filesystem fill:#faf089,stroke:#d69e2e,color:#000
    classDef test fill:#fed7e2,stroke:#9b2c2c,color:#000
```
