chore: follow up workflow fixes with docs, comments, and regression tests

[adrunkhuman]

Summary

• Follow up the recent workflow-heavy fixes and refactors with a full commenter/docs/tester pass across the merged PR range from fix: WAL mode, results post UX, proactive session cleanup #129 through refactor: split database.py god-object into focused repositories (#116) #138
• Tighten public docs around runtime mode, data path defaults, restore safety, DM/thread routing, and admin panel/database workflow contracts
• Add regression coverage for the riskiest paths called out in review: concurrent prediction writes, concurrent fixture creation, DM router startup wiring, results posting/calculation flows, restore safety, config defaults, and timezone loading

Why

• The recent sequence of changes fixed real race conditions and untangled a lot of stateful behavior, but it also left some contracts implicit and a few important edge cases under-tested
• This follow-up makes the current behavior easier to understand and harder to regress without trying to change product scope again

Notes

• Split into atomic commits for comments, docs, and tests to keep review somewhat survivable
• Most relevant prior work: fix: WAL mode, results post UX, proactive session cleanup #129, fix: enforce prediction write guards atomically at the database layer #130, fix: safe DATA_DIR default, empty-games parse, atomic restore #131, fix: stale results guard, calculation post results, default UTC #132, refactor: inject db/service into admin panel views #134, refactor: remove passthrough service methods #135, fix: explicit DM router and admin session exclusivity (#111, #112) #136, refactor: extract AdminDMHandler base to eliminate _verify_admin duplication #137, refactor: split database.py god-object into focused repositories (#116) #138

Verification

• uv run ruff check scripts/restore_db.py tests/test_admin_commands.py tests/test_bot.py tests/test_config.py tests/test_database.py tests/test_results_handler.py tests/test_restore_db.py tests/test_thread_prediction_handler.py tests/test_timezone.py typer_bot/bot.py typer_bot/commands/admin_panel/base.py typer_bot/commands/admin_panel/modals.py typer_bot/database/connection.py typer_bot/handlers/dm_prediction_handler.py typer_bot/handlers/thread_prediction_handler.py typer_bot/services/workflow_state.py typer_bot/utils/config.py typer_bot/utils/prediction_parser.py
• uv run pytest

[railway-app]

🚅 Deployed to the matchday-typer-pr-139 environment in patient-quietude

Service	Status	Web	Updated (UTC)
matchday-typer	🕒 Building (View Logs)		Mar 22, 2026 at 12:31 am