# rafaelpierre/moviegpt architecture

> Architecture diagram of the GitHub repository rafaelpierre/moviegpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rafaelpierre/moviegpt
- Repository: https://github.com/rafaelpierre/moviegpt

## Overview

MovieGPT collects movie metadata, builds a persisted semantic index, and uses that index with an LLM to produce recommendations through a CLI or FastAPI endpoint. The sampled code shows the data, indexing, prompt, and request paths; README documents CLI capabilities, while the web route is the sampled API entry point. The index and model integrations are implemented through LlamaIndex, so their internal details are not shown here.

Main entry points: [`src/moviegpt/providers/rag.py`](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py) (RAG Query), [`src/moviegpt/client.py`](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/client.py) (CLI Workflows), [`src/moviegpt/api/web.py`](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/api/web.py) (Generate API), [`src/moviegpt/data/utils.py`](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/data/utils.py) (Movie Data Fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Metadata Ingestion"]
  node_fetch["Movie Data Fetch<br/>[utils.py]"]
  node_metadata["Movie Metadata<br/>[utils.py]"]
end

subgraph group_rag["Recommendation RAG"]
  node_indexing["Index Builder<br/>[rag.py]"]
  node_vector[("Persisted Vector Index<br/>[rag.py]")]
  node_prompt["Recommendation Prompt<br/>[recommendation.py]"]
  node_query["RAG Query<br/>[rag.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Workflows<br/>[client.py]"]
  node_api["Generate API<br/>[web.py]"]
  node_server["Web Launcher<br/>[server.py]"]
end

subgraph group_services["External Services"]
  node_wikipedia["Movie Data Source"]
  node_openai["OpenAI Models"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_cli -->|"downloads data"| node_fetch
node_fetch -->|"fetches decades"| node_wikipedia
node_fetch -->|"returns records"| node_metadata
node_cli -->|"creates index"| node_indexing
node_indexing -->|"persists index"| node_vector
node_indexing -->|"embeds documents"| node_openai
node_cli -->|"queries recommendations"| node_query
node_user -->|"submits details"| node_api
node_cli -->|"starts web server"| node_server
node_server -->|"launches app"| node_api
node_api -->|"builds prompt"| node_prompt
node_api -->|"requests answer"| node_query
node_query -->|"formats input"| node_prompt
node_query -->|"loads index"| node_vector
node_query -->|"generates answer"| node_openai
node_query -->|"returns answer"| node_api

click node_cli "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/client.py"
click node_api "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/api/web.py"
click node_server "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/api/server.py"
click node_fetch "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/data/utils.py"
click node_metadata "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/data/utils.py"
click node_indexing "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py"
click node_vector "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py"
click node_prompt "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/prompts/recommendation.py"
click node_query "https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fetch,node_metadata,node_user toneBlue
class node_indexing,node_vector,node_prompt,node_query toneAmber
class node_cli,node_api,node_server toneMint
class node_wikipedia,node_openai toneRose
```

## Components

### Metadata Ingestion

- [Movie Data Fetch](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/data/utils.py): `src/moviegpt/data/utils.py`
- [Movie Metadata](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/data/utils.py): `src/moviegpt/data/utils.py`

### Recommendation RAG

- [Index Builder](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py): `src/moviegpt/providers/rag.py`
- [Persisted Vector Index](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py): `src/moviegpt/providers/rag.py`
- [Recommendation Prompt](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/prompts/recommendation.py): `src/moviegpt/prompts/recommendation.py`
- [RAG Query](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/providers/rag.py): `src/moviegpt/providers/rag.py`

### User Interfaces

- [CLI Workflows](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/client.py): `src/moviegpt/client.py`
- [Generate API](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/api/web.py): `src/moviegpt/api/web.py`
- [Web Launcher](https://github.com/rafaelpierre/moviegpt/blob/main/src/moviegpt/api/server.py): `src/moviegpt/api/server.py`

### External Services

- **Movie Data Source**
- **OpenAI Models**

### Other components

- **User**

## Connections

- User → CLI Workflows: runs commands (evidence: `README.md`)
- CLI Workflows → Movie Data Fetch: downloads data (evidence: `src/moviegpt/client.py`)
- Movie Data Fetch → Movie Data Source: fetches decades (evidence: `src/moviegpt/data/utils.py`)
- Movie Data Fetch → Movie Metadata: returns records (evidence: `src/moviegpt/data/utils.py`)
- CLI Workflows → Index Builder: creates index (evidence: `src/moviegpt/client.py`)
- Index Builder → Persisted Vector Index: persists index (evidence: `src/moviegpt/providers/rag.py`)
- Index Builder → OpenAI Models: embeds documents (evidence: `src/moviegpt/providers/rag.py`)
- CLI Workflows → RAG Query: queries recommendations (evidence: `src/moviegpt/client.py`)
- User → Generate API: submits details (evidence: `README.md`)
- CLI Workflows → Web Launcher: starts web server (evidence: `src/moviegpt/client.py`)
- Web Launcher → Generate API: launches app
- Generate API → Recommendation Prompt: builds prompt (evidence: `src/moviegpt/api/web.py`)
- Generate API → RAG Query: requests answer (evidence: `src/moviegpt/api/web.py`)
- RAG Query → Recommendation Prompt: formats input (evidence: `src/moviegpt/providers/rag.py`)
- RAG Query → Persisted Vector Index: loads index (evidence: `src/moviegpt/providers/rag.py`)
- RAG Query → OpenAI Models: generates answer (evidence: `src/moviegpt/providers/rag.py`)
- RAG Query → Generate API: returns answer (evidence: `src/moviegpt/api/web.py`)