python-service-and-schema-cohesion

Service layer and schema cohesion

The service layer is where use cases live: "place an order", "cancel a subscription", "refund a payment". An application service orchestrates aggregates (via repos) and external systems (via clients), owns the top-level transaction boundary, and returns a Pydantic schema — the use case result, ready for serialization.

Pure domain services and policies are extraction tools inside that shape. Use them when a business decision is too large for the application service but does not belong cleanly on one aggregate or value object.

Schemas live next to services because every transformation between domain and wire shape is a method on the schema class. Cohesion is the rule: if there's a translation X → Y, it's a method on one of those classes, never a free function.

When to use this skill

• Adding a new use case (route → service method)
• Modifying an existing service to call new repos/clients
• Defining a new Pydantic schema for API I/O or external system payloads
• Adding a translation between a model and a schema, or between two schemas

The rules

1. Class per file when there's state + multiple methods; functions otherwise

# app/services/checkout.py — class form (shape; full version in examples/checkout_service.py)
class CheckoutService:
    def __init__(self, *, orders: OrderRepo, stripe: StripeClient, session: AsyncSession) -> None:
        self._orders, self._stripe, self._session = orders, stripe, session

    async def place_order(self, cmd: PlaceOrderCommand) -> OrderGet: ...
    async def cancel_order(self, cmd: CancelOrderCommand) -> OrderGet: ...
    async def refund_order(self, cmd: RefundOrderCommand) -> OrderGet: ...

# app/services/refunds.py — function form (single use case, no shared state)
async def issue_refund(
    cmd: RefundOrderCommand,
    *,
    orders: OrderRepo,
    stripe: StripeClient,
    session: AsyncSession,
) -> OrderGet: ...

Rule: class when the file has 2+ methods sharing deps. Function (or several functions) when each use case stands alone with no shared state.