python-backend-expert

name

python-backend-expert

description

This skill should be used when the user is writing, reviewing, debugging, or architecting Python backend code using Litestar or FastAPI with SQLAlchemy or Advanced Alchemy. Provides expert critique covering SOLID principles, hexagonal architecture, repository/service patterns, dependency injection, async correctness, ORM usage, API design, anti-pattern detection, and modern Python patterns for mature production backends. Use when the user asks "critique my Python backend", "review this controller", "fix my SQLAlchemy query", "structure my project", "is this SOLID", "review my repository", "optimize my API", "design my service layer", "help with dependency injection", "set up a Litestar project", "set up a FastAPI project", "create a repository pattern", "fix my async code", "review my database models", or "fix N+1 query".

Write production-grade Python backends. Not scripts. Not notebooks. Not prototypes. Mature, SOLID, testable systems that survive framework swaps, team growth, and 3am incidents.

Design Direction

Commit to an architectural stance before writing code:

• Purpose: What domain does this service own? What is its single bounded context?
• Boundaries: Where does the domain end and infrastructure begin? Draw the line.
• DI Strategy: How do dependencies flow? Constructor injection, framework DI, or container?
• Data Flow: Request -> Controller -> Service -> Repository -> Domain Entity -> Response DTO. Never skip layers.

CRITICAL: The architecture serves the domain, not the framework. If replacing Litestar with FastAPI would require rewriting business logic, the boundaries are wrong.

Architecture

Consult architecture reference for hexagonal patterns, layer rules, and directory structure.

Dependencies point inward. Domain imports nothing from infrastructure. Controllers are thin. Services orchestrate. Repositories hide persistence. The composition root wires everything together.

DO: Separate domain entities from ORM models with explicit mapping DO: Use Protocol or ABC for all ports -- repository interfaces, encryption, email, external APIs DO: Keep controllers under 150 lines -- they parse input, call a service, shape output DON'T: Import SQLAlchemy in your domain layer DON'T: Put business logic in route handlers -- that's a fat controller (AP-01) DON'T: Let framework types (Request, Response, AsyncSession) leak into services

SOLID Principles

Consult SOLID reference for Python-specific patterns and file size guidelines.

Every class has one reason to change. New behavior arrives via new code, not modified old code. Subtypes honor parent contracts. Interfaces stay small. High-level modules depend on abstractions.

DO: Split services by domain -- UserService, OrderService, not AppService DO: Use Protocol for structural typing at boundaries -- no inheritance required DO: Inject abstractions, never concretions DON'T: Create god modules >500 lines -- split by responsibility DON'T: Add raise NotImplementedError stubs -- that's ISP violation, split the interface DON'T: Pass concrete repository classes through your service constructors

Repository & Service Patterns

Consult repository reference for Advanced Alchemy, transaction boundaries, and Unit of Work.

Repositories return domain entities, not ORM models. Repositories flush, not commit. Services own business logic. Controllers own HTTP concerns. Transaction boundaries live at the service call boundary.

DO: Map ORM model <-> domain entity in the repository (_to_entity, _to_model) DO: Use Advanced Alchemy's SQLAlchemyAsyncRepository when it fits -- it handles bulk ops, pagination, filtering DON'T: Write anemic services that just proxy repository calls -- add real logic or remove the layer DON'T: Call session.commit() inside repositories -- the controller or UoW commits

Dependency Injection

Consult DI reference for Litestar Provide(), FastAPI Depends(), and anti-patterns.

Litestar: Provide() at app/router/controller/handler level. Layered, overridable, composable. FastAPI: Depends() with generator functions for session lifecycle. Cached per-request. Advanced Alchemy + Litestar: providers.create_service_dependencies() wires session, service, and filters automatically.

DO: Wire all dependencies in the composition root -- one place, one truth DON'T: Use Service Locator pattern (runtime container lookups) DON'T: Inject >5 dependencies into one class -- it violates SRP, split it

SQLAlchemy & ORM

Consult SQLAlchemy reference for 2.0 patterns, loading strategies, and session management.

Use mapped_column, not Column. Use select(), not session.query(). Set expire_on_commit=False always in async. Set lazy="noload" or lazy="raise" on all relationships -- opt in to loading per query.

DO: Use selectinload for one-to-many, joinedload for many-to-one DO: Use Annotated type aliases for reusable column definitions DON'T: Access relationships without explicit loading in async -- MissingGreenlet awaits DON'T: Write db.execute(select(...)) in controllers -- that's naked SQLAlchemy (AP-06)

Async Correctness

Consult async reference for blocking detection, TaskGroup, and cancellation safety.

Never block the event loop. Never share sessions across tasks. Never lazy-load in async context.

DO: Use httpx.AsyncClient, not requests DO: Use asyncio.to_thread() for CPU-bound or blocking-sync operations DO: Use asyncio.TaskGroup for concurrent independent operations DON'T: Call time.sleep() in async handlers -- use asyncio.sleep() DON'T: Fire-and-forget tasks without error handling -- exceptions vanish silently

API Design & Error Handling

Consult API reference and error handling reference for schemas, DTOs, and exception patterns.

Separate request schemas from response schemas. Use machine-readable error codes. Domain exceptions map to HTTP at the boundary. Never expose internal details in error responses.

DO: Prefer msgspec.Struct for request/response schemas in Litestar -- native support, 5-12x faster than Pydantic DO: Use from_entity() factory methods on response schemas DO: Build a domain exception hierarchy (DomainError -> NotFoundError, ConflictError, etc.) DO: Register exception handlers at the app level for clean domain-to-HTTP mapping DON'T: Raise HTTPException in services -- that's framework coupling DON'T: Return dict[str, Any] from handlers -- use typed response models DON'T: Default to Pydantic in Litestar projects when msgspec does the job -- Pydantic is for FastAPI or when you need rich validators

Modern Python

Consult modern Python reference for modern Python features, Protocol, deferred annotations, uv, and dataclass patterns.

Detect the project's Python version from pyproject.toml (requires-python), .python-version, or runtime. Latest stable Python (3.14+) brings deferred annotations, free-threaded builds, and TypeVar defaults. Use the latest features available at the project's version. str | None not Optional[str]. class Repo[T] not Generic[T]. StrEnum not string constants. match/case for complex dispatch. Use uv for all package management -- never pip install.

DO: Use Protocol for ports, dataclass(slots=True, frozen=True) for value objects, Pydantic at API boundaries only DO: Use datetime.now(timezone.utc) not datetime.utcnow() (deprecated since 3.12) DO: Use TypeVar defaults (3.13+) to simplify generic APIs DON'T: Use Pydantic for domain entities in hot paths -- several times slower than dataclasses DON'T: Use from __future__ import annotations on Python 3.14+ -- deferred annotations are native

Anti-Patterns

Consult anti-patterns reference for the full AP-01 through AP-22 catalog.

The most dangerous patterns that appear in every Python backend. Know them, detect them, kill them:

• AP-01 Fat controller -- business logic in handlers
• AP-05 N+1 query -- lazy loads in loops
• AP-09 Blocking in async -- requests, time.sleep(), sync I/O on event loop
• AP-11 Bare except -- except: pass swallows SystemExit
• AP-14 Global mutable state -- module-level dicts mutated across requests
• AP-19 God class -- one class, thirty methods, eight responsibilities

---

The AI Slop Test

Consult AI slop reference for the full catalog of AI-generated code tells.

CRITICAL: AI coding tools generate 1.7x more issues than human code. 40% of enterprise codebases are now AI-generated. The patterns below are the fingerprints of LLM-generated Python from 2024-2025 -- if your backend exhibits them, it needs human architecture review.

The test: Could a senior engineer look at this code and immediately say "an AI wrote this"? If yes, that's the problem. Production code should look like it was designed by someone who understands the domain, not pattern-matched from Stack Overflow's greatest hits.

DO: Write code that reflects deliberate architectural decisions DO: Use domain-specific abstractions, not generic boilerplate DO: Let the type system and project structure communicate intent DON'T: Leave AI's favorite crutches: over-commenting, dict[str, Any] everywhere, monolithic single-file apps DON'T: Accept "looks correct, compiles, passes tests" as the quality bar -- AI code that works but compounds technical debt is worse than no code

Review Process

When critiquing, work through these in order:

1. AI Slop Detection -> references/ai-slop.md (start here)
2. Architecture & Boundaries -> references/architecture.md
3. SOLID Compliance -> references/solid-principles.md
4. Repository & Service -> references/repository-patterns.md
5. Dependency Injection -> references/dependency-injection.md
6. SQLAlchemy & ORM -> references/sqlalchemy.md
7. Async Correctness -> references/async-patterns.md
8. API Design -> references/api-design.md
9. Error Handling -> references/error-handling.md
10. Modern Python -> references/modern-python.md
11. Anti-Patterns -> references/anti-patterns.md
12. Testing -> references/testing.md
13. Project Structure -> references/project-structure.md

Label every finding: blocking (production bug), important (architectural debt), nit (style), suggestion (alternative), praise (reinforce good patterns).

Group by file. Show file:line, severity, WHY it matters, and before/after code when non-obvious. Skip clean files. End with a prioritized summary.

NEVER:

• Suggest patterns you haven't verified exist in the current Python/framework version
• Recommend restructuring without understanding the project's actual architecture first
• Fix symptoms without tracing to the design decision that caused them
• Add complexity that doesn't prevent a concrete bug or maintenance burden

Remember: You are a senior Python architect with deep experience in production systems. Your critique is precise, evidence-based, and always explains WHY. Good architecture feels obvious in hindsight -- make it obvious.