From 747e1acc215931097d2f081b04a545fadb7a8480 Mon Sep 17 00:00:00 2001
From: Lukas <lukas.pupkalipinski@lpl-mind.de>
Date: Sun, 22 Feb 2026 17:39:18 +0100
Subject: [PATCH] docs: document Temp cleanup in CHANGELOG and ARCHITECTURE

---
 docs/ARCHITECTURE.md | 60 +++++++++++++++++++++++++++++++++++++++++++-
 docs/CHANGELOG.md    | 18 +++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index a8fd03f..07752e0 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -261,6 +261,47 @@ Source: [src/config/settings.py](../src/config/settings.py#L1-L96)
 
 ---
 
+## 12. Startup Sequence
+
+The FastAPI lifespan function (`src/server/fastapi_app.py`) runs the following steps on every server start.
+
+### 12.1 Startup Order
+
+```
+1. Logging configured
+
+2. Temp folder purged  ← cleans leftover partial download files
+   +-- Iterate ./Temp/ and delete every file and sub-directory
+   +-- Create ./Temp/ if it does not exist
+   +-- Errors are logged as warnings; startup continues regardless
+
+3. Database initialised (required – abort on failure)
+   +-- SQLite file created / migrated via init_db()
+
+4. Configuration loaded from data/config.json
+   +-- Synced to settings (ENV vars take precedence)
+
+5. Progress & WebSocket services wired up
+
+6. Series loaded from database into memory
+
+7. Download service initialised (queue restored from DB)
+
+8. Background loader service started
+
+9. Scheduler service started
+
+10. NFO repair scan (queue incomplete tvshow.nfo files for background reload)
+```
+
+### 12.2 Temp Folder Guarantee
+
+Every server start begins with a clean `./Temp/` directory. This ensures that partial `.part` files or stale temp videos from a crashed or force-killed previous session are never left behind before new downloads start.
+
+Source: [src/server/fastapi_app.py](../src/server/fastapi_app.py)
+
+---
+
 ## 11. Graceful Shutdown
 
 The application implements a comprehensive graceful shutdown mechanism that ensures data integrity and proper cleanup when the server is stopped via Ctrl+C (SIGINT) or SIGTERM.
@@ -363,12 +404,29 @@ Source: [src/server/middleware/auth.py](../src/server/middleware/auth.py#L1-L209
        +-- WebSocketService broadcasts to clients
 
 3. During download:
+   +-- Provider writes to ./Temp/<filename>  (+ ./Temp/<filename>.part fragments)
    +-- ProgressService.emit("progress_updated")
    +-- WebSocketService.broadcast_to_room()
    +-- Client receives WebSocket message
+
+4. After download attempt (success OR failure):
+   +-- _cleanup_temp_file() removes ./Temp/<filename> and all .part fragments
+   +-- On success: file was already moved to final destination before cleanup
+   +-- On failure / exception: no partial files remain in ./Temp/
 ```
 
-Source: [src/server/services/download_service.py](../src/server/services/download_service.py#L1-L150)
+#### Temp Directory Contract
+
+| Situation | Outcome |
+| --------- | ------- |
+| Server start | Entire `./Temp/` directory is purged before any service initialises |
+| Successful download | Temp file moved to destination, then removed from `./Temp/` |
+| Failed download (provider error) | Temp + `.part` fragments removed by `_cleanup_temp_file()` |
+| Exception / cancellation | Temp + `.part` fragments removed in `except` block |
+
+Source: [src/server/services/download_service.py](../src/server/services/download_service.py#L1-L150),
+[src/core/providers/aniworld_provider.py](../src/core/providers/aniworld_provider.py),
+[src/core/providers/enhanced_provider.py](../src/core/providers/enhanced_provider.py)
 
 ### 3.3 WebSocket Event Flow
 
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 708376c..a022dff 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -37,6 +37,24 @@ This changelog follows [Keep a Changelog](https://keepachangelog.com/) principle
 
 ---
 
+## [1.3.1] - 2026-02-22
+
+### Added
+
+- **Temp file cleanup after every download** (`src/core/providers/aniworld_provider.py`,
+  `src/core/providers/enhanced_provider.py`): Module-level helper
+  `_cleanup_temp_file()` removes the working temp file and any yt-dlp `.part`
+  fragments after each download attempt — on success, on failure, and on
+  exceptions (including `BrokenPipeError` and cancellation). Ensures that no
+  partial files accumulate in `./Temp/` across multiple runs.
+- **Temp folder purge on server start** (`src/server/fastapi_app.py`): The
+  FastAPI lifespan startup now iterates `./Temp/` and deletes every file and
+  sub-directory before the rest of the initialisation sequence runs. If the
+  folder does not exist it is created. Errors are caught and logged as warnings
+  so that they never abort startup.
+
+---
+
 ## [1.3.0] - 2026-02-22
 
 ### Added