Switch backend framework from FastAPI to Django + django-ninja

[Brad-Edwards]

Summary

Migrate the Ground Control backend from FastAPI to Django 5.x with django-ninja, replacing the manual assembly of FastAPI + SQLAlchemy + Alembic + auth libraries with Django's batteries-included approach. This change is motivated by Ground Control's CRUD-heavy, permissions-heavy, admin-heavy workload profile, which aligns better with Django's strengths than FastAPI's async-first design.

Related Issues

Supersedes ADR-001 with ADR-010.

Changes

• Framework migration: Replace FastAPI with Django 5.x + django-ninja

  • Django provides ORM, migrations, admin panel, auth/permissions, middleware, and test framework out of the box
  • django-ninja preserves the Pydantic + OpenAPI DX that motivated FastAPI

• Database layer: Replace SQLAlchemy + Alembic with Django ORM + built-in migrations

  • Use psycopg 3 (async-capable) instead of asyncpg

• Authentication: Replace python-jose + passlib with Django auth + django-oauth-toolkit

  • Supports OAuth2 provider for agent authentication (ADR-007)

• Multi-tenancy: Add django-tenants for schema-per-tenant support (ADR-006)

• Audit logging: Add django-auditlog for automatic audit trails on model changes

• Background tasks: Add django-q2 for Redis-backed task processing

• Storage: Add django-storages[s3] for S3/cloud storage backend

• Project structure: Add Django settings (base, test), urls.py, asgi.py, wsgi.py, manage.py

• Dependencies: Update pyproject.toml to reflect Django ecosystem (removed: fastapi, uvicorn, starlette, sqlalchemy, alembic, asyncpg, python-jose, passlib)

• Documentation: Update CODING_STANDARDS.md, ARCHITECTURE.md, CONTRIBUTING.md, and README.md to reference Django instead of FastAPI

• ADR-010: New architecture decision record documenting the rationale for switching frameworks

Test Plan

• Unit tests pass (pytest)
• Type checking passes (mypy --strict)
• Linting passes (ruff check)
• Django settings validation passes
• No coverage regression

Checklist

• Code follows project coding standards (docs/CODING_STANDARDS.md)
• Domain layer has no framework imports (except django.db.models for model definitions)
• All new public functions have type annotations
• CHANGELOG.md updated
• Architecture decision documented (ADR-010)

https://claude.ai/code/session_013EKfsxTPEFXJf5Gu9Td5tn

[sonarqubecloud]

Quality Gate failed

Failed conditions
75.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud