docs: update deployment docs and standardize logging (#194)

* docs: update deployment docs and costs for production-fe workflow

- update README costs to ~$25-30/month (2x fly apps + neon)
- fix backend API links to use api.plyr.fm custom domain
- update environments.md for production-fe branch deployment
- document new release workflow (just release merges main → production-fe)
- remove outdated overview.md (referenced old relay branding)
- remove STATUS.md link (not tracked in git)
- fix local development to use justfile commands

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* feat: add hot reloading to transcoder with cargo-watch

use cargo watch for transcoder development to auto-reload on file changes,
matching the hot reload experience of backend (uvicorn --reload) and
frontend (bun run dev)

requires: cargo install cargo-watch

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* refactor: organize frontend commands into nested justfile

- create frontend/justfile with dev, build, preview, check, install
- remove deploy-frontend from root justfile (deployment via cloudflare pages)
- update docs to use 'just frontend dev' instead of 'just run-frontend'
- matches transcoder pattern with nested justfile modules

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* refactor: standardize logging with logfire handler

- use LogfireLoggingHandler for consistent log formatting
- remove duplicate logfire.configure() call in database.py
- add per-file import sort ignore for main.py (warnings filter must be first)
- downgrade handle resolution log to debug level
- clean up README deployment instructions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* refactor: simplify frontend justfile to only used targets

remove build, preview, install targets - these are never used locally.
cloudflare pages handles builds, and deps are managed directly with bun.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

README.md

···
 ```bash
 # install dependencies
 uv sync
-cd frontend && bun install
-
-# run backend
-just serve
+just frontend install
 
-# run frontend (new terminal)
-just dev
-```
-
-or manually:
+# run backend (hot reloads)
+just run-backend
 
-```bash
-# backend
-uv sync
-uv run uvicorn backend.main:app --reload --port 8001
+# run frontend (hot reloads)
+just frontend dev
 
-# frontend (new terminal)
-cd frontend && bun install && bun run dev
+# run transcoder (hot reloads)
+just transcoder run
 ```
 
 visit http://localhost:5173
···
 <details>
 <summary>costs</summary>
 
-~$5-6/month for MVP:
-- cloudflare pages: free
-- cloudflare r2: ~$0.16
-- fly.io: $5
-- neon: free
+~$25-30/month:
+- fly.io backend (production): ~$10/month (shared-cpu-1x, 256MB RAM)
+- fly.io backend (staging): ~$10/month (shared-cpu-1x, 256MB RAM)
+- fly.io transcoder: ~$0-5/month (auto-scales to zero when idle)
+- neon postgres: $5/month (starter plan)
+- cloudflare pages: free (frontend hosting)
+- cloudflare r2: ~$0.16/month (6 buckets across dev/staging/prod)
 
 </details>
 
 ## links
 
 - **production**: https://plyr.fm
-- **backend API**: https://relay-api.fly.dev
+- **backend API**: https://api.plyr.fm
 - **repository**: https://github.com/zzstoatzz/plyr.fm
 
 ## documentation
 
-- [deployment guide](docs/deployment/overview.md)
-- [latest status](STATUS.md)
+- [deployment guide](docs/deployment/environments.md)
 - [configuration](docs/configuration.md)
+- [full documentation](docs/README.md)

docs/deployment/environments.md

···
 
 ## environments
 
-| environment | trigger | backend app | backend URL | database | frontend | storage |
-|-------------|---------|-------------|-------------|----------|----------|---------|
-| **development** | local | local server | localhost:8001 | plyr-dev (neon) | localhost:5173 | audio-dev, images-dev (r2) |
-| **staging** | push to main | plyr-api-staging | plyr-api-staging.fly.dev | plyr-staging (neon) | cloudflare pages preview | audio-staging, images-staging (r2) |
-| **production** | github release | plyr-api | plyr-api.fly.dev | plyr-prod (neon) | plyr.fm (cloudflare pages) | audio-prod, images-prod (r2) |
+| environment | trigger | backend URL | database | frontend | storage |
+|-------------|---------|-------------|----------|----------|---------|
+| **development** | local | localhost:8001 | plyr-dev (neon) | localhost:5173 | audio-dev, images-dev (r2) |
+| **staging** | push to main | relay-api-staging.fly.dev | plyr-staging (neon) | cloudflare pages preview (main) | audio-staging, images-staging (r2) |
+| **production** | github release | api.plyr.fm | plyr-prod (neon) | plyr.fm (production-fe branch) | audio-prod, images-prod (r2) |
 
 ## workflow
 
 ### local development
 
 ```bash
-# start backend
-uv run uvicorn backend.main:app --reload --port 8001
+# start backend (hot reloads)
+just run-backend
 
-# start frontend
-cd frontend && bun run dev
+# start frontend (hot reloads)
+just frontend dev
 
-# start transcoder (optional)
-cd transcoder && just run
+# start transcoder (hot reloads)
+just transcoder run
 ```
 
 connects to `plyr-dev` neon database and uses `fm.plyr` atproto namespace.
···
 **trigger**: push to `main` branch
 
 **backend**:
-1. github actions runs `.github/workflows/deploy-backend.yml`
-2. deploys to `plyr-api-staging` fly app using `fly.staging.toml`
-3. runs `alembic upgrade head` via `release_command`
-4. backend available at `https://plyr-api-staging.fly.dev`
+1. github actions runs `.github/workflows/deploy-staging.yml`
+2. runs `alembic upgrade head` via `release_command`
+3. backend available at `https://relay-api-staging.fly.dev`
 
 **frontend**:
-- cloudflare pages automatically deploys from `main` branch
-- uses preview environment with `PUBLIC_API_URL=https://plyr-api-staging.fly.dev`
-- available at cloudflare-generated preview URL
+- cloudflare pages automatically creates preview builds from `main` branch
+- uses preview environment with `PUBLIC_API_URL=https://relay-api-staging.fly.dev`
 
 **testing**:
-- backend: `https://plyr-api-staging.fly.dev/docs`
+- backend: `https://relay-api-staging.fly.dev/docs`
 - database: `plyr-staging` (neon)
 - storage: `audio-staging`, `images-staging` (r2)
-- atproto namespace: `fm.plyr`
 
 ### production deployment (manual)
 
-**trigger**: create github release (e.g., `v1.0.0`)
+**trigger**: run `just release` (creates github tag, merges main → production-fe)
 
 **backend**:
-1. github actions runs `.github/workflows/deploy-production.yml`
-2. deploys to `plyr-api` fly app using `fly.toml`
-3. runs `alembic upgrade head` via `release_command`
-4. backend available at `https://plyr-api.fly.dev`
+1. github actions runs `.github/workflows/deploy-prod.yml`
+2. runs `alembic upgrade head` via `release_command`
+3. backend available at `https://api.plyr.fm`
 
 **frontend**:
-- cloudflare pages production environment serves `main` branch
-- uses production environment with `PUBLIC_API_URL=https://plyr-api.fly.dev`
-- available at `https://plyr.fm` (custom domain)
+1. release script merges `main` → `production-fe` branch
+2. cloudflare pages production environment tracks `production-fe` branch
+3. uses production environment with `PUBLIC_API_URL=https://api.plyr.fm`
+4. available at `https://plyr.fm`
 
 **creating a release**:
 ```bash
 # after validating changes in staging:
 just release
-
-# or manually via gh cli:
-gh release create v1.0.0 --title "v1.0.0" --notes "release notes here"
 ```
 
-or via github UI: releases → draft new release → create tag → publish
+this will:
+1. create timestamped github tag (triggers backend deploy)
+2. merge main → production-fe (triggers frontend deploy)
 
 **testing**:
 - frontend: `https://plyr.fm`
-- backend: `https://plyr-api.fly.dev/docs`
+- backend: `https://api.plyr.fm/docs`
 - database: `plyr-prod` (neon)
 - storage: `audio-prod`, `images-prod` (r2)
-- atproto namespace: `fm.plyr`
 
 ## configuration files
 
 ### backend
 
-**fly.staging.toml**:
-- app: `plyr-api-staging`
-- release_command: `uv run alembic upgrade head` (runs migrations)
-- environment variables configured in fly.io
-
-**fly.toml**:
-- app: `plyr-api`
-- release_command: `uv run alembic upgrade head` (runs migrations)
-- environment variables configured in fly.io
-
-**transcoder/fly.toml**:
-- app: `plyr-transcoder`
-- auto-scaling enabled (stops when idle)
-- environment variables configured in fly.io
+**fly.staging.toml** / **fly.toml**:
+- release_command: `uv run alembic upgrade head` (runs migrations before deploy)
+- environment variables configured via `flyctl secrets set`
 
 ### frontend
 
···
 - framework: sveltekit
 - build command: `cd frontend && bun run build`
 - build output: `frontend/build`
+- production branch: `production-fe`
+- preview branch: `main`
 - environment variables:
-  - preview: `PUBLIC_API_URL=https://plyr-api-staging.fly.dev`
-  - production: `PUBLIC_API_URL=https://plyr-api.fly.dev`
+  - preview: `PUBLIC_API_URL=https://relay-api-staging.fly.dev`
+  - production: `PUBLIC_API_URL=https://api.plyr.fm`
 
 ### secrets management
 
-**staging secrets** (set via `flyctl secrets set`):
-- `DATABASE_URL` → neon staging connection string
-- `ATPROTO_CLIENT_ID` → `https://plyr-api-staging.fly.dev/client-metadata.json`
-- `ATPROTO_REDIRECT_URI` → `https://plyr-api-staging.fly.dev/auth/callback`
-- `ATPROTO_APP_NAMESPACE` → `fm.plyr`
-- `OAUTH_ENCRYPTION_KEY` → unique 44-char base64 fernet key
+all secrets configured via `flyctl secrets set`. key environment variables:
+- `DATABASE_URL` → neon connection string (env-specific)
+- `ATPROTO_CLIENT_ID`, `ATPROTO_REDIRECT_URI` → oauth config (env-specific URLs)
+- `OAUTH_ENCRYPTION_KEY` → unique per environment
 - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` → r2 credentials
-- `LOGFIRE_WRITE_TOKEN`, `LOGFIRE_ENABLED`, `LOGFIRE_ENVIRONMENT`
-- `FRONTEND_URL` → cloudflare pages preview URL
-- `TRANSCODER_URL` → `https://plyr-transcoder.fly.dev`
-- `TRANSCODER_AUTH_TOKEN` → shared secret for transcoder auth
-
-**production secrets** (already configured):
-- same structure but with production URLs and database
-- `ATPROTO_APP_NAMESPACE` → `fm.plyr`
-- `FRONTEND_CORS_ORIGIN_REGEX` → `^https://(www\.)?plyr\.fm$`
-- additional: `NOTIFY_BOT_HANDLE`, `NOTIFY_BOT_PASSWORD`, `NOTIFY_ENABLED`
-
-**transcoder secrets**:
-- `TRANSCODER_AUTH_TOKEN` → shared with backend for authentication
-
-**local dev (.env)**:
-- `ATPROTO_APP_NAMESPACE` → `fm.plyr`
+- `LOGFIRE_WRITE_TOKEN`, `LOGFIRE_ENVIRONMENT` → observability config
 
 ## database migrations
 
···
 
 **staging**:
 - logfire: environment filter `LOGFIRE_ENVIRONMENT=staging`
-- backend logs: `flyctl logs -a plyr-api-staging`
-- transcoder logs: `flyctl logs -a plyr-transcoder`
+- backend logs: `flyctl logs -a relay-api-staging`
 
 **production**:
 - logfire: environment filter `LOGFIRE_ENVIRONMENT=production`
-- backend logs: `flyctl logs -a plyr-api`
-- transcoder logs: `flyctl logs -a plyr-transcoder`
+- backend logs: `flyctl logs -a relay-api`
 
 ## costs
 
-**current**: ~$15-20/month
-- fly.io backend (production): $5-10/month (shared-cpu-1x, 256MB RAM)
-- fly.io backend (staging): $5-10/month (shared-cpu-1x, 256MB RAM)
-- fly.io transcoder: $0-5/month (auto-scales to zero when idle, 1GB RAM)
-- neon dev: free tier (0.5GB storage)
-- neon staging: free tier (0.5GB storage)
-- neon production: free tier (0.5GB storage, 3GB data transfer)
+**current**: ~$25-30/month
+- fly.io backend (production): ~$10/month (shared-cpu-1x, 256MB RAM)
+- fly.io backend (staging): ~$10/month (shared-cpu-1x, 256MB RAM)
+- fly.io transcoder: ~$0-5/month (auto-scales to zero when idle)
+- neon postgres: $5/month (starter plan)
 - cloudflare pages: free (frontend hosting)
-- cloudflare R2: ~$0.16/month (6 buckets: audio-dev, audio-staging, audio-prod, images-dev, images-staging, images-prod)
-
-## benefits
+- cloudflare R2: ~$0.16/month (6 buckets across dev/staging/prod)
 
-- **safe testing**: catch bugs in staging before production
-- **migration validation**: test database changes in production-like environment
-- **rollback capability**: releases enable version-based rollbacks via github
-- **clear release process**: explicit versioning via github releases
-- **single branch**: no branch management - just `main` and feature branches
+## workflow summary
 
-## deployment history
-
-1. ✅ production backend deployed (plyr-api.fly.dev)
-2. ✅ production frontend deployed (plyr.fm)
-3. ✅ transcoder service deployed (plyr-transcoder.fly.dev)
-4. ✅ staging environment configured (plyr-api-staging.fly.dev)
-5. ✅ automated deployments via github actions
-6. ✅ database migrations automated via fly.io release_command
+- **merge PR to main**: deploys staging backend, creates frontend preview
+- **run `just release`**: deploys production backend + production frontend together
+- **database migrations**: run automatically before deploy completes
+- **rollback**: revert github release or restore database from neon backup

docs/deployment/overview.md

···
-# deployment overview
-
-relay uses a three-tier deployment strategy. see [`environments.md`](./environments.md) for complete details.
-
-## quick reference
-
-| environment | frontend | backend | trigger |
-|-------------|----------|---------|---------|
-| **staging** | staging.relay-4i6.pages.dev | relay-api-staging.fly.dev | push to `staging` branch (frontend) <br> push to `main` (backend) |
-| **production** | relay-4i6.pages.dev | relay-api.fly.dev | push to `production` branch (frontend) <br> github release (backend) |
-
-## deployment workflow
-
-### staging (automatic testing)
-1. push backend changes to `main` → deploys to relay-api-staging
-2. push frontend changes to `staging` branch → deploys to staging.relay-4i6.pages.dev
-3. test end-to-end before promoting to production
-
-### production (manual release)
-1. validate changes in staging
-2. create github release → deploys backend to relay-api
-3. merge to `production` branch → deploys frontend to relay-4i6.pages.dev
-
-## key files
-
-- backend configs: `fly.toml` (production), `fly.staging.toml` (staging)
-- backend deploy: `.github/workflows/deploy-backend.yml`, `.github/workflows/deploy-production.yml`
-- frontend: cloudflare pages (configured via UI)
-- migrations: see [`database-migrations.md`](./database-migrations.md)
-
-## monitoring
-
-- logfire: filter by `deployment_environment` (staging/production)
-- fly.io: `flyctl logs -a relay-api` or `flyctl logs -a relay-api-staging`
-- neon: separate databases per environment (relay-dev, relay-staging, relay)
-
-for complete details, see [`environments.md`](./environments.md).

frontend/justfile

···
+set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
+default := "dev"
+
+# run frontend dev server (hot reloads)
+dev:
+    cd {{justfile_directory()}}/frontend && bun run dev --host 0.0.0.0
+
+# check svelte types
+check:
+    cd {{justfile_directory()}}/frontend && bun run check

justfile

···
 # plyr.fm dev workflows
+mod frontend
 mod transcoder
 
 
···
     @just --list
 
 
-# run backend server
+# run backend server (hot reloads)
 run-backend:
     uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port ${PORT:-8001}
-
-# run frontend dev server
-run-frontend:
-    cd frontend && bun run dev --host 0.0.0.0
 
 # run tests with docker-compose
 test *ARGS='tests/':
···
 migrate-status:
     uv run alembic current
 
-
-# deploy frontend to cloudflare pages
-deploy-frontend:
-    cd frontend && bun run build && bun x wrangler pages deploy .svelte-kit/cloudflare
 
 # show commits since last release
 changelog:

pyproject.toml

···
 readme = "README.md"
 license = "Apache-2.0"
 
-keywords = [
-    "music",
-    "streaming",
-    "atproto",
-    "bluesky",
-    "decentralized",
-]
+keywords = ["music", "streaming", "atproto", "bluesky", "decentralized"]
 
 [dependency-groups]
 dev = [
···
 python_files = ["test_*.py", "*_test.py"]
 python_classes = ["Test*"]
 python_functions = ["test_*"]
-filterwarnings = [
-    "ignore::pydantic.warnings.UnsupportedFieldAttributeWarning",
-]
+filterwarnings = ["ignore::pydantic.warnings.UnsupportedFieldAttributeWarning"]
 
 [tool.ruff.lint]
 fixable = ["ALL"]
 ignore = [
     "COM812",
     "PLR0913", # Too many arguments
-    "SIM102", # Dont require combining if statements
+    "SIM102",  # Dont require combining if statements
 ]
 extend-select = [
-    "B", # flake8-bugbear
-    "C4", # flake8-comprehensions
-    "I", # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "I",   # isort
     "PIE", # flake8-pie
     "RUF", # Ruff-specific
     "SIM", # flake8-simplify
-    "UP", # pyupgrade
+    "UP",  # pyupgrade
 ]
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "I001"]
 "tests/**/*.py" = ["S101"] # Allow assert in tests
-"src/backend/api/**/*.py" = ["B008"] # Allow Depends() and File() in FastAPI route defaults
+"src/backend/api/**/*.py" = [
+    "B008",
+] # Allow Depends() and File() in FastAPI route defaults
+"src/backend/main.py" = ["E402"] # Need warnings filter before imports
 
 [tool.coverage.run]
 source = ["src"]
···
 
 [tool.ty.src]
 include = ["src", "tests"]
-exclude = ["**/node_modules", "**/__pycache__", ".venv", ".git", "dist", "frontend"]
+exclude = [
+    "**/node_modules",
+    "**/__pycache__",
+    ".venv",
+    ".git",
+    "dist",
+    "frontend",
+]
 
 [tool.ty.environment]
 python-version = "3.11"

src/backend/_internal/notifications.py

···
                 {"actor": settings.notify.recipient_handle}
             )
             self.recipient_did = profile.did
-            logger.info(
+            logger.debug(
                 f"resolved {settings.notify.recipient_handle} to {self.recipient_did}"
             )
 

src/backend/main.py

···
 import asyncio
 import contextlib
 import logging
+import warnings
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+
+# filter pydantic warning from atproto library
+warnings.filterwarnings(
+    "ignore",
+    message="The 'default' attribute with value None was provided to the `Field\\(\\)` function",
+    category=UserWarning,
+    module="pydantic._internal._generate_schema",
+)
 
 from backend._internal import notification_service, queue_service
 from backend.api import (
···
 from backend.api.migration import router as migration_router
 from backend.config import settings
 from backend.models import init_db
-
-# configure logging level based on debug mode
-logging.basicConfig(
-    level=logging.DEBUG if settings.app.debug else logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-
-logger = logging.getLogger(__name__)
 
 # configure logfire if enabled
 if settings.observability.enabled:
···
         token=settings.observability.write_token,
         environment=settings.observability.environment,
     )
+
+    # configure logging with logfire handler
+    logging.basicConfig(
+        level=logging.DEBUG if settings.app.debug else logging.INFO,
+        handlers=[logfire.LogfireLoggingHandler()],
+    )
 else:
     logfire = None
+    # fallback to basic logging when logfire is disabled
+    logging.basicConfig(
+        level=logging.DEBUG if settings.app.debug else logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+# # reduce noise from verbose loggers
+# logging.getLogger("httpx").setLevel(logging.WARNING)
+
+logger = logging.getLogger(__name__)
 
 
 async def run_periodic_tasks():

src/backend/utilities/database.py

···
         if settings.observability.enabled:
             import logfire
 
-            logfire.configure(
-                token=settings.observability.write_token,
-                environment=settings.observability.environment,
-            )
             logfire.instrument_sqlalchemy(engine.sync_engine)
 
         ENGINES[cache_key] = engine

transcoder/Justfile

···
     cd {{justfile_directory()}}/transcoder && \
     TRANSCODER_HOST="${TRANSCODER_HOST:-127.0.0.1}" \
     TRANSCODER_PORT="${TRANSCODER_PORT:-8082}" \
-    cargo run
+    cargo watch -x run
 
 build:
     cd {{justfile_directory()}}/transcoder && cargo build --release