Untyped dict parameter. No Pydantic model, serialisation contract or reliable OpenAPI schema.
RescueGitHubArticlesGet Checklist
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.
APISVCDATA
01 · API interfaceValidate the external contract and delegate the operation.02 · Service boundaryApply business rules and control transaction boundaries.03 · Durable dataProtect state with constraints and observable persistence.
DEGRADEDREFERENCE SYSTEM · FastAPI · Python · PRODUCTION-7Topics coveredPythonFastAPIPostgreSQLpytestDockerCloud InfrastructureSQLAlchemyCI/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 inspection01P7-A-007Validation 02P7-C-003Session management 03P7-C-004Error model 04P7-C-005Transaction 05P7-P-007External I/O 06P7-O-004Side effects 07P7-C-007Idempotency
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()0245 customer = db.query(Customer).filter(6 Customer.id == order["customer_id"]7 ).first()89 if not customer:0310 return {"error": "customer not found"}1112 shipment = Shipment(...)13 db.add(shipment)14 db.commit()041516 requests.post(SHIPPING_PROVIDER_URL,0517 json={"order_id": order["id"]})18 send_email(customer.email)061920 return {"success": True}07
17engineering problems
detected FAILED
detected FAILED
Session opened without a context manager. Exceptions can leave it open indefinitely.
Returns HTTP 200 with an error object; clients cannot distinguish failure by status.
Commits before external I/O, leaving partial state when a downstream call fails.
+ 3 more findings · See how we rescue it →
The shipping request has no timeout, retry policy or circuit breaker.
Email delivery is synchronous and unobserved; a failure is not recoverable.
A client retry can create the same shipment more than once.
The diagnostic framework
Production readiness is not a feeling.
PRODUCTION-7 is a repeatable method for assessing a backend across Architecture, Correctness, Testing, Security, Performance, Observability and Deployability.
Each dimension is scored from evidence, converted into concrete repair work and checked again at a production gate. A system passes only when every dimension reaches the minimum threshold — a strong average cannot hide a critical weakness.
PRODUCTION-7 · Diagnostic ReportSystem Score
3.03/ 10.00
DEGRADED
parcelflow-backend
v0.1.0 · Python 3.11
v0.1.0 · Python 3.11
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 transformationBefore · initial state After · production-ready
Rescue the system, not just the code.
main.py — 3,200 lines
@app.get("/users")
@app.post("/orders")
# business logic
# database calls
# email sending
# everything.Everything tightly coupled. Nothing independently testable.
→
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.
ParcelFlow is the manual's fictional logistics backend: a working FastAPI system for customers, orders and shipments, intentionally built with realistic architectural, data, testing and operational weaknesses.
It is both the continuous case study and the future companion repository. Readers inspect the degraded version with PRODUCTION-7, repair the same codebase chapter by chapter and finish by running it through the production gate again.
ProjectPARCELFLOWInitial statusDEGRADEDMissionPRODUCTION RESCUE
01Audit DEGRADED
02Architecture
03Data
04Testing
05Security
06Observability
07Performance
08Events
09Deployment
10AI Engineering
11Production Gate VERIFIED
Engineering topics01 02 03 04 05 06 07
The seven dimensions of a production-ready Python backend.
Architecture
Boundaries · Service layers · Repository pattern · Dependency injection · Legacy refactoring
Correctness
Transactions · Constraints · Idempotency · Error contracts · Safe migrations
Testing
pytest · Integration tests · Testcontainers · Failure paths · Coverage strategy
Security
Identity and access · Secrets · Input boundaries · Dependency risk · Secure defaults
Performance
Async correctness · Query analysis · Connection tuning · Load testing
Observability
Structured logging · Metrics · Tracing · Health signals · Failure diagnosis
Deployability
Docker · Configuration · Cloud infrastructure · CI/CD · Rollback
Engineering note / 001
Read the articleThe seven dimensions of a production-ready Python backend
Architecture, correctness, testing, security, performance, observability and deployability — and the evidence required to trust each one.
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.
Engineering noteQuality gates for AI-generated Python →
AI Coding AgentCursor · Copilot · Claude
↓Generated CodeFast · Inconsistent · Unverified
↓Deterministic Engineering GatesRUFF · MYPY · PYTEST · COVERAGE · SECURITY · ARCHITECTURE
↓Human DecisionShip · Repair · Reject
Free Claude Code resource
Give Claude Code the context your backend deserves.
Get a production-minded CLAUDE.md for FastAPI, Flask and Django — with architecture boundaries, testing rules, security guardrails and a clear definition of done.
Built for Python backend workGet the free CLAUDE.md →Enter your email on the resource page and receive the file immediately.
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
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$ 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.
Author
José Miguel Mangas
Backend / Full-Stack Software EngineerI'm a backend and full-stack software engineer specialising in Python, backend architecture, data platforms and cloud systems.
My experience spans aviation, technology, telecommunications and publishing, including work with British Airways via Parser, EPAM NEORIS, Apple, Jazztel, Grupo Planeta and Telefónica via PwC. Python Backend Rescue distils that production experience into practical engineering guidance.
Frequently asked
Questions
No. It is for engineers who already write and ship Python and want to improve architecture, correctness and production operations.
FastAPI is the primary example, but the engineering methods apply to Django, Flask and other Python backend systems.
No. Deployment examples may use concrete services, but the engineering framework is cloud-independent and focuses on portable production principles.
No. It treats AI-assisted development as an input that still requires deterministic gates and accountable engineering decisions.
The manual is in active development. Early subscribers will receive selected chapters and launch information.
Yes. ParcelFlow is designed as a branch-by-branch companion repository, but its public URL is not available yet.
Your backend already works.
Now make it trustworthy.