ADR-001: Use Litestar as Web Framework

Status

Accepted

Context

We are migrating python.org from Django to a modern async Python web framework. The current Django implementation has served well but faces challenges:

Problem Statement

  • Performance: Synchronous Django WSGI struggles with concurrent connections

  • Type Safety: Limited type checking in Django codebase

  • Modern Features: Missing native async/await support throughout

  • Developer Experience: Verbose boilerplate for API development

  • Dependency Injection: Manual dependency management patterns

Constraints

  • Must support async/await throughout the stack

  • Must integrate well with async SQLAlchemy 2.0

  • Must provide OpenAPI documentation out of the box

  • Must have strong type safety support

  • Must be production-ready and actively maintained

  • Team must be able to ramp up within reasonable time

Requirements

Functional Requirements:

  • RESTful API support

  • Template rendering (Jinja2)

  • Session management

  • Authentication/Authorization

  • File uploads/downloads

  • WebSocket support (future)

Non-Functional Requirements:

  • Handle 10,000+ requests per second

  • Response time < 100ms for API endpoints

  • Strong type safety with mypy

  • Excellent developer experience

  • Comprehensive documentation

Decision

We will use Litestar 2.x as the web framework for the python.org migration.

Chosen Solution

Litestar provides:

  • Full async/await support with ASGI

  • Advanced dependency injection system

  • Native SQLAlchemy integration via Advanced Alchemy

  • Automatic OpenAPI documentation

  • Strong type safety with Pydantic v2

  • Excellent performance (10,000+ req/s)

  • Active development and community

Rationale

  1. Type Safety: Litestar enforces type hints throughout, catching errors at development time

  2. Performance: ASGI-based with excellent benchmarks (comparable to FastAPI)

  3. DX: Clean API, minimal boilerplate, excellent error messages

  4. Ecosystem: Advanced Alchemy provides battle-tested SQLAlchemy patterns

  5. Documentation: Auto-generated OpenAPI docs with Swagger UI and ReDoc

  6. Community: Active development, responsive maintainers, growing adoption

Consequences

Positive Consequences

  • Performance Improvement: 5-10x throughput increase over Django WSGI

  • Type Safety: Catch bugs during development, not production

  • Developer Velocity: Less boilerplate, faster feature development

  • API-First: Excellent API development experience

  • Modern Patterns: Leverage latest Python async features

  • Testing: Better testability with dependency injection

Negative Consequences

  • Learning Curve: Team needs to learn new framework

  • Ecosystem: Smaller ecosystem compared to Django/FastAPI

  • Migration Effort: Significant upfront migration work

  • Fewer Third-Party Packages: May need to build custom integrations

  • Documentation: Less Stack Overflow content than Django

Risks & Mitigation

Risk

Likelihood

Impact

Mitigation

Team adoption challenges

Medium

Medium

Comprehensive training, pair programming

Missing features

Low

Medium

Contribute to Litestar, build custom solutions

Performance issues

Low

High

Extensive benchmarking, load testing

Security vulnerabilities

Low

High

Regular security audits, dependency updates

Community support declines

Low

High

Active contribution, relationship with maintainers

Migration Path

  1. Foundation (Week 1-2): Set up Litestar project structure

  2. Core Features (Week 3-4): Implement auth, database, core patterns

  3. Domain Migration (Week 5-12): Migrate Django apps one by one

  4. Testing (Week 13-14): Comprehensive testing and optimization

  5. Deployment (Week 15-16): Staged rollout to production

Alternatives Considered

Alternative 1: FastAPI

Description: Popular async web framework with automatic API documentation

Pros:

  • Larger community and ecosystem

  • More Stack Overflow content

  • Proven at scale (used by Microsoft, Uber, Netflix)

  • Excellent documentation

  • More third-party packages

Cons:

  • Less integrated dependency injection

  • Manual SQLAlchemy setup and patterns

  • More boilerplate for complex applications

  • Less opinionated structure

  • Pydantic v1 in older versions (compatibility issues)

Why not chosen: While FastAPI is excellent, Litestar’s deeper SQLAlchemy integration via Advanced Alchemy, superior dependency injection, and more opinionated structure better suits our needs for a large-scale application migration.

Alternative 2: Starlette

Description: Low-level ASGI framework (FastAPI is built on Starlette)

Pros:

  • Maximum flexibility

  • Minimal overhead

  • Complete control over implementation

  • Battle-tested foundation

Cons:

  • Too low-level, requires building many abstractions

  • No built-in OpenAPI documentation

  • No built-in dependency injection

  • Significantly more boilerplate

  • Longer development time

Why not chosen: Too low-level for our needs. We’d essentially be building our own framework on top of Starlette, which doesn’t align with the goal of faster development.

Alternative 3: Keep Django, Add Async Support

Description: Use Django 4.2+ async views with async ORM

Pros:

  • Minimal migration effort

  • Team already familiar

  • Mature ecosystem

  • All existing code works

Cons:

  • Django’s async support still immature

  • ORM async support incomplete

  • Performance gains limited by architecture

  • Still dealing with legacy patterns

  • Misses opportunity for modernization

Why not chosen: Django’s async support is improving but still not first-class. The migration effort to properly leverage async Django would be comparable to migrating to a native async framework, without the benefits.

Implementation Notes

Timeline

  • Foundation: 2 weeks

  • Core Domains: 3 weeks

  • Feature Domains: 4 weeks

  • Templates & Frontend: 2 weeks

  • Testing & Optimization: 2 weeks

  • Deployment: 2 weeks

  • Total: ~15-16 weeks

Dependencies

  • Litestar: 2.x latest stable

  • Advanced Alchemy: Latest (Litestar ecosystem)

  • SQLAlchemy: 2.0+

  • Pydantic: 2.x

  • Jinja2: 3.x for templates

  • SAQ: Background task processing

  • Redis: Session storage and task queue

Success Criteria

  • All Django functionality replicated

  • API response time < 100ms (p95)

  • Throughput > 10,000 req/s

  • Zero downtime deployment

  • 90%+ test coverage

  • Type checking passes with mypy strict mode

  • Security audit passes

Rollback Strategy

If critical issues arise post-deployment:

  1. Immediate: Rollback DNS to Django instance

  2. Short-term: Run both systems in parallel with traffic splitting

  3. Long-term: Address issues and re-deploy Litestar incrementally

Keep Django instance running for 30 days post-cutover.

References

Metadata

  • Author: ARCHITECT Agent

  • Date: 2025-11-25

  • Reviewers: TBD

  • Related ADRs: ADR-002 (SAQ), ADR-003 (Meilisearch)

  • Tags: framework, architecture, performance, async

Revision History

Version

Date

Author

Changes

1.0

2025-11-25

ARCHITECT

Initial version