# mahialaraf/fitz architecture

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

- Interactive diagram: https://gitdiagram.com/mahialaraf/fitz
- Repository: https://github.com/mahialaraf/fitz

## Overview

This is a terminal movie and TV discovery/advisory app. Users create or load a local profile, then either search for a title or answer preference questions to get recommendations; selected titles receive an AI suitability advisory and can be marked watched. The README only says work is ongoing. The graph follows the sampled Python calls; CSV files are runtime state, and the external AI and TMDB services are evidenced by the source. Other repository files were not inspected.

Main entry points: [`tools.py`](https://github.com/mahialaraf/fitz/blob/main/tools.py) (Input and state helpers), [`search_fitz.py`](https://github.com/mahialaraf/fitz/blob/main/search_fitz.py) (Title search and review flow), [`main.py`](https://github.com/mahialaraf/fitz/blob/main/main.py) (Menu and profile flow), [`get_fitz.py`](https://github.com/mahialaraf/fitz/blob/main/get_fitz.py) (Preference scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Terminal app"]
  node_main["Menu and profile flow<br/>[main.py]"]
  node_tools["Input and state helpers<br/>[tools.py]"]
end

subgraph group_discovery["Title discovery"]
  node_quiz["Preference scoring<br/>[get_fitz.py]"]
  node_genredata["Genre questions and scores<br/>[Data.py]"]
  node_recommend["Genre-based recommendations<br/>[Content_data.py]"]
  node_search["Title search and review flow<br/>[search_fitz.py]"]
end

subgraph group_advisory["AI advisory"]
  node_chatbot["Title correction and advisory<br/>[chatbot.py]"]
end

subgraph group_state["Local state"]
  node_profile[("Profile CSV<br/>[profiles.csv]")]
  node_records[("Review records CSV<br/>[records.csv]")]
  node_watched[("Watched titles CSV<br/>[marked.csv]")]
  node_cache["Review cache<br/>[Data.py]"]
end

node_user(("User"))
node_tmdb["TMDB API"]
node_gemini["Gemini API"]

node_user -->|"uses"| node_main
node_main -->|"manages profile"| node_tools
node_main -->|"starts search"| node_search
node_main -->|"starts recommendations"| node_quiz
node_main -->|"reads and saves profile"| node_tools
node_tools -->|"reads and writes"| node_profile
node_quiz -->|"uses questions"| node_genredata
node_quiz -->|"requests titles"| node_recommend
node_quiz -->|"opens selected title"| node_search
node_recommend -->|"fetches genres and titles"| node_tmdb
node_search -->|"corrects title and writes advisory"| node_chatbot
node_search -->|"searches and fetches details"| node_tmdb
node_search -->|"loads and saves reviews"| node_tools
node_search -->|"marks watched"| node_tools
node_chatbot -->|"generates text"| node_gemini
node_tools -->|"reads and appends"| node_records
node_tools -->|"reads and appends"| node_watched
node_tools -->|"updates cache"| node_cache

click node_main "https://github.com/mahialaraf/fitz/blob/main/main.py"
click node_tools "https://github.com/mahialaraf/fitz/blob/main/tools.py"
click node_quiz "https://github.com/mahialaraf/fitz/blob/main/get_fitz.py"
click node_genredata "https://github.com/mahialaraf/fitz/blob/main/Data.py"
click node_recommend "https://github.com/mahialaraf/fitz/blob/main/Content_data.py"
click node_search "https://github.com/mahialaraf/fitz/blob/main/search_fitz.py"
click node_chatbot "https://github.com/mahialaraf/fitz/blob/main/chatbot.py"
click node_profile "https://github.com/mahialaraf/fitz/blob/main/profiles.csv"
click node_records "https://github.com/mahialaraf/fitz/blob/main/records.csv"
click node_watched "https://github.com/mahialaraf/fitz/blob/main/marked.csv"
click node_cache "https://github.com/mahialaraf/fitz/blob/main/Data.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_main,node_tools,node_user toneBlue
class node_quiz,node_genredata,node_recommend,node_search toneAmber
class node_chatbot,node_tmdb,node_gemini toneMint
class node_profile,node_records,node_watched,node_cache toneRose
```

## Components

### Terminal app

- [Menu and profile flow](https://github.com/mahialaraf/fitz/blob/main/main.py): `main.py`
- [Input and state helpers](https://github.com/mahialaraf/fitz/blob/main/tools.py): `tools.py`

### Title discovery

- [Preference scoring](https://github.com/mahialaraf/fitz/blob/main/get_fitz.py): `get_fitz.py`
- [Genre questions and scores](https://github.com/mahialaraf/fitz/blob/main/Data.py): `Data.py`
- [Genre-based recommendations](https://github.com/mahialaraf/fitz/blob/main/Content_data.py): `Content_data.py`
- [Title search and review flow](https://github.com/mahialaraf/fitz/blob/main/search_fitz.py): `search_fitz.py`

### AI advisory

- [Title correction and advisory](https://github.com/mahialaraf/fitz/blob/main/chatbot.py): `chatbot.py`

### Local state

- [Profile CSV](https://github.com/mahialaraf/fitz/blob/main/profiles.csv): `profiles.csv`
- [Review records CSV](https://github.com/mahialaraf/fitz/blob/main/records.csv): `records.csv`
- [Watched titles CSV](https://github.com/mahialaraf/fitz/blob/main/marked.csv): `marked.csv`
- [Review cache](https://github.com/mahialaraf/fitz/blob/main/Data.py): `Data.py`

### Other components

- **User**
- **TMDB API**
- **Gemini API**

## Connections

- User → Menu and profile flow: uses (evidence: `main.py`)
- Menu and profile flow → Input and state helpers: manages profile (evidence: `main.py`)
- Menu and profile flow → Title search and review flow: starts search (evidence: `main.py`)
- Menu and profile flow → Preference scoring: starts recommendations (evidence: `main.py`)
- Menu and profile flow → Input and state helpers: reads and saves profile (evidence: `main.py`)
- Input and state helpers → Profile CSV: reads and writes (evidence: `tools.py`)
- Preference scoring → Genre questions and scores: uses questions (evidence: `get_fitz.py`)
- Preference scoring → Genre-based recommendations: requests titles (evidence: `get_fitz.py`)
- Preference scoring → Title search and review flow: opens selected title (evidence: `get_fitz.py`)
- Genre-based recommendations → TMDB API: fetches genres and titles (evidence: `Content_data.py`)
- Title search and review flow → Title correction and advisory: corrects title and writes advisory (evidence: `search_fitz.py`)
- Title search and review flow → TMDB API: searches and fetches details (evidence: `search_fitz.py`)
- Title search and review flow → Input and state helpers: loads and saves reviews (evidence: `search_fitz.py`)
- Title search and review flow → Input and state helpers: marks watched (evidence: `search_fitz.py`)
- Title correction and advisory → Gemini API: generates text (evidence: `chatbot.py`)
- Input and state helpers → Review records CSV: reads and appends (evidence: `tools.py`)
- Input and state helpers → Watched titles CSV: reads and appends (evidence: `tools.py`)
- Input and state helpers → Review cache: updates cache (evidence: `tools.py`)
