Skip to content

Domain dataclasses

The stored entities are Beanie documents (Model Conversion), so the domain layer holds everything else: value objects embedded in documents, results, filters, configs, and the changes a partial update makes. Value objects and results are stdlib dataclasses, and update changes are TypedDicts. They live under app/domain/ (plus app/dlq/models.py) and import nothing from Beanie or app/db/docs, since the documents import them. Pydantic stays at the edges: request and response schemas in app/schemas_pydantic/, documents in app/db/docs/, and the Kafka events in app/domain/events/typed.py, the one domain module that uses it.

No dataclass repeats the fields of a document. When a service needs an entity, it takes the document.

What dataclasses don't do

A dataclass doesn't validate types and doesn't convert nested dicts. ReplayConfig(filter={"user_id": "u1"}, max_events=10) builds fine and leaves a dict where a ReplayFilter should be. So nothing builds a dataclass from a dict by unpacking it.

The opposite holds inside Pydantic models, and the code relies on that. When a dataclass is a field type of a BaseModel or a document, Pydantic validates it and converts dicts: ExecutionDocument.resource_usage is a ResourceUsageDomain, ReplaySessionDocument.config a ReplayConfig with its ReplayFilter, and UserSettingsDocument keeps its notification and editor settings as dataclasses. Those documents register dataclasses.asdict in bson_encoders so the values can be written to MongoDB. Where a dataclass has to come from a dict outside a model, a TypeAdapter validates it, the way the settings route builds SystemSettings from the request.

Where they live

File Main types
app/domain/user/user_models.py UserChanges, UserDeleteResult, LoginResult
app/domain/user/settings_models.py DomainNotificationSettings, DomainEditorSettings, UserSettingsChanges, DomainUserSettingsChangedEvent
app/domain/execution/models.py ExecutionResultDomain, CancelResult, ResourceLimitsDomain
app/domain/replay/models.py ReplayFilter, ReplayConfig, ReplayError
app/domain/events/event_models.py EventFilter, EventListResult, EventStatistics
app/domain/events/typed.py EventMetadata, ResourceUsageDomain (next to the Pydantic events)
app/domain/notification/models.py NotificationChanges
app/domain/saved_script/models.py SavedScriptChanges
app/domain/rate_limit/rate_limit_models.py RateLimitConfig, RateLimitRule, UserRateLimit
app/domain/admin/settings_models.py SystemSettings
app/domain/admin/replay_models.py ReplaySessionData
app/domain/idempotency/models.py IdempotencyRecord
app/domain/sse/models.py SSEExecutionEventData
app/dlq/models.py DLQMessageChanges, RetryPolicy

Writing one

ReplayConfig in app/domain/replay/models.py, embedded in ReplaySessionDocument.config, shows the conventions for a value object:

@dataclass
class ReplayConfig:
    """What a replay session sends again: the stored events that match the filter, up to max_events."""

    filter: ReplayFilter
    max_events: int

Mutable defaults and generated values use field(default_factory=...). Timestamps are timezone-aware, from datetime.now(timezone.utc). Generated ids use default_factory=lambda: str(uuid4()), so code never checks them for None. Enums are StringEnum subclasses.

A partial update's changes are a TypedDict with total=False. A key that's there gets set, and a key that isn't keeps the stored value:

class SavedScriptChanges(TypedDict, total=False):
    """Fields an update sets; a missing key keeps the stored value and None clears the description."""

    name: str
    script: str
    lang: str
    lang_version: str
    description: str | None

A new value object embedded in a document needs the document's bson_encoders entry. Without it, writing the document fails with Beanie's "Cannot encode" ValueError.