Playbooks

This section translates the earlier theory into practical service-design rules. Knowing Pythonic patterns, typing, runtime behavior, asyncio, FastAPI, Pydantic, and SQLAlchemy independently is useful, but what matters in production is how those pieces fit together without collapsing into one giant layer.

Quick takeaway: a playbook is not a summary page. It is a decision aid. You should be able to use these chapters when starting a service, reviewing code, or refactoring a codebase that has begun to tangle its boundaries.

The Questions This Part Answers

How should a new service start?

It proposes a reference layout for routers, services, repositories, schemas, settings, logging, and tests.

How should configuration be designed?

It explains how to split `settings.py`, `pydantic-settings`, `.env`, secret sources, and test overrides into a clean configuration boundary.

How do FastAPI, Pydantic, and SQLAlchemy stay decoupled?

It separates request DTOs, transactions, ORM entities, and response DTOs so the API can evolve cleanly.

What should type reviews focus on?

It prioritizes `Any` containment, abstraction discipline, protocol usage, and boundary clarity over annotation volume.

How should fixture design work?

It covers yield fixtures, dependency override cleanup, database isolation, and client lifecycles as real service-testing patterns.

What comes after fixtures?

It explains how to add HTTP contract tests, websocket protocol tests, property-based tests, and idempotency invariants on top.

How do you choose Lambda vs Kubernetes?

It compares traffic shape, database connection strategy, long-lived connections, and operational surface area instead of treating hosting as an afterthought.

How do schema changes stay safe during progressive delivery?

It explains ordering for Alembic, backfill, and feature flags across rolling, blue-green, canary, and Lambda alias rollouts.

How do schema, API, and event contracts evolve together?

It brings DB migrations, API versioning, event versioning, and backfill or replay into one contract-evolution frame.

How do retries and duplicate delivery stay safe?

It connects idempotency keys, outbox design, publisher retry, and dedupe into one operational picture.

Where does theory meet service design?

It connects typing, runtime, and framework knowledge to concrete API architecture decisions.

Recommended Reading Order

1. API Service Template
2. Settings and Pydantic Settings
3. Testing with Fixtures
4. Testing Beyond Fixtures
5. ABC + Fake UoW Testing
6. Use Case + UoW + ABC
7. FastAPI + Pydantic + SQLAlchemy
8. Lambda vs Kubernetes
9. Progressive Delivery + Alembic
10. Contract Evolution and Sustainable CD
11. Idempotency and Outbox
12. Typing Review Checklist

How to Use This Part

• Start with API Service Template when creating a new service skeleton.
• Start with Settings and Pydantic Settings if you need a clean config boundary for env vars, secrets, and test overrides.
• Start with Testing with Fixtures if you need a clean fixture and teardown baseline for service tests.
• Start with Testing Beyond Fixtures if you want to add contract, property-based, and protocol testing on top of that baseline.
• Start with ABC + Fake UoW Testing if you want fast unit tests around use-case branching without touching a real database.
• Start with Use Case + UoW + ABC if you want a concrete SOLID-aware use-case boundary with SQLAlchemy and explicit abstract base classes.
• Start with FastAPI + Pydantic + SQLAlchemy if you already have a service and want cleaner boundaries.
• Start with Lambda vs Kubernetes if the hosting decision is still open and you need a workload-driven rubric.
• Start with Progressive Delivery + Alembic if you need a safe order for schema changes, backfill jobs, and rollout promotion under rolling, blue-green, canary, or Lambda alias deployment.
• Start with Contract Evolution and Sustainable CD if you need one mental model for DB schema, public API, async events, and historical data migration.
• Start with Idempotency and Outbox if retry-safe create endpoints and reliable publication are becoming production concerns.
• Use Typing Review Checklist as a team review baseline.

Good Companion Chapters

• FastAPI
• Pydantic
• SQLAlchemy 2.0
• Typing