System status — Degraded

Your Python backend works.

That's not the same as being production-ready.

A practical engineering manual for turning fragile, legacy and AI-generated Python backends into systems you can test, observe, deploy and trust.

Get the free production checklist Explore PRODUCTION-7 View the project on GitHub →

SYSTEM / BACKEND-001
INSPECTION / COMPLETEP7 / 3.03

APISVCDB

DEGRADEDparcelflow-backend · FastAPI · Python 3.11

Topics coveredPythonFastAPIPostgreSQLpytestDockerAWSSQLAlchemyCI/CDObservabilityAI-Assisted Engineering

The engineering problem

Working code can still be bad engineering.

A backend that passes its tests in development can still exhibit cascading failures, invisible data corruption and complete unrecoverability under production conditions.

“The gap between working and trustworthy is not filled by more features. It is filled by disciplined engineering.”

Failure pattern catalogue DEGRADED

A-001Architecture

Business logic inside API route handlers

A-003Architecture

Database session management without boundaries

T-001Testing

Test suites that mock everything and catch nothing

C-002Correctness

Inconsistent error responses and status codes

C-005Correctness

No transaction strategy — partial writes on failure

P-002Performance

Incorrect async usage blocking the event loop

P-007Performance

External calls with no timeout, retry or circuit breaker

C-007Correctness

Missing idempotency — safe retry is impossible

O-001Observability

No structured logging — production failures are invisible

A-009Architecture

AI-generated code with duplicated logic and inconsistent abstractions

Code inspection

What's wrong with this endpoint?

It works in development. Under production conditions, it fails in at least seven distinct ways.

Inspection ReportREF / BH-001

Status DEGRADED

Issues17

Sourceroutes/orders.py

1@app.post("/orders")2def create_order(order: dict):013    db = SessionLocal()024 5    customer = db.query(Customer).filter(6        Customer.id == order["customer_id"]7    ).first()8 9    if not customer:0310        return {"error": "customer not found"}11 12    shipment = Shipment(...)13    db.add(shipment)14    db.commit()0415 16    requests.post(SHIPPING_PROVIDER_URL,0517        json={"order_id": order["id"]})18    send_email(customer.email)0619 20    return {"success": True}07

17engineering problems
detected FAILED

01P7-A-007Validation

Untyped dict parameter. No Pydantic model, serialisation contract or reliable OpenAPI schema.

02P7-C-003Session management

Session opened without a context manager. Exceptions can leave it open indefinitely.

03P7-C-004Error model

Returns HTTP 200 with an error object; clients cannot distinguish failure by status.

04P7-C-005Transaction

Commits before external I/O, leaving partial state when a downstream call fails.

+ 3 more findings · See how we rescue it →

05P7-P-007External I/O

The shipping request has no timeout, retry policy or circuit breaker.

06P7-O-004Side effects

Email delivery is synchronous and unobserved; a failure is not recoverable.

07P7-C-007Idempotency

A client retry can create the same shipment more than once.

The diagnostic framework

Production readiness is not a feeling.

PRODUCTION-7 evaluates systems across seven engineering dimensions. Each is scored, diagnosed and addressed.

Explore the framework

AArchitecture

2.4

CCorrectness

4.8

TTesting

1.9

SSecurity

3.6

PPerformance

4.2

OObservability

1.5

DDeployability

2.8

Reference mark at 7.0 = minimum production threshold

Architecture transformation

Rescue the system, not just the code.

Before · initial state

main.py — 3,200 lines

@app.get("/users")
@app.post("/orders")
# business logic
# database calls
# email sending
# everything.

Everything tightly coupled. Nothing independently testable.

→

After · production-ready

app/ — structured boundaries

app/
├── api/routes/
├── domain/orders/
├── services/
├── repositories/
├── infrastructure/
└── tests/

Routes delegate, never implement
Domain logic is independently testable
Infrastructure executes behind boundaries

! Architecture follows the problem. The goal is boundaries, not folders.

The Python Backend Rescue Manual

One backend. One complete rescue.

Every chapter follows ParcelFlow — a fictional logistics backend deliberately constructed with the engineering problems most often found in real Python systems.

ProjectPARCELFLOWInitial statusDEGRADEDMissionPRODUCTION RESCUE

01Audit DEGRADED

02Architecture

03Data

04Testing

05Security

06Observability

07Performance

08Events

09Deployment

10AI Engineering

11Production Gate VERIFIED

Engineering topics

Every layer of a production Python backend.

Architecture

Boundaries · Service layers · Repository pattern · Dependency injection · Legacy refactoring

Data

PostgreSQL · SQLAlchemy async · Transactions · Constraints · Alembic

Testing

pytest · Integration tests · Testcontainers · Failure paths · Coverage strategy

Production Eng.

Docker · Configuration · Secrets · Structured logging · Tracing

Performance

Async correctness · Query analysis · Connection tuning · Load testing

Distributed Sys.

Background tasks · Queues · Events · Idempotency

AWS

IAM · Deployment strategy · Rollback · CI/CD

AI Engineering

AI-generated debt · Refactoring · Quality gates · Code review

AI-assisted engineering

AI can write your code.

It won't own your production incident.

AI increases development speed — and the speed at which weak tests, duplicated logic and architectural debt enter a codebase.

AI Coding AgentCursor · Copilot · Claude

↓

Generated CodeFast · Inconsistent · Unverified

↓

Deterministic Engineering GatesRUFF · MYPY · PYTEST · COVERAGE · SECURITY · ARCHITECTURE

↓

Human DecisionShip · Repair · Reject

Free resource

Is your backend actually production-ready?

Run your Python backend through a practical production-readiness inspection: 100 points across all seven P7 dimensions.

Production Readiness Inspection

The Production-Ready Python Backend Checklist

01 / Architecture[ ] Boundaries are explicit[ ] Business logic is isolated
02 / Correctness[ ] Transaction boundaries defined[ ] Idempotency keys implemented
03 / Testing[ ] Failure paths are tested

+ 7 more categories · 100 inspection points

Publication status

Follow the rescue as it's built.

The manual is in active development. The structure is set, ParcelFlow is being built and the first chapters are in progress.

01Selected chapters as they are completed
02Engineering notes on the rescue methodology
03ParcelFlow repository updates and branch releases
04PRODUCTION-7 framework developments
05Launch information before public announcement
06Early-access pricing

Join the early-access list

Python Backend Rescue · Field Manual / 001

The Python Backend Rescue Manual

A practical field manual for turning fragile Python backends into production-grade systems.

JOSÉ MIGUEL MANGASField Manual — In Development

bash — parcelflow

$ git clone github.com/pbrescue/parcelflowCloning into 'parcelflow'...$ git checkout broken# 3,200-line main.py. No tests. Start here.$ git checkout production# PRODUCTION-7 score: 9.1. Ship it.

Open source companion

Don't just read the rescue. Inspect the code.

ParcelFlow will expose the exact state of the codebase at every stage of the rescue. Its public repository is not yet available.

GitHub repository coming soon

Author

José Miguel Mangas

Backend / Full-Stack Software Engineer

Backend and full-stack software engineer working across Python APIs, data pipelines, cloud infrastructure and production systems.

Python Backend Rescue grew out of years working with Python backends at different stages of their lifecycle — from greenfield builds to legacy rescues.

PythonFastAPIPostgreSQLAWSDockerCI/CDData pipelinesAI-assisted engineering

Frequently asked

Questions

Is this a beginner Python book?

Is this only about FastAPI?

Is this an AWS book?

Is this an AI coding book?

When will the book be available?

Will the code be available?

Your backend already works.

Now make it trustworthy.

Get the free production checklist Explore PRODUCTION-7 View on GitHub →