# ARCHITECTURE.md

## Project

Rename-MVP

Webapplicatie voor het hernoemen van mediabestanden op basis van metadata van TheTVDB.

---

# High Level Architecture

browser  
↓  
FastAPI backend  
↓  
TVDB service  
↓  
TheTVDB API


---

# Container Architecture

Runtime:

Rootless Podman container

Image:

rename-mvp

Expose:

8085 → 8080


---

# Volumes

Host en container gebruiken identieke paden.

Volumes:

/Volumes/8TB/Shared_Folders/TV_Shows → /Volumes/8TB/Shared_Folders/TV_Shows  

/Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows → /Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows  

/home/kodi/.config/rename-mvp/data → /app/data


---

# Allowed Media Roots

De applicatie mag alleen bestanden lezen of wijzigen binnen de volgende directories:

/Volumes/8TB/Shared_Folders/TV_Shows  

/Volumes/8TB_RAID1/Shared_Folders/Library/TV_Shows


Alle file operations moeten binnen deze paden blijven.


---

# Backend Modules

Belangrijke modules:

tvdb_auth_service  
tvdb_client  
tvdb_service  
file_service  
preview_service  
rename_service  
session_service  


---

# TVDB Authentication Flow

1 login via /login  
2 ontvang JWT token  
3 decode JWT payload  
4 lees exp claim  
5 bereken renew_after  

token wordt opgeslagen in:

/app/data/tvdb_auth.json


---

# Token Lifecycle

Token wordt alleen vernieuwd als:

now >= renew_after

of

TVDB response 401 geeft.

Token wordt **niet bij elke request vernieuwd**.


---

# File Rename Flow

1 user selecteert serie  
2 afleveringen worden geladen  
3 user selecteert afleveringen  
4 user selecteert bestanden  
5 backend genereert preview  
6 user bevestigt rename  
7 backend voert rename uit  


---

# Data Storage

SQLite:

session state  
rename logs  

JSON:

tvdb_auth.json


---

# Naming Format

Bestandsnaam:

{series} ({year}) - S{season:02}E{episode:02} - {title}{ext}

Voorbeeld:

Elsbeth (2024) - S02E03 - Devil's Night.mkv


---

# Invariants

Deze eigenschappen mogen niet veranderen:

- API endpoints
- rename template
- token renew logic
- container runtime