Modules, Types, and Domain Models

Modules give code names and boundaries; type hints make assumptions visible; domain models protect valid business state. A maintainable backend keeps the core meaning of a ticket independent from HTTP, database rows, and model-provider payloads so each outer technology can change without rewriting the business rules.

What will you be able to do?

structure a Python package by responsibility;
model valid states with enums and dataclasses;
use static type checks as fast design feedback;
separate domain objects from transport and persistence schemas.

What belongs in the domain?

Create src/supportdesk_ai/domain/tickets.py:

python

from dataclasses import dataclass, replace
from enum import StrEnum
from uuid import UUID


class TicketStatus(StrEnum):
    OPEN = "open"
    IN_PROGRESS = "in_progress"
    RESOLVED = "resolved"


@dataclass(frozen=True, slots=True)
class Ticket:
    id: UUID
    organization_id: UUID
    subject: str
    status: TicketStatus = TicketStatus.OPEN

    def resolve(self) -> "Ticket":
        if self.status is TicketStatus.RESOLVED:
            raise ValueError("ticket is already resolved")
        return replace(self, status=TicketStatus.RESOLVED)

frozen=True makes mutation explicit: resolve returns a new valid value. The organization identifier is part of the model because tenant ownership is a business fact, not an HTTP detail.

Suggested boundaries:

text

src/supportdesk_ai/
├── domain/          # business meaning, no FastAPI or SQLAlchemy
├── application/     # use cases and ports
├── adapters/        # database, model, cache, queue implementations
├── api/             # HTTP schemas, dependencies, routes
└── main.py          # composition root

Verify types:

bash

uv run mypy src
uv run python -c 'from supportdesk_ai.domain.tickets import Ticket
Status; print(Ticket
Status.OPEN)'

Why not use one model everywhere?

An HTTP creation request has no database-generated ID. A database row has persistence details. A model provider may use a strict classification schema. A domain ticket represents business truth. Reusing one giant model leaks fields, creates accidental write access, and tightly couples layers.

Why does this matter in AI-native systems?

Provider schemas change more often than domain language. Keep ModelTicketClassification at the adapter boundary, translate it into an application command, then apply domain rules. The model never returns a fully trusted Ticket or chooses tenant ownership.

Common mistakes

Circular imports indicate unclear ownership; dependencies should point inward.
Type hints without a type checker are documentation only; run mypy or an equivalent tool in CI.
Enums copied from a provider leak vendor behavior; define application-owned terms.
A “utils” module becomes a boundaryless drawer; name modules after responsibilities.

AI Pair-Programmer Prompt

text

Review this package tree and import graph. Identify domain rules, application use
cases, inbound schemas, and outbound adapters. Flag framework/provider types that
leak inward, circular dependencies, and models reused across trust boundaries.
Propose a minimal move plan with type-check commands.

Exercise

Add an assign(agent_id) method that rejects resolved tickets and returns a new ticket. Decide whether assignment belongs in the same aggregate and defend your answer.

Acceptance criteria: static checks pass; tests prove the resolved-state rule and immutability; no FastAPI import appears in domain/.

Knowledge check

Why is organization_id a domain field?
What problem does StrEnum solve here?
Why keep provider types out of the domain?

Answers

Tenant ownership affects every valid operation and data boundary.
It restricts states while serializing naturally as meaningful strings.
Provider churn and untrusted payload semantics should not redefine business truth.

Completion checklist

Domain imports no web or database framework.
Type checks pass.
State transitions preserve invariants.

Primary references

Modules, Types, and Domain Models

What belongs in the domain?

Create src/supportdesk_ai/domain/tickets.py:

python

from dataclasses import dataclass, replace
from enum import StrEnum
from uuid import UUID


class TicketStatus(StrEnum):
    OPEN = "open"
    IN_PROGRESS = "in_progress"
    RESOLVED = "resolved"


@dataclass(frozen=True, slots=True)
class Ticket:
    id: UUID
    organization_id: UUID
    subject: str
    status: TicketStatus = TicketStatus.OPEN

    def resolve(self) -> "Ticket":
        if self.status is TicketStatus.RESOLVED:
            raise ValueError("ticket is already resolved")
        return replace(self, status=TicketStatus.RESOLVED)

frozen=True makes mutation explicit: resolve returns a new valid value. The organization identifier is part of the model because tenant ownership is a business fact, not an HTTP detail.

Suggested boundaries:

text

src/supportdesk_ai/
├── domain/          # business meaning, no FastAPI or SQLAlchemy
├── application/     # use cases and ports
├── adapters/        # database, model, cache, queue implementations
├── api/             # HTTP schemas, dependencies, routes
└── main.py          # composition root

Verify types:

bash

uv run mypy src
uv run python -c 'from supportdesk_ai.domain.tickets import Ticket
Status; print(Ticket
Status.OPEN)'

Common mistakes

Circular imports indicate unclear ownership; dependencies should point inward.

Type hints without a type checker are documentation only; run mypy or an equivalent tool in CI.

Enums copied from a provider leak vendor behavior; define application-owned terms.

A “utils” module becomes a boundaryless drawer; name modules after responsibilities.

AI Pair-Programmer Prompt

text

Review this package tree and import graph. Identify domain rules, application use
cases, inbound schemas, and outbound adapters. Flag framework/provider types that
leak inward, circular dependencies, and models reused across trust boundaries.
Propose a minimal move plan with type-check commands.

Knowledge check

Why is organization_id a domain field?

What problem does StrEnum solve here?

Why keep provider types out of the domain?

Answers

Tenant ownership affects every valid operation and data boundary.

It restricts states while serializing naturally as meaningful strings.

Provider churn and untrusted payload semantics should not redefine business truth.