refactor(server): extract the audio-effects routes into routers/audio_effects.py (R3)

[byrongamatos]

The first route module through the appstate seam from #833. Move-only, backend-only.

Picked by measurement, not by the plan

The plan assumed artists/aliases was the cheapest first router. A transitive dependency-closure scan over every route group says otherwise — api_artist_links reaches _mb_http_get and _enrich_network_enabled, both monkeypatch.setattr targets (13 + 15 sites). Ranking every group by (setattr targets, helpers needing relocation):

group	routes	lines	setattr	helpers to relocate
artist-aliases	5	37	0	none
loops	3	30	0	none
audio-effects	5	46	0	_audio_effects_error (exclusive)
artist-page/links	3	13	2	19
song	14	644	11	95

audio-effects wins as the first cut: zero setattr targets, one exclusive helper, and — unlike the alias group — it exercises the second seam slot (audio_effect_mappings, not meta_db) and the _demo_mode_guard middleware, which has four regexes pointed at these exact paths.

What changed

Bodies are verbatim. Two mechanical edits, nothing else:

@app.get(...)             ->  @router.get(...)
audio_effect_mappings.x   ->  appstate.audio_effect_mappings.x

The singleton read stays a module attribute resolved at call time, so a re-imported server re-publishes a fresh DB into the seam and monkeypatch.setattr reaches this module. routers/ never imports server: the graph is server → routers → appstate.

app.include_router(...) sits exactly where the routes used to be defined. FastAPI matches in registration order, so the mount site is load-bearing.

server.py: 9,445 → 9,386 lines. fastapi.Query went dead with the move and was removed; the other four unused imports are pre-existing on main.

Verification

• Route table diffed against origin/main: 143 routes, identical paths, methods, and registration order. This is the assertion that matters for include_router.
• Boot smoke drives all five routes end-to-end: create → read back → activate → clear-active → delete → 404 on a missing id → 400 on a bad body. Query(...) still 422s a missing required param.
• Demo-mode middleware still 403s all four moved write routes and still allows the read — checked against a running server with FEEDBACK_DEMO_MODE=1.
• Docker: COPY routers/ /app/routers/ plus !routers/ + !routers/** in .dockerignore (that file opens with a blanket * exclusion, so a new package is invisible to the build without it — this is what would have broken the image). Verified against the real daemon: routers/ reaches the build context, __pycache__ does not.
• pytest 2348 passed (75 across the audio-effects + demo-mode suites); pyflakes clean on routers/; npm run lint 0 errors.
• Codex preflight: 0 findings.

Pattern for the rest of the train

routers/__init__.py documents it: expose a module-level router, read singletons as appstate.<name> at call time, never from appstate import … (frozen binding), never import server.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added audio-effects mapping API endpoints for listing, creating, updating, activating, and deleting mappings.
  • Added filtering and validation support for audio-effects mapping requests.
  • Preserved existing error responses and route behavior.

• Infrastructure

  • Updated Docker packaging and local development mounts so the new API routes are included at runtime.

• Documentation

  • Updated the changelog and project size-exemption documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The audio-effects mapping endpoints were extracted from server.py into routers/audio_effects.py, mounted through app.include_router(...), and packaged through updated Docker ignore, image-copy, and compose-mount rules.

Changes

Audio-effects router extraction

Layer / File(s)	Summary
Router handlers and shared state access routers/__init__.py, routers/audio_effects.py	Defines the router, five audio-effects endpoints, shared ValueError handling, and late-bound access to appstate.audio_effect_mappings.
Server integration server.py	Replaces the inline handlers with audio_effects.router, mounted at the original registration point.
Runtime packaging and documentation .dockerignore, Dockerfile, docker-compose.yml, CHANGELOG.md, docs/size-exemptions.md	Includes routers/ in Docker build and runtime mounts, and updates related project documentation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant FastAPI_app
  participant audio_effects_router
  participant appstate_audio_effect_mappings
  Client->>FastAPI_app: audio-effects request
  FastAPI_app->>audio_effects_router: dispatch registered route
  audio_effects_router->>appstate_audio_effect_mappings: perform mapping operation
  appstate_audio_effect_mappings-->>audio_effects_router: return result or error
  audio_effects_router-->>Client: JSON response

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: extracting the audio-effects routes from server.py into routers/audio_effects.py.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/r3-router-artists

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

routers/audio_effects.py (1)

43-43: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Silence the Ruff B008 false positive via config, not code.

Body(...) / Body(default_factory=dict) as argument defaults are the standard FastAPI idiom; this is a known B008 false positive, not a real mutable-default bug, and pre-exists the extraction (verbatim per the module docstring). Rather than restructuring handlers, add these fastapi callables to Ruff's immutable-calls allowlist.

🔧 Suggested pyproject.toml addition

[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = ["fastapi.Body", "fastapi.Query", "fastapi.Depends", "fastapi.Path"]

Also applies to: 63-63

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@routers/audio_effects.py` at line 43, Configure Ruff rather than changing the
FastAPI handlers: under [tool.ruff.lint.flake8-bugbear] in pyproject.toml, add
fastapi.Body, fastapi.Query, fastapi.Depends, and fastapi.Path to
extend-immutable-calls, covering the defaults used by
upsert_audio_effect_mapping and the handler at the other reported location.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@routers/audio_effects.py`:
- Line 43: Configure Ruff rather than changing the FastAPI handlers: under
[tool.ruff.lint.flake8-bugbear] in pyproject.toml, add fastapi.Body,
fastapi.Query, fastapi.Depends, and fastapi.Path to extend-immutable-calls,
covering the defaults used by upsert_audio_effect_mapping and the handler at the
other reported location.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5cd519b9-8eff-419e-9217-950b4f84c6f1

📥 Commits

Reviewing files that changed from the base of the PR and between d6f2df1 and 2a0014c.

📒 Files selected for processing (8)

• .dockerignore
• CHANGELOG.md
• Dockerfile
• docker-compose.yml
• docs/size-exemptions.md
• routers/__init__.py
• routers/audio_effects.py
• server.py