finalized v2 architecture for 2.0.1

docs/architecture-v2.org

@@ -1,6 +1,6 @@
 #+TITLE: youdis v2 architecture
-#+VERSION: 1
 #+DATE: [2026-03-31 Tue]
+#+VERSION: 3
 
 * Purpose
 Youdis v2 splits the current monolithic Discord bot into:
@@ -27,8 +27,8 @@ The goal is to make downloader behavior inspectable, reusable, and easier to deb
 Owns:
 - request validation
 - single active job state
-- yt-dlp configuration loading and merge rules
-- download execution
+- yt-dlp executable invocation
+- yt-dlp configuration selection and runtime argument construction
 - archive behavior
 - output path behavior
 - progress and final result events
@@ -63,6 +63,20 @@ V2 should start as a single private process boundary with two layers:
 
 The backend is intended for private/local deployment. Trust comes from deployment topology and network placement, not backend auth.
 
+** Execution model
+The backend is a thin FastAPI wrapper around the `yt-dlp` executable, not a deep Python integration, unless proven necessary.
+
+Why this is the default:
+- keeps behavior closer to native `yt-dlp`
+- makes container debugging easier because commands can be reproduced manually
+- avoids reimplementing `yt-dlp` option parsing unless we truly need tighter integration
+
+This means the backend is primarily responsible for:
+- deciding when `yt-dlp` may run
+- constructing a safe effective command
+- supervising the subprocess while it is active
+- translating process outcomes into a small API contract
+
 ** Backend Contract
 *** Request model
 Minimal fields:
@@ -74,17 +88,26 @@ Minimal fields:
 Only `url` affects downloader behavior in v2. The rest is passthrough metadata for logs and frontend context.
 
 *** Result states
-The backend should normalize job outcomes into a small stable vocabulary:
+The backend should keep its external state model deliberately small:
 - `accepted`
 - `busy`
-- `validating`
-- `downloading`
-- `skipped`
+- `running`
 - `completed`
 - `failed`
 - `cancelled`
 
-These states should be transport-agnostic and human-debuggable.
+These states should be transport-agnostic, human-debuggable, and only distinct when a frontend would behave differently.
+
+Internal phases and details may be richer, but they should usually be carried as metadata rather than promoted to top-level states.
+
+Examples of detail fields that can travel alongside the small state model:
+- `phase=validating`
+- `phase=downloading`
+- `disposition=archive_hit`
+- `message=already in archive`
+- `result_path=/downloads/...`
+
+This keeps the API simple while still leaving room for useful operator-facing detail.
 
 *** Minimal endpoints
 The first backend seam should stay small:
@@ -101,7 +124,7 @@ V2 explicitly supports one active job at a time.
 - If idle, the backend accepts a new job and marks it active.
 - If busy, the backend rejects the new request with a `busy` result.
 - Cancel is coarse and best-effort.
-- The backend clears active state when the job reaches `skipped`, `completed`, `failed`, or `cancelled`.
+- The backend clears active state when the job reaches `completed`, `failed`, or `cancelled`.
 
 This is a feature, not a limitation, for the initial service.
 
@@ -109,7 +132,7 @@ This is a feature, not a limitation, for the initial service.
 
 This is the most important v2 cleanup.
 
-The backend owns all yt-dlp configuration behavior. Frontends must not build yt-dlp option dictionaries.
+The backend owns all yt-dlp invocation behavior. Frontends must not build `yt-dlp` commands or option dictionaries.
 
 ** Config split
 
@@ -122,13 +145,13 @@ Static settings belong in `default-yt-dlp.conf`:
 
 Runtime settings belong in backend code:
 - target URL
-- progress hooks
-- cancellation hook
-- request-scoped metadata
+- config-file path, if explicitly set at launch
+- request-scoped flags or overrides
+- subprocess lifecycle and cancellation behavior
 - any values that must vary per request
 
 *** Merge rule
-The backend should load the default config first, then apply a small set of explicit runtime overrides.
+The backend should invoke `yt-dlp` with the default config first, then apply a small set of explicit runtime overrides.
 
 If a runtime override conflicts with file-backed config, the override wins and the backend should log the effective value used.
 
@@ -136,8 +159,7 @@ If a runtime override conflicts with file-backed config, the override wins and t
 For each job, the backend should make it easy to inspect:
 
 - config file path used
-- whether config loading succeeded
-- effective key yt-dlp options after merge
+- effective `yt-dlp` command or key override arguments
 - final normalized job result
 
 This exists specifically because the current config behavior has been difficult to reason about.
@@ -157,25 +179,45 @@ youdis/
   default-yt-dlp.conf
   youdis/
     __init__.py
-    api.py
-    config.py
+    main.py
     models.py
-    worker.py
-    ytdlp_backend.py
     adapters/
       __init__.py
       discord.py
   docs/
-    architecture-v2.md
+    architecture-v2.org
 #+end_quote
 
 Notes:
 
-- `ytdlp_backend.py` owns yt-dlp integration and result normalization.
-- `worker.py` owns active-job state and lifecycle.
-- `api.py` exposes the minimal HTTP seam.
+- `main.py` owns the FastAPI app, active-job state, and `yt-dlp` subprocess lifecycle.
+- `models.py` owns request and response models.
 - `adapters/discord.py` becomes a thin client of the backend.
 
+** Example response shape
+
+One likely response shape for v1:
+
+#+begin_src json
+{
+  "state": "completed",
+  "disposition": "archive_hit",
+  "message": "already in archive",
+  "job_id": "abc123"
+}
+#+end_src
+
+And for an active job:
+
+#+begin_src json
+{
+  "state": "running",
+  "phase": "downloading",
+  "message": "downloading 3 of 9",
+  "job_id": "abc123"
+}
+#+end_src
+
 ** Framework Recommendation
 
 FastAPI is the current recommendation for the backend seam.
@@ -200,7 +242,7 @@ Why this is not a strong ideological choice:
 - single active-job state holder
 - one submit-job path
 - one current-job status path
-- yt-dlp config loading from `default-yt-dlp.conf`
-- explicit runtime overrides for request URL, progress hooks, and cancel behavior
+- `yt-dlp` subprocess invocation using `default-yt-dlp.conf`
+- explicit runtime overrides for request URL and cancel behavior
 
 The Discord adapter should remain unchanged until that backend skeleton can accept a job and report status coherently.