adding latest documentation and changes to the script.

video_transcription/ai_transcriber_v2/documentation/TECHNICAL_OVERVIEW.md

@@ -0,0 +1,31 @@
+# Technical Overview
+
+## 🏗 Architecture
+
+The project is modularized into specialized Python scripts:
+
+*   **`main.py`**: The entry point. Manages the batch processing loop and job tracking.
+*   **`extractor.py`**: Media handling via FFmpeg. Responsible for audio extraction and subtitle embedding. Contains the "Flatpak Escape" logic.
+*   **`transcriber.py`**: Integration with `openai-whisper`. Manages GPU health checks and model loading.
+*   **`translator.py`**: The AI translation engine. Implements the 4-tier fallback logic (Gemini -> Google -> Ollama -> MyMemory).
+*   **`utils.py`**: Shared utilities for encoding detection (chardet), port checking, and service health monitoring.
+*   **`tracker.py`**: Persistence layer using SQLite/SQLAlchemy to track job status across runs.
+
+## 🛡 Safety Mechanisms
+
+1.  **Duration Match Check**: Uses `ffprobe` to ensure the final subbed video length matches the original source.
+2.  **File Size Sanity**: Rejects any remux operation that results in a file < 80% of the original size (preventing video stream loss).
+3.  **SRT Health Check**: Compares the last timestamp of the translated SRT against the original transcript to detect partial/truncated translations.
+4.  **Encoding Detection**: Uses `chardet` to reliably read foreign subtitle files without manual configuration.
+
+## 🐳 Flatpak / Sandbox Support
+
+Since this project is designed for Bazzite/Atomic distros, all system-level calls (`ffmpeg`, `ffprobe`, `ollama`) are wrapped in a check that detects the presence of `/.flatpak-info`. If found, it automatically prefixes commands with `flatpak-spawn --host` to utilize system-installed binaries.
+
+## 💾 Database Schema
+
+The `job_history.db` tracks:
+- `file_path`: Absolute path to source.
+- `status`: PENDING, PROCESSING, COMPLETED, FAILED.
+- `step_status`: Individual status for Extract, Transcribe, Translate, and Embed steps.
+- `error_message`: Captured stack traces for failed jobs.