chore: unify agent context into AGENTS.md (#320) (#322)

* chore: add staging smoke test script

Adds scripts/smoke_test_staging.py to verify API health and rate limiting configuration in the staging environment.

* chore: unify agent context into AGENTS.md

Consolidates CLAUDE.md and GEMINI.md into a single AGENTS.md file. Adds symlinks for compatibility.

.github/path-filters.yml

···
 migrations:
-  - "alembic/versions/**"
-  - "alembic/env.py"
-  - "alembic.ini"
+  - "backend/alembic/versions/**"
+  - "backend/alembic/env.py"
+  - "backend/alembic.ini"

.github/workflows/deploy-prod.yml

···
           if [ "${{ steps.changes.outputs.migrations }}" == "true" ]; then
             echo "🔄 migrations detected - will run via release_command before deployment"
           fi
-          flyctl deploy --config fly.toml --remote-only -a relay-api
+          flyctl deploy --config backend/fly.toml --remote-only -a relay-api
         env:
           FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_PROD }}

.github/workflows/deploy-staging.yml

···
     branches:
       - main
     paths:
-      - "src/**"
-      - "pyproject.toml"
-      - "uv.lock"
-      - "Dockerfile"
-      - "fly.staging.toml"
-      - "alembic/**"
-      - "alembic.ini"
+      - "backend/src/**"
+      - "backend/pyproject.toml"
+      - "backend/uv.lock"
+      - "backend/Dockerfile"
+      - "backend/fly.staging.toml"
+      - "backend/alembic/**"
+      - "backend/alembic.ini"
       - ".github/workflows/deploy-staging.yml"
   workflow_dispatch:
 
···
           if [ "${{ steps.changes.outputs.migrations }}" == "true" ]; then
             echo "🔄 migrations detected - will run via release_command before deployment"
           fi
-          flyctl deploy --config fly.staging.toml --remote-only -a relay-api-staging
+          flyctl deploy --config backend/fly.staging.toml --remote-only -a relay-api-staging
         env:
           FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN_STAGING }}

.github/workflows/run-pre-commit.yml

···
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-          cache-dependency-glob: "uv.lock"
+          cache-dependency-glob: "backend/uv.lock"
 
       - name: install bun
         uses: oven-sh/setup-bun@v2
···
             ${{ runner.os }}-bun-
 
       - name: install dependencies
-        run: uv sync
+        run: cd backend && uv sync
 
       - name: install frontend dependencies
         run: cd frontend && bun install
···
 
       - name: check lockfile is up to date
         run: |
+          cd backend
           if ! uv lock --check; then
             echo "❌ lockfile is out of date!"
             echo "to update the lockfile, run 'uv lock'."

.github/workflows/test-backend.yml

···
 on:
   pull_request:
     paths:
-      - "src/backend/**"
-      - "tests/**"
-      - "pyproject.toml"
-      - "uv.lock"
+      - "backend/src/backend/**"
+      - "backend/tests/**"
+      - "backend/pyproject.toml"
+      - "backend/uv.lock"
       - ".github/workflows/test-backend.yml"
 
 permissions:
···
         uses: astral-sh/setup-uv@v7
         with:
           enable-cache: true
-          cache-dependency-glob: "uv.lock"
+          cache-dependency-glob: "backend/uv.lock"
 
       - name: install dependencies
-        run: uv sync --locked
+        run: cd backend && uv sync --locked
 
       - name: run tests
         env:
           DATABASE_URL: postgresql+asyncpg://relay_test:relay_test@localhost:5432/relay_test
-        run: uv run pytest tests/
+        run: cd backend && uv run pytest tests/
 
       - name: prune uv cache
         if: always()

.pre-commit-config.yaml

···
     rev: v0.24.1
     hooks:
       - id: validate-pyproject
+        files: ^backend/pyproject\.toml$
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v3.1.0
···
     hooks:
       - id: type-check
         name: type check
-        entry: uv run ty check
+        entry: bash -c 'cd backend && uv run ty check'
         language: system
         types: [python]
         pass_filenames: false

backend/README.md

···
+../README.md

backend/justfile

···
+# backend/justfile
+set shell := ["bash", "-eu", "-o", "pipefail", "-c"]
+default := "run-backend"
+
+# run backend server (hot reloads)
+run-backend:
+    uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port ${PORT:-8001}
+
+# run tests with docker-compose
+test *ARGS='tests/':
+    docker compose -f tests/docker-compose.yml up -d
+    uv run pytest {{ ARGS }}
+    docker compose -f tests/docker-compose.yml down
+
+# run type checking and linting
+lint:
+    uv run ty check
+    uv run ruff check .
+
+# create a new database migration
+migrate MESSAGE:
+    uv run alembic revision --autogenerate -m "{{ MESSAGE }}"
+
+# upgrade database to latest migration
+migrate-up:
+    uv run alembic upgrade head
+
+# show current migration status
+migrate-status:
+    uv run alembic current
+
+# create a github release (triggers production deployment)
+release:
+    ./scripts/release

justfile

···
 # plyr.fm dev workflows
 mod frontend
 mod transcoder
+mod backend # Backend commands are now managed in backend/justfile
 
 
 # show available commands
···
     ln -s AGENTS.md CLAUDE.md
     ln -s AGENTS.md GEMINI.md
 
-# run backend server (hot reloads)
-run-backend:
-    uv run uvicorn backend.main:app --reload --host 0.0.0.0 --port ${PORT:-8001}
-
-# run tests with docker-compose
-test *ARGS='tests/':
-    docker compose -f tests/docker-compose.yml up -d
-    uv run pytest {{ ARGS }}
-    docker compose -f tests/docker-compose.yml down
-
-# run type checking
-lint:
-    uv run ty check
-
-# create a new database migration
-migrate MESSAGE:
-    uv run alembic revision --autogenerate -m "{{ MESSAGE }}"
-
-# upgrade database to latest migration
-migrate-up:
-    uv run alembic upgrade head
-
-# show current migration status
-migrate-status:
-    uv run alembic current
+    # Setup sub-modules if they have setup recipes
+    # just frontend setup # Uncomment if frontend/justfile gets a setup
+    # just backend setup # Uncomment if backend/justfile gets a setup
 
 
 # show commits since last release
 changelog:
     @git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:'%C(yellow)%h%Creset %C(blue)%ad%Creset %C(green)%s%Creset %C(dim)- %an%Creset' --date=relative
 
-# create a github release (triggers production deployment)
-release:
-    ./scripts/release
-
 # deploy frontend only (promote remote main to production-fe branch)
 release-frontend-only:
     git fetch origin main
-    git push origin origin/main:production-fe
+    git push origin origin/main:production-fe

pyproject.toml backend/pyproject.toml

···
     "cachetools>=6.2.1",
     "pytest-asyncio>=0.25.3",
     "aioboto3>=15.5.0",
-    "slowapi>=0.1.9",
+    "slowapi @ git+https://github.com/zzstoatzz/slowapi.git@fix-deprecation",
 ]
 
 requires-python = ">=3.11"
···
 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"]

uv.lock backend/uv.lock

···
     { name = "python-dotenv", specifier = ">=1.1.0" },
     { name = "python-jose", extras = ["cryptography"], specifier = ">=3.3.0" },
     { name = "python-multipart", specifier = ">=0.0.20" },
-    { name = "slowapi", specifier = ">=0.1.9" },
+    { name = "slowapi", git = "https://github.com/zzstoatzz/slowapi.git?rev=fix-deprecation" },
     { name = "sqlalchemy", specifier = ">=2.0.36" },
     { name = "uvicorn", extras = ["standard"], specifier = ">=0.34.0" },
 ]
···
 [[package]]
 name = "slowapi"
 version = "0.1.9"
-source = { registry = "https://pypi.org/simple" }
+source = { git = "https://github.com/zzstoatzz/slowapi.git?rev=fix-deprecation#4a9e9a228ec3dbcad28e8fa8b6112da7052ee2d9" }
 dependencies = [
     { name = "limits" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/a0/99/adfc7f94ca024736f061257d39118e1542bade7a52e86415a4c4ae92d8ff/slowapi-0.1.9.tar.gz", hash = "sha256:639192d0f1ca01b1c6d95bf6c71d794c3a9ee189855337b4821f7f457dddad77", size = 14028, upload-time = "2024-02-05T12:11:52.13Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2b/bb/f71c4b7d7e7eb3fc1e8c0458a8979b912f40b58002b9fbf37729b8cb464b/slowapi-0.1.9-py3-none-any.whl", hash = "sha256:cfad116cfb84ad9d763ee155c1e5c5cbf00b0d47399a769b227865f5df576e36", size = 14670, upload-time = "2024-02-05T12:11:50.898Z" },
 ]
 
 [[package]]