feat: add dark source inspection interface

2026-08-12 18:42:03 +03:00
parent db75f2c4f8
commit 277aa8a568
9 changed files with 1090 additions and 16 deletions
@@ -0,0 +1,48 @@
+# Architecture
+
+## Current state
+
+```text
+Browser
+  -> FastAPI / Jinja interface
+  -> POST /api/inspect
+  -> URL validation
+  -> yt-dlp metadata extraction (download disabled)
+  -> normalized metadata and output previews
+```
+
+FastAPI runs inspection in a thread pool. The browser receives a deliberately
+small response and never receives yt-dlp's signed media URLs. Displayed output
+options are previews; backend download selectors are not implemented yet.
+
+## Next application boundary
+
+Downloads will use durable jobs rather than long-running HTTP requests:
+
+```text
+Web service -> SQLite job record <- Worker service
+                                     |
+                                     +-> yt-dlp
+                                     +-> FFmpeg / ffprobe
+                                     +-> per-job directory
+```
+
+The worker will claim one queued job at a time, update progress, validate the
+finished media, and record the artifact. This preserves state across web
+restarts and keeps media processing outside request handlers.
+
+## Planned output presets
+
+1. **Best available** — highest useful source quality, merging separate video
+   and audio streams without transcoding.
+2. **Compatible MP4** — prefer the highest H.264 video and AAC audio streams
+   that can be merged into MP4 without transcoding.
+
+If no compatible combination exists, the first version should report that
+instead of silently starting an expensive transcode. Transcoding can later be
+an explicit third outcome with CPU and time limits.
+
+## Production boundary
+
+Production will route Cloudflare Access through Cloudflare Tunnel to the web
+service. The origin will not publish an application port directly.