Skip to content

Set Up the Domain

DDD CQRS ES

The Domain is the central composition root of a Protean application. It registers domain elements, loads configuration, and manages adapter lifecycle. Every Protean project starts by creating a Domain instance.

Creating a Domain

The simplest way to create a domain:

from protean import Domain

domain = Domain()

Protean auto-detects the root path from the caller's file location and searches that directory and its parent directories for configuration in .domain.toml, domain.toml, or pyproject.toml.

For named domains or explicit configuration:

domain = Domain(
    name="ecommerce",
    config={
        "databases": {
            "default": {
                "provider": "postgresql",
                "database_uri": "postgresql://localhost/ecommerce",
            }
        }
    },
)

For the full list of constructor parameters, see Domain Constructor Reference. For configuration options, see Configuration.

What's in This Section

Register Elements

Register domain elements with decorators or manual registration.

Initialize Domain

Call domain.init() to resolve references, validate the domain, and connect adapters.

Activate Domain

Push a domain context to make current_domain and the g object available.

When to Compose

When to call domain.init() and push the context in FastAPI, Flask, scripts, and the Protean server.

Configure for Production

Environment overlays, environment variable substitution, adapter selection, and dual-mode testing configuration.

Choosing Adapters

Decide which database, broker, event store, and cache to use for each workload. Compares the built-in options by use case and trade-offs.

Inspecting the IR

Generate and explore the domain's Intermediate Representation.

Schema Generation

Generate JSON Schema files for domain elements.