Database UI

[vtnphan]

Pull Request

Summary

SBP-255 Add optional DB admin/debug tooling

Changes

• Added optional Starlette Admin integration and admin-only debug APIs:
  • app/db/admin.py (new)
  • mounted from app/main.py via mount_db_admin(app)
  • debug endpoints under /admin/debug/* for S3 objects, run inputs, and run outputs
  • role-based access checks and session/cookie handling for admin UI
• Added/updated DB migrations:
  • workflow_runs.binder_name
  • workflow_runs.sample_id
  • run_metrics.final_design_count
• Updated docs and examples:
  • .env.example admin-related env vars
  • README.md API/env/docs for optional DB admin UI
• Added tests:
  • tests/test_db_admin.py
  • updated tests/test_main.py
  • updated tests/test_services_job_utils.py
• Tooling/config updates:
  • added starlette-admin dependency
  • mypy/coverage exclusions for app/db/admin.py in pyproject.toml

How to Test

1. Install deps:
   • uv sync --extra dev
2. Run lint/type checks:
   • uv run ruff check app tests
   • uv run black --check app tests
   • uv run mypy app --ignore-missing-imports
3. Run tests with coverage:
   • uv run pytest --cov=app --cov-report=term-missing -q
4. Validate admin UI (optional):
   • set ENABLE_DB_ADMIN=true
   • run backend and open /admin
   • verify /admin/debug/s3-objects, /admin/debug/run-inputs, /admin/debug/run-outputs
5. Validate score path behavior:
   • run tests/test_services_job_utils.py and confirm sample-based ranker path coverage

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have added tests that prove my fix is effective or that my feature works
• I have added or updated documentation where necessary
• I have run linting and unit tests locally
• The code follows the project's style guidelines

[marius-mather]

I think there are a few things to look at here, particularly with how the admin role is checked from the access token. It's important not to overcomplicate this, try to look at the specific claims we use in Auth0 to store roles and only look at that in your code.

[Copilot]

Pull request overview

Adds optional database admin/debug UI tooling to the FastAPI backend, mounted conditionally via an environment flag, along with docs/config and tests to validate mounting and access helpers.

Changes:

• Introduces Starlette Admin + admin-only debug endpoints (/admin/debug/*) and mounts them from create_app().
• Adds tests covering admin mounting/config gating and debug endpoint responses.
• Updates dependencies/config/docs for enabling the optional admin UI.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
app/db/admin.py	New Starlette Admin + debug API mounting helpers, Auth0-based login/session handling, and admin access dependency.
app/main.py	Calls mount_db_admin(app) during app creation.
tests/test_db_admin.py	New tests for enabling logic, mounting behavior, claims role checks, and debug endpoints.
tests/test_main.py	Verifies admin debug routes are present when enabled via env vars.
tests/conftest.py	Forces ENABLE_DB_ADMIN=false for tests by default.
pyproject.toml	Adds starlette-admin dependency and excludes app/db/admin.py from mypy/coverage.
uv.lock	Locks starlette-admin (and jinja2) into the resolved dependency set.
README.md	Documents optional /admin UI and required env vars.
.env.example	Adds admin-related env vars and changes example DB port.
app/services/job_utils.py	Minor typing cleanup for prefixes.
app/routes/workflows.py	Removes/shortens a few placeholder comments/unused assignments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[marius-mather]

This looks good overall, I just want to make sure we're not overcomplicating the admin login. I was able to implement this without having to render my own HTML etc., see: https://github.com/AustralianBioCommons/aai-backend/blob/08e8c0ca593844c5b176003d11b3601e9e6f86b9/db/st_admin.py#L321.

Where possible, I think you want to avoid creating HTML pages etc. where you could take the simpler route and just do a redirect.

[marius-mather]

looking good now, thanks!

[vtnphan]

Hi @marius-mather , just solved conflicts due to previous PR, can you help to have a quick look and approve again? Thank you!

[marius-mather]

all good - but try to avoid force-pushing in future as it can mess up history and do unexpected things. you can usually fix merge conflicts by merging main into your PR branch