# adrian-sit/personal-movie-vault architecture

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

- Interactive diagram: https://gitdiagram.com/adrian-sit/personal-movie-vault
- Repository: https://github.com/adrian-sit/personal-movie-vault
- Video tour (about a minute): https://gitdiagram.com/adrian-sit/personal-movie-vault/video

## Overview

Personal Movie Vault is a local-first movie-history knowledge system. The workflow transforms hand-authored metadata into movie records and exact viewing aggregates, combines those with joined and semantically chunked personal notes, builds a local embedding index, then retrieves evidence and generates cited answers. It also exposes chat through a local web interface and includes retrieval evaluation. The sampled code supports the transformation, analytics, web calls, and evaluation calls; README statements support the broader RAG stages and local Ollama integration.

Main entry points: [`src/rag.py`](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py) (Ingest and chunk), [`src/yaml_to_json.py`](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/yaml_to_json.py) (Metadata transform), [`eval/run_retrieval_eval.py`](https://github.com/adrian-sit/personal-movie-vault/blob/main/eval/run_retrieval_eval.py) (Retrieval evaluation), [`src/web.py`](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/web.py) (Chat server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Movie data"]
  node_raw_metadata["Movie metadata<br/>[movies.yaml]"]
  node_raw_notes["Personal notes"]
  node_transform["Metadata transform<br/>[yaml_to_json.py]"]
  node_analytics["Viewing analytics"]
  node_movie_records["Movie records<br/>[movies.json]"]
  node_viewing_stats["Viewing statistics"]
end

subgraph group_retrieval["RAG system"]
  node_rag_build["Ingest and chunk<br/>[rag.py]"]
  node_embedding["Local embeddings<br/>[rag.py]"]
  node_index[("Local RAG index<br/>[rag.py]")]
  node_retrieval_methods["Retrieval strategies<br/>[rag.py]"]
  node_answer["Answer generation<br/>[rag.py]"]
  node_evaluation["Retrieval evaluation"]
end

subgraph group_interfaces["User interfaces"]
  node_web_server["Chat server<br/>[web.py]"]
  node_web_ui["Chat interface<br/>[index.html]"]
end

node_user(("Movie viewer"))
node_ollama{{"Ollama API"}}

node_user -->|"asks through"| node_web_ui
node_web_ui -.->|"sends chat"| node_web_server
node_web_server -->|"searches"| node_retrieval_methods
node_web_server -->|"requests answer"| node_answer
node_raw_metadata -->|"reads"| node_transform
node_transform -->|"writes"| node_movie_records
node_transform -->|"builds aggregates"| node_analytics
node_analytics -->|"returns statistics"| node_viewing_stats
node_raw_metadata -->|"joins by id"| node_rag_build
node_raw_notes -->|"parses and chunks"| node_rag_build
node_movie_records -->|"supplies metadata"| node_rag_build
node_viewing_stats -->|"supplies exact counts"| node_rag_build
node_rag_build -->|"embeds chunks"| node_embedding
node_embedding -->|"requests vectors"| node_ollama
node_rag_build -->|"stores chunks and vectors"| node_index
node_index -->|"provides corpus"| node_retrieval_methods
node_retrieval_methods -->|"embeds query"| node_ollama
node_retrieval_methods -->|"returns ranked evidence"| node_answer
node_answer -->|"requests completion"| node_ollama
node_user -.->|"runs evaluation"| node_evaluation
node_evaluation -->|"evaluates search"| node_retrieval_methods
node_evaluation -->|"optionally generates"| node_answer

click node_raw_metadata "https://github.com/adrian-sit/personal-movie-vault/blob/main/data/raw/movies.yaml"
click node_raw_notes "https://github.com/adrian-sit/personal-movie-vault/tree/main/data/raw"
click node_transform "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/yaml_to_json.py"
click node_analytics "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/viewing_analytics.py"
click node_movie_records "https://github.com/adrian-sit/personal-movie-vault/blob/main/data/processed/movies.json"
click node_viewing_stats "https://github.com/adrian-sit/personal-movie-vault/blob/main/data/processed/viewing_statistics.json"
click node_rag_build "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py"
click node_embedding "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py"
click node_index "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py"
click node_retrieval_methods "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py"
click node_answer "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py"
click node_web_server "https://github.com/adrian-sit/personal-movie-vault/blob/main/src/web.py"
click node_web_ui "https://github.com/adrian-sit/personal-movie-vault/blob/main/web/index.html"
click node_evaluation "https://github.com/adrian-sit/personal-movie-vault/blob/main/eval/run_retrieval_eval.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_raw_metadata,node_raw_notes,node_transform,node_analytics,node_movie_records,node_viewing_stats,node_user toneBlue
class node_rag_build,node_embedding,node_index,node_retrieval_methods,node_answer,node_evaluation toneAmber
class node_web_server,node_web_ui,node_ollama toneMint
```

## Components

### Movie data

- [Movie metadata](https://github.com/adrian-sit/personal-movie-vault/blob/main/data/raw/movies.yaml): `data/raw/movies.yaml`
- [Personal notes](https://github.com/adrian-sit/personal-movie-vault/tree/main/data/raw): `data/raw`
- [Metadata transform](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/yaml_to_json.py): `src/yaml_to_json.py`
- [Viewing analytics](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/viewing_analytics.py): `src/viewing_analytics.py`
- [Movie records](https://github.com/adrian-sit/personal-movie-vault/blob/main/data/processed/movies.json): `data/processed/movies.json`
- [Viewing statistics](https://github.com/adrian-sit/personal-movie-vault/blob/main/data/processed/viewing_statistics.json): `data/processed/viewing_statistics.json`

### RAG system

- [Ingest and chunk](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py): `src/rag.py`
- [Local embeddings](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py): `src/rag.py`
- [Local RAG index](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py): `src/rag.py`
- [Retrieval strategies](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py): `src/rag.py`
- [Answer generation](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/rag.py): `src/rag.py`
- [Retrieval evaluation](https://github.com/adrian-sit/personal-movie-vault/blob/main/eval/run_retrieval_eval.py): `eval/run_retrieval_eval.py`

### User interfaces

- [Chat server](https://github.com/adrian-sit/personal-movie-vault/blob/main/src/web.py): `src/web.py`
- [Chat interface](https://github.com/adrian-sit/personal-movie-vault/blob/main/web/index.html): `web/index.html`

### Other components

- **Movie viewer**
- **Ollama API**

## Connections

- Movie viewer → Chat interface: asks through (evidence: `README.md`)
- Chat interface → Chat server: sends chat
- Chat server → Retrieval strategies: searches (evidence: `src/web.py`)
- Chat server → Answer generation: requests answer (evidence: `src/web.py`)
- Movie metadata → Metadata transform: reads (evidence: `src/yaml_to_json.py`)
- Metadata transform → Movie records: writes (evidence: `src/yaml_to_json.py`)
- Metadata transform → Viewing analytics: builds aggregates (evidence: `src/yaml_to_json.py`)
- Viewing analytics → Viewing statistics: returns statistics (evidence: `README.md`)
- Movie metadata → Ingest and chunk: joins by id (evidence: `README.md`)
- Personal notes → Ingest and chunk: parses and chunks (evidence: `README.md`)
- Movie records → Ingest and chunk: supplies metadata (evidence: `README.md`)
- Viewing statistics → Ingest and chunk: supplies exact counts (evidence: `README.md`)
- Ingest and chunk → Local embeddings: embeds chunks (evidence: `README.md`)
- Local embeddings → Ollama API: requests vectors (evidence: `README.md`)
- Ingest and chunk → Local RAG index: stores chunks and vectors (evidence: `README.md`)
- Local RAG index → Retrieval strategies: provides corpus (evidence: `README.md`)
- Retrieval strategies → Ollama API: embeds query (evidence: `README.md`)
- Retrieval strategies → Answer generation: returns ranked evidence (evidence: `README.md`)
- Answer generation → Ollama API: requests completion (evidence: `README.md`)
- Movie viewer → Retrieval evaluation: runs evaluation
- Retrieval evaluation → Retrieval strategies: evaluates search (evidence: `eval/run_retrieval_eval.py`)
- Retrieval evaluation → Answer generation: optionally generates (evidence: `eval/run_retrieval_eval.py`)