Glossary
A comprehensive reference of terms used throughout Protean and the patterns it implements — Domain-Driven Design, CQRS, and Event Sourcing. Terms are grouped by category and listed alphabetically within each group. Use the sidebar to jump to any term.
Domain-Driven Design
Analysis Model
A conceptual artifact that bridges the gap between the real-world domain and the software implementation. The analysis model captures the core concepts, behaviors, and rules of the domain using DDD's tactical patterns (aggregates, entities, value objects, domain services) without prescribing technological details. It is developed collaboratively by domain experts and developers and serves as a blueprint for the system's design. The goal of DDD is to keep the analysis model and the code model aligned throughout the life of the project.
Learn more → | See also: Domain Model, Ubiquitous Language
Aggregate
A cluster of domain objects treated as a single unit for the purpose of data changes. Every aggregate has a root entity (the aggregate root) that controls access to its internals and enforces business rules, guaranteeing consistency within its boundary. In Protean, aggregates are defined with the @domain.aggregate decorator.
Learn more → | See also: Aggregate Root, Entity, Invariant, Transaction Boundary
Aggregate Root
The root entity of an aggregate — the single entry point through which all external interactions with the aggregate occur. The aggregate root is responsible for enforcing invariants and ensuring consistency of the entire cluster. In Protean, the class decorated with @domain.aggregate serves as the aggregate root.
Learn more → | See also: Aggregate, Entity
Bounded Context
A boundary within which a particular domain model is defined and applicable. Each bounded context has its own ubiquitous language and its own set of aggregates, entities, and value objects — the same real-world concept may be modeled differently in different bounded contexts.
Learn more → | See also: Domain, Ubiquitous Language
Domain
The sphere of knowledge and activity around which the business logic of an application revolves. In Protean, the Domain class also serves as the central registry that holds all domain elements and acts as the entry point for domain operations.
Learn more → | See also: Bounded Context, Domain Model
Domain Model
The representation of core business logic and rules expressed through aggregates, entities, value objects, domain services, and events. A well-crafted domain model captures the essential complexity of the business while remaining independent of infrastructure concerns.
Learn more → | See also: Aggregate, Entity, Value Object
Entity
An object defined primarily by its identity rather than its attributes. Two entities with the same attribute values are still distinct if they have different identities. Entities are mutable and can evolve over time. In Protean, entities are defined with the @domain.entity decorator and exist within an aggregate boundary.
Learn more → | See also: Aggregate, Identity, Value Object
Ubiquitous Language
A shared vocabulary developed collaboratively by domain experts and developers, used consistently in code, conversations, and documentation. The ubiquitous language ensures that the software model accurately reflects the business domain and reduces the risk of miscommunication.
Learn more → | See also: Bounded Context, Domain Model
Value Object
An immutable object that represents a descriptive aspect of the domain with no conceptual identity. Value objects are defined entirely by their attributes — two value objects with the same attributes are considered equal. In Protean, value objects are defined with the @domain.value_object decorator.
Learn more → | See also: Entity, Field
CQRS
Command Query Responsibility Segregation (CQRS)
A design pattern that separates the models used for reading data (queries) from the models used for writing data (commands). This separation allows each side to be optimized independently — the write model enforces business rules while the read model is denormalized for fast queries. Protean supports CQRS through distinct command/query paths and projections.
Learn more → | See also: Read Model, Write Model, Projection
Eventual Consistency
A consistency model where different parts of the system may temporarily hold different views of the data, but will converge to a consistent state over time. In Protean, eventual consistency arises when aggregates communicate through domain events processed asynchronously by event handlers or projectors.
Learn more → | See also: Domain Event, Projection, Transaction Boundary
Query
A request to retrieve data from the system without changing state. In CQRS, queries are handled by the read model, which is optimized for the specific data access patterns required by the application's consumers.
Learn more → | See also: Command Query Responsibility Segregation (CQRS), Read Model
Read Model
A data model optimized for querying and reading, separate from the write model. Read models are denormalized and shaped to match specific query needs, populated by processing domain events. In Protean, projections serve as read models.
Learn more → | See also: Projection, Write Model
Write Model
The model responsible for handling state changes and enforcing business rules. In CQRS, the write model processes commands and ensures all invariants are satisfied before persisting changes. In Protean, the aggregate and its surrounding domain model constitute the write model.
Learn more → | See also: Aggregate, Command, Read Model
Event Sourcing
Concurrency Control
A mechanism for preventing conflicts when multiple processes attempt to modify the same aggregate simultaneously. Protean uses optimistic concurrency control through aggregate versioning — each aggregate tracks a version number that is checked before persisting changes, rejecting updates based on stale versions. When a version mismatch is detected, the framework raises ExpectedVersionError. In async handlers, this error is automatically retried with exponential backoff before reaching the subscription retry pipeline.
Learn more → | Auto-retry config → | See also: Aggregate, Event Sourcing
Delta Event
A domain event that captures an incremental, specific change to an aggregate's state. Delta events describe what changed (e.g., OrderItemAdded, PriceUpdated) rather than the complete current state, making them useful for granular auditing and targeted reactions.
Learn more → | See also: Domain Event, Fact Event
Event-Carried State Transfer
A pattern where domain events carry the complete state of an aggregate, allowing consumers to build their own local copies of the data without querying the source. This pattern reduces coupling between services and improves autonomy. In Protean, fact events enable this pattern.
Learn more → | See also: Fact Event, Projection
Event Sourcing
A persistence pattern in which an aggregate's state is stored as a sequence of immutable domain events rather than as a current-state snapshot. The aggregate's state at any point in time can be reconstructed by replaying its events from the beginning. In Protean, aggregates opt in with is_event_sourced=True.
Learn more → | See also: Event Store, Event Stream, Replay, Snapshot
Event Store
A specialized persistence mechanism that stores domain events as an append-only, immutable log. The event store serves as the system of record for event-sourced aggregates, providing mechanisms to append events and retrieve them by stream. Protean supports event store adapters such as Message DB.
Learn more → | See also: Event Sourcing, Event Stream
Event Stream
A chronological sequence of events belonging to a specific aggregate instance. Each aggregate instance has its own event stream, identified by a combination of the stream category and the aggregate's identity. Event streams are the fundamental unit of storage in event sourcing.
Learn more → | See also: Event Store, Stream Category
Fact Event
A domain event that encloses the entire state of an aggregate at a specific point in time. Fact events are automatically generated by Protean when fact_events=True is set on an aggregate, and they enable the Event-Carried State Transfer pattern by providing consumers with a complete, self-contained snapshot of the aggregate.
Learn more → | See also: Delta Event, Event-Carried State Transfer
Hydration
The process of reconstructing an aggregate's current state from its persisted representation. In event-sourced systems, hydration means replaying all events in the aggregate's stream. In traditional CQRS, it means loading the aggregate's current-state record from the persistence store.
Learn more → | See also: Event Sourcing, Replay, Snapshot
Replay
The process of reprocessing a sequence of historical events to reconstruct an aggregate's state or to rebuild a projection from scratch. Replay is a core capability of event-sourced systems, enabling debugging, auditing, and the creation of new read models from existing event history.
Learn more → | See also: Event Sourcing, Hydration, Projection
Snapshot
A saved point-in-time representation of an aggregate's state, used to optimize hydration performance in event-sourced systems. Instead of replaying the entire event history, the system loads the most recent snapshot and only replays events that occurred after it. Protean's snapshot threshold is configurable (default: 10 events).
Learn more → | See also: Event Sourcing, Hydration
@apply Decorator
A decorator used on methods within event-sourced aggregates to mutate aggregate state in response to a specific event type. When an event is raised or replayed, Protean calls the matching @apply method to update the aggregate's attributes. This separates event raising (business intent) from state mutation (mechanical update).
Learn more → | See also: Event Sourcing, Aggregate, Domain Event
is_event_sourced Option
An aggregate decorator option (@domain.aggregate(is_event_sourced=True)) that switches the aggregate's persistence model from current-state storage to event sourcing. When enabled, the aggregate's state is derived entirely from replaying its event stream rather than loading a snapshot from a database table.
Learn more → | See also: Event Sourcing, @apply Decorator
Domain Elements
Command
An immutable message expressing the intent to perform a specific action or change the system's state. Commands are named using imperative verbs (e.g., PlaceOrder, CancelReservation) and carry the data needed to perform the requested action. In Protean, commands are defined with the @domain.command decorator.
Learn more → | See also: Command Handler, Domain Event
Command Handler
A component responsible for processing a command by executing the corresponding business logic on an aggregate. Each command handler is connected to a single aggregate and orchestrates the state change in response to a command. In Protean, command handlers are defined with the @domain.command_handler decorator.
Learn more → | See also: Command, Aggregate
Domain Event
An immutable record of something significant that happened in the domain. Events are named in past tense (e.g., OrderPlaced, PaymentProcessed) and capture the relevant data about the state change. Domain events are the primary mechanism for communication between aggregates and bounded contexts. In Protean, events are defined with the @domain.event decorator.
Learn more → | See also: Event Handler, Fact Event, Delta Event
Domain Service
A stateless component that encapsulates domain logic which does not naturally belong to any single aggregate, entity, or value object. Domain services typically coordinate operations that span multiple aggregates or implement complex business rules. In Protean, domain services are defined with the @domain.domain_service decorator.
Learn more → | See also: Aggregate, Application Service
Event Handler
A component that reacts to domain events by executing follow-up business logic. Event handlers enable decoupled, reactive behavior — they listen for specific events and perform actions such as updating other aggregates, sending notifications, or triggering external processes. In Protean, event handlers are defined with the @domain.event_handler decorator.
Learn more → | See also: Domain Event, Subscriber
Invariant
A business rule or constraint that must always hold true within a domain concept. Invariants are checked before and after every state change to ensure the aggregate remains in a valid state. In Protean, invariants are defined as methods decorated with @invariant within an aggregate or entity class.
Learn more → | See also: Aggregate, Validation
Process Manager
A stateful, event-driven coordinator that manages multi-step business processes spanning multiple aggregates. Process managers correlate events from different streams to the same running instance, maintain their own event-sourced state, and issue commands to drive other aggregates forward. They have a defined lifecycle — starting with an initiating event and completing when the process reaches a terminal state. In Protean, process managers are defined with the @domain.process_manager decorator.
Learn more → | See also: Event Handler, Command, Domain Event
Projection
A read-optimized, denormalized view of data constructed by processing one or more event streams. Projections are the primary mechanism for building read models in CQRS, tailored to specific query needs. In Protean, projections are defined with the @domain.projection decorator.
Learn more → | See also: Projector, Read Model
Subscriber
A component that consumes messages from external message brokers or other systems outside the domain boundary. Subscribers bridge the gap between external messaging infrastructure and the domain's internal event handling. In Protean, subscribers are defined with the @domain.subscriber decorator.
Learn more → | See also: Broker, Event Handler
Fields & Data
Association Field
A field type that defines a relationship between domain elements. Protean provides three association field types: HasOne for one-to-one relationships, HasMany for one-to-many relationships, and Reference for establishing the inverse relationship from a child entity back to its parent aggregate.
Learn more → | See also: Field, Shadow Field
Container Field
A field type that holds multiple or composite values. Protean provides List for ordered collections, Dict for key-value mappings, and ValueObject for embedding a value object directly within an entity or aggregate.
Learn more → | See also: Field, Value Object
Field
The fundamental building block for defining the structure and data types of domain elements. Fields are implemented as Python descriptors and handle type validation, constraints, and defaults. Protean provides simple fields (String, Integer, Float, Boolean, Date, DateTime, etc.), container fields, and association fields.
Learn more → | See also: Simple Field, Container Field, Association Field
Identity
A unique identifier that distinguishes one entity or aggregate instance from all others. In Protean, identity can be configured through identity strategies (uuid, function), identity types (string, integer, uuid), and custom identifier fields.
Learn more → | See also: Entity, Aggregate
Shadow Field
A hidden field automatically created alongside a Reference association field. The shadow field stores the actual identifier value (the foreign key) linking a child entity to its parent aggregate. Shadow fields are named with a _id suffix by convention.
Learn more → | See also: Association Field, Identity
Simple Field
A basic field type for scalar data values. Protean's simple fields include String, Text, Integer, Float, Boolean, Date, DateTime, Auto (auto-generated identities), and Identifier (explicit identity fields).
Learn more → | See also: Field, Identity
Validation
The process of ensuring data conforms to defined constraints and business rules. Protean supports field-level validation (type checks, required fields, max length, allowed values) and domain-level validation through invariants. Custom validators can be attached to individual fields for domain-specific constraints.
Learn more → | See also: Field, Invariant
Application Layer
Application Service
A service that orchestrates a specific business use case by coordinating between the domain model and infrastructure. Application services receive commands, load aggregates from repositories, invoke domain logic, and persist the results. In Protean, application services are defined with the @domain.application_service decorator.
Learn more → | See also: Command Handler, Domain Service, Repository
@use_case Decorator
A decorator applied to methods within an application service to mark them as use case entry points. It automatically wraps the method body in a UnitOfWork context, providing transaction management — if the method succeeds, all changes are committed; if it raises, all changes are rolled back.
Learn more → | See also: Application Service, Unit of Work
Composition
The process of assembling a domain by registering its elements — aggregates, entities, value objects, commands, events, handlers, and services — into the Domain registry. In Protean, elements are auto-discovered from specified modules or manually registered, then wired together during domain initialization.
Learn more → | See also: Domain
Custom Repository
A repository with user-defined methods that go beyond standard CRUD operations, tailored to specific aggregate access patterns. Custom repositories allow encapsulating complex queries and domain-specific data access logic while maintaining the abstraction boundary. In Protean, custom repositories are defined with the @domain.repository decorator.
Learn more → | See also: Repository, Data Access Object (DAO)
Database Model
A persistence-technology-specific data schema that maps domain elements to their storage representation. Database models handle the translation between domain objects and the underlying storage format (relational tables, document structures, etc.). In Protean, database models are defined with the @domain.model decorator.
Learn more → | See also: Repository, Provider
Projector
A specialized handler responsible for keeping projections up to date by listening to domain events and applying the corresponding changes to projection data. Projectors work exclusively with projections, translating domain events into read model updates. In Protean, projectors are defined with the @domain.projector decorator.
Learn more → | See also: Projection, Event Handler
Repository
An abstraction that encapsulates the storage, retrieval, and search behavior for aggregates. Repositories provide a collection-like interface that isolates domain logic from the details of data storage, allowing the persistence mechanism to be swapped without affecting the domain model.
Learn more → | See also: Aggregate, Custom Repository, Unit of Work
Unit of Work
A pattern that groups all changes made to aggregates within a single business operation into an atomic transaction. The unit of work tracks changes, coordinates persistence, and ensures that either all changes are committed or none are. In Protean, the unit of work is managed automatically via a context manager.
Learn more → | See also: Repository, Transaction Boundary
Reactive Layer
Event-Driven Architecture
An architectural style in which the flow of the program is determined by events — significant state changes that are published and consumed asynchronously. Components communicate by producing and reacting to events rather than through direct calls, promoting loose coupling and scalability. Protean's reactive layer is built on this principle.
Learn more → | See also: Domain Event, Event Handler, Eventual Consistency
Stream Category
A logical name that groups related message streams together. Stream categories serve as the routing mechanism for subscriptions, determining which handlers receive which messages. In Protean, stream categories are derived from the aggregate class name by default and can be customized via the stream_category meta option.
Learn more → | See also: Event Stream, Subscription
Infrastructure
Adapter
A concrete implementation of a port that connects the domain to a specific technology. Adapters translate between the domain's abstract interfaces and the details of external systems (databases, message brokers, caches). Protean ships with adapters for PostgreSQL, Elasticsearch, Redis, Message DB, and more.
Learn more → | See also: Port, Ports and Adapters Architecture
Broker
A message broker infrastructure component responsible for publishing and delivering messages (events and commands) between producers and consumers. Protean supports multiple broker implementations including an inline (in-process) broker for development and Redis-based brokers for production.
Learn more → | See also: Adapter, Subscriber
Cache
A caching infrastructure component for storing frequently accessed data to reduce load on primary data stores and improve response times. In Protean, caches are configured as adapters and can be backed by implementations such as Redis.
Learn more → | See also: Adapter, Provider
Data Access Object (DAO)
A pattern that provides a low-level abstract interface for database operations. In Protean, the DAO layer sits beneath repositories and handles the direct interaction with persistence technologies, allowing repositories to remain technology-agnostic.
Learn more → | See also: Repository, Provider
Event Store Adapter
An adapter implementation for persisting and retrieving domain events. Event store adapters provide the concrete storage mechanism for event sourcing, supporting operations like appending events, reading streams, and managing snapshots. Protean includes a Message DB adapter for production use.
Learn more → | See also: Event Store, Adapter
Outbox Pattern
A reliability pattern that ensures messages are published to the broker exactly when the associated business transaction commits. Events are first written to an outbox table in the same database transaction as the aggregate changes, then asynchronously picked up and published to the broker by a background processor.
Learn more → | See also: Broker, Transaction Boundary, Unit of Work
Port
An abstract interface that defines the contract between the domain and external infrastructure. Ports specify what capabilities are needed (persistence, messaging, caching) without prescribing how they are implemented. In Protean, ports include BaseProvider, BaseBroker, BaseEventStore, and BaseCache.
Learn more → | See also: Adapter, Ports and Adapters Architecture
Ports and Adapters Architecture
An architectural pattern (also known as Hexagonal Architecture) that isolates the domain model from technology concerns. The domain defines ports (abstract interfaces) for its infrastructure needs, and adapters provide concrete implementations. This separation allows swapping technologies without changing domain logic.
Learn more → | See also: Adapter, Port
Provider
A database adapter that provides persistence functionality for a specific storage technology. Providers handle connection management, query execution, and data mapping. In Protean, providers can be assigned per aggregate using the provider meta option, allowing different aggregates to use different databases.
Learn more → | See also: Adapter, Database Model
Structured Logging
Protean's built-in logging system based on structlog. configure_logging() sets up environment-aware structured logging with JSON output in production and colored console output in development. Supports context variables that propagate across async boundaries, method call tracing, rotating file handlers, and automatic suppression of noisy third-party loggers.
Learn more → | See also: Engine, Observatory
Integrations
DomainContextMiddleware
An ASGI middleware for FastAPI applications that automatically pushes the correct Protean domain context per HTTP request. Maps URL path prefixes to Domain instances using longest-prefix-first matching. Requests that don't match any prefix pass through without a domain context. Supports both static route-to-domain maps and custom resolver callables.
Learn more → | See also: Domain, Bounded Context
Exception Handlers (FastAPI)
A set of pre-built exception handlers (register_exception_handlers) that map Protean domain exceptions to standard HTTP responses. ValidationError and InvalidDataError become 400, ObjectNotFoundError becomes 404, InvalidStateError becomes 409, and InvalidOperationError becomes 422.
Learn more → | See also: DomainContextMiddleware
Server & Messaging
Consumer Group
A mechanism that allows multiple instances of an application to process messages from the same stream in parallel, with each message delivered to exactly one consumer in the group. Consumer groups provide automatic load balancing and fault tolerance. In Protean, consumer groups are used by StreamSubscription via Redis Streams.
Learn more → | See also: Subscription, Engine
Dead Letter Queue
A dedicated stream where messages that have failed processing after exhausting all retry attempts are moved. Dead letter queues preserve failed messages along with error metadata, enabling debugging, analysis, and manual reprocessing.
Learn more → | See also: Subscription, Idempotency
CommandDispatcher
An internal routing mechanism that consolidates multiple command handler subscriptions on the same stream category into a single subscription. Instead of creating N separate subscriptions that compete for the same messages, the engine creates one CommandDispatcher per stream category that reads each command once and routes it to the correct handler based on the command type.
Learn more → | See also: Command Handler, Engine, Subscription
Engine
The core async message processing system in Protean that manages the lifecycle of subscriptions, coordinates message handling, and provides graceful startup and shutdown. The engine polls for messages from event stores and brokers, delivers them to the appropriate handlers, and tracks processing state.
Learn more → | See also: Subscription, Broker
Idempotency
The property ensuring that processing the same message multiple times produces the same result as processing it once. Idempotent handlers are essential in distributed systems where messages may be delivered more than once due to retries, network issues, or at-least-once delivery guarantees.
Learn more → | See also: Command Handler, Event Handler
Message
A piece of data transmitted between components in an event-driven system. In Protean, messages are the supertype encompassing both commands (requests to do something) and domain events (records of something that happened). Messages flow through streams and are processed by handlers.
Learn more → | See also: Command, Domain Event, Stream Category
MessageTrace
A structured dataclass representing one stage of a message's journey through the processing pipeline. Each trace captures the event type, domain, stream, message identity, status, handler name, processing duration, and optional error and metadata. MessageTrace events are serialized to JSON and published to Redis Pub/Sub by the TraceEmitter.
Learn more → | See also: TraceEmitter, Observatory
Observatory
A standalone FastAPI server (Observatory) that provides real-time monitoring of the Protean message processing pipeline. It subscribes to the trace event channel and exposes an HTML dashboard, Server-Sent Events stream, REST API for infrastructure health and statistics, and a Prometheus metrics endpoint. Runs on its own port (default 9000), separate from the application.
Learn more → | See also: TraceEmitter, MessageTrace, Engine
Position Tracking
The mechanism by which subscriptions track which messages have been successfully processed. Position tracking ensures that after a restart, a subscription resumes from where it left off rather than reprocessing the entire stream. Different subscription types implement position tracking differently (cursor-based, consumer group ACKs, etc.).
Learn more → | See also: Subscription, Consumer Group
Subscription
A long-running process that connects message sources (event stores or brokers) to handlers. Subscriptions manage the message flow lifecycle: polling for new messages, delivering them to handlers, tracking processed positions, and handling errors with retries. Protean provides StreamSubscription, EventStoreSubscription, and BrokerSubscription types.
Learn more → | See also: Engine, Stream Category, Position Tracking
TraceEmitter
A lightweight component attached to the Engine that publishes structured MessageTrace events to Redis Pub/Sub as messages flow through the processing pipeline. Designed for zero overhead when nobody is listening — it checks subscriber count via PUBSUB NUMSUB and short-circuits before any serialization when no subscribers are found. Tracing failures are silently swallowed and never affect message processing.
Learn more → | See also: MessageTrace, Observatory, Engine
Transaction Boundary
The scope within which all state changes must be atomic — either all succeed or all are rolled back. In domain-driven design, each aggregate defines a transaction boundary. No single transaction should span multiple aggregates; cross-aggregate consistency is achieved through eventual consistency via domain events.
Learn more → | See also: Aggregate, Unit of Work, Eventual Consistency
Testing
DomainFixture
A test lifecycle manager provided by protean.integrations.pytest that handles domain initialization, database schema setup/teardown, and per-test data cleanup across all adapters. DomainFixture is the recommended way to set up Protean's test infrastructure in pytest, providing setup(), teardown(), and domain_context() methods.
Learn more → | See also: Domain Model Testing, Test Mode
Domain Model Testing
The practice of testing domain logic in isolation from infrastructure, using plain Python objects without mocks. Because Protean's domain model is technology-agnostic, aggregates, entities, value objects, and domain services can be tested directly by constructing them, invoking their methods, and asserting on their state.
Learn more → | See also: Domain Model, Test Mode
Test Mode
A configuration setting for the Protean engine that enables deterministic, synchronous message processing suitable for automated tests. In test mode, exceptions are propagated rather than handled by retry logic, making test failures immediately visible and debuggable.
Learn more → | See also: Engine, Domain Model Testing