Contents

A complete listing of every page in the Protean documentation. Use your browser's search (Ctrl+F / Cmd+F) to find any topic.

---

Getting Started

• Installation -- Set up Python and install Protean.
• Quickstart -- Build a domain in 5 minutes with in-memory adapters.

Tutorial: Building Bookshelf

A guided, end-to-end walkthrough of building a complete online bookstore.

Part I -- Getting Started

• 1. Your First Aggregate -- Create the foundation with a working Book aggregate.
• 2. Fields and Identity -- Explore field types, options, and how identity works.

Part II -- The Domain Model

• 3. Value Objects -- Model rich, descriptive concepts instead of primitives.
• 4. Entities and Associations -- Build the Order aggregate with entities and relationships.
• 5. Business Rules -- Add invariants and encapsulate behavior in aggregate methods.

Part III -- Commands and Events

• 6. Commands -- Formalize state changes with commands and command handlers.
• 7. Domain Events -- Define domain events and raise them from aggregates.
• 8. Event Handlers -- Process events and trigger side effects.

Part IV -- Services and Read Models

• 9. Application Services -- Create a synchronous coordination layer.
• 10. Domain Services -- Encapsulate business logic spanning multiple aggregates.
• 11. Projections -- Build read-optimized views from events.

Part V -- Infrastructure

• 12. Persistence -- Connect to real databases using configuration.
• 13. Async Processing -- Switch to asynchronous processing for scalability.
• 14. Event Sourcing -- Store events instead of current state.

Part VI -- Quality

• 15. Testing -- Testing strategies for every layer of the application.

---

Guides

Comprehensive reference organized by topic. Each guide goes deep on a specific area.

• Guide Overview -- How the guides are organized and where to start.
• How Do I...? -- Task-oriented index: find the right guide by what you're trying to do.

Choose a Path

• Architectural Pathways -- Three approaches that build on each other.
• DDD Pathway -- Aggregates, application services, and repositories.
• CQRS Pathway -- Separate reads from writes with commands and projections.
• Event Sourcing Pathway -- Derive state from event replay.

Compose a Domain

• The Domain Object -- The composition root that manages elements, configuration, and adapters.
• Register Elements -- How elements register themselves with the domain.
• Initialize the Domain -- Call init() to wire everything together.
• Activate the Domain -- Bind the domain to a context for use.
• When to Compose -- Lifecycle and timing of domain composition.
• Element Decorators -- Decorators that construct and register domain elements.

Define Concepts

• Defining Concepts -- Foundational domain concepts using DDD tactical patterns.
• Aggregates -- Model domain concepts with unique identity.
• Entities -- Objects with identity that compose aggregates.
• Value Objects -- Immutable descriptive objects identified by their attributes.
• Expressing Relationships -- Model associations between domain elements.
• Events -- Model past changes as discrete, meaningful facts.
• Deciding Between Elements -- Checklists and decision flows for choosing element types.

Fields

• Fields Overview -- Field types, attributes, options, and functionalities.
• Simple Fields -- String, Text, Integer, Float, Boolean, and other primitives.
• Container Fields -- Fields that hold and embed value objects.
• Association Fields -- HasOne, HasMany, and Reference fields for relationships.
• Common Arguments -- Shared field arguments like required, default, and description.

Add Behavior

• Domain Behavior -- Enforcing business rules through validations, invariants, and methods.
• Validations -- Field-level validation using types, options, and custom validators.
• Invariants -- Business rules that must always hold true within an aggregate.
• Mutating Aggregates -- Modify state through named methods reflecting actions and events.
• Raising Events -- Notify other parts of the system through domain events.
• Domain Services -- Complex domain logic that spans multiple aggregates.

Application Layer

• Changing State -- Mechanisms for state changes: services, commands, and handlers.
• Application Services -- Bridge between the API layer and the domain model.
• Commands -- Data transfer objects expressing intention to change state.
• Command Handlers -- Process commands and execute domain logic.
• Persist Aggregates -- Save aggregates using a repository's add method.
• Retrieve Aggregates -- Load aggregates using a repository's get method.

Reactive Layer

• Consuming State Changes -- React to state changes through handlers, projections, and subscribers.
• Event Handlers -- Consume events to sync state or trigger side effects.
• Projections -- Create read-optimized views built from events.
• Subscribers -- Consume messages from external brokers.

Essentials

• Object Model -- Common structure and traits shared by all domain elements.
• Identity -- Identity generation strategies, types, and configuration.
• Stream Categories -- How messages are organized and routed.
• Configuration -- Configure Protean through domain.toml and environment variables.
• Unit of Work -- Automatic transaction management for aggregate changes.

Server

• Server Overview -- Asynchronous message processing engine for events, commands, and external messages.
• Engine Architecture -- Core async processing, managing subscriptions and lifecycle.
• Subscriptions -- Connect handlers to message sources.
• Subscription Types -- Stream and EventStore subscriptions for different use cases.
• Subscription Configuration -- Flexible configuration with priority hierarchy.
• Outbox Pattern -- Reliable message delivery via same-transaction storage.
• Running the Server -- Start, configure, and operate the Protean server.

CLI

• CLI Overview -- The protean command-line interface for scaffolding and management.
• Domain Discovery -- Use --domain to load and initialize domains.
• protean new -- Initialize new projects.
• protean shell -- Interactive shell with the domain pre-loaded.
• protean docs -- Live preview server for documentation.
• protean test -- Run tests with category and technology options.

Testing

• Testing Strategy -- Layered testing approach with fast in-memory adapters.
• Domain Model Tests -- Unit tests for aggregates, entities, value objects, and invariants.
• Application Tests -- Validate commands, handlers, and services.
• Integration Tests -- Verify behavior with real infrastructure.
• Fixtures and Patterns -- Reusable pytest fixtures and conftest recipes.

---

Core Concepts

Architectural theory and the building blocks of domain-driven systems.

Architecture Patterns

• Domain-Driven Design -- Tactical elements and their roles in the DDD pattern.
• CQRS -- Separating read and write responsibilities.
• Event Sourcing -- Deriving state from replaying event sequences.
• Choosing an Architecture -- When to use CQRS vs Event Sourcing.

Building Blocks

• Domain Elements Overview -- Tactical patterns organized into four layers.
• Aggregates -- Clusters of objects treated as a single unit for data changes.
• Entities -- Mutable objects with distinct identity.
• Value Objects -- Immutable elements distinguished by properties.
• Domain Services -- Domain logic that doesn't fit within aggregates.
• Events -- Immutable facts indicating state changes.
• Commands -- Intentions to change system state.
• Command Handlers -- Process commands and execute domain logic.
• Event Handlers -- React to events with side effects and state synchronization.
• Application Services -- Coordinate use cases at the boundary between external world and domain.
• Repositories -- Collection-oriented persistence abstraction for aggregates.
• Subscribers -- Consume messages from external brokers.
• Projections -- Read-optimized denormalized views.
• Projectors -- Specialized event handlers that maintain projections.

---

Adapters

Plug-in infrastructure that keeps your domain code free of technology dependencies.

• Adapters Overview -- Ports and Adapters (Hexagonal Architecture) in Protean.
• Adapter Internals -- How database adapter components work together.

Database

• Database Providers -- Overview of supported database adapters.
• PostgreSQL -- SQLAlchemy-based adapter for PostgreSQL.
• Elasticsearch -- Adapter for search and analytics.

Brokers

• Broker Overview -- Unified interface for message broker implementations.
• Inline Broker -- Synchronous in-memory broker for development and testing.
• Redis Streams -- Durable ordered messaging with consumer groups.
• Redis PubSub -- Redis Lists-based queuing with consumer groups.
• Custom Brokers -- Build your own broker adapter.

Caches

• Cache Overview -- Cache providers in Protean.
• Redis Cache -- Redis as a cache adapter.

Event Stores

• Event Store Overview -- Event store options in Protean.
• MessageDB -- MessageDB event store adapter.

---

Patterns & Recipes

In-depth guides for recurring patterns in domain-driven applications. These span multiple domain elements and represent good practices that Protean supports but does not enforce.

Aggregate Design

• Design Small Aggregates -- Draw boundaries around consistency requirements, not data relationships.
• One Aggregate Per Transaction -- Modify one aggregate per handler; use events for cross-aggregate side effects.
• Encapsulate State Changes -- Express every state change as a named method capturing business intent.
• Replace Primitives with Value Objects -- Extract strings and numbers into value objects with format rules and operations.

Event-Driven Patterns

• Design Events for Consumers -- Events carry enough context for consumers to act independently.
• Idempotent Event Handlers -- Produce the same result whether an event is processed once or many times.
• Event Versioning and Evolution -- Evolve event schemas without breaking consumers or the event store.
• Command Idempotency -- Ensure processing the same command twice produces the same effect.

Architecture & Quality

• Validation Layering -- Different validation belongs at different layers: fields, value objects, invariants, handlers.
• Thin Handlers, Rich Domain -- Handlers orchestrate; aggregates and domain services contain all logic.
• Testing Domain Logic in Isolation -- Test aggregates and value objects directly, without infrastructure.

Identity & Communication

• Creating Identities Early -- Generate aggregate identities at creation, not at the database.
• Connecting Concepts Across Bounded Contexts -- Synchronize the same real-world concept across multiple contexts.
• Consuming Events from Other Domains -- Subscribers as anti-corruption layers for external events.
• Sharing Event Classes Across Domains -- Share schemas, not code; use contract tests for compatibility.

---

Reference

• Glossary -- Definitions of key terms.
• Philosophy & Design Principles -- The convictions that guide Protean's design.

---

Community

• Community -- Get help and connect with other Protean users.
• Development Setup -- Set up Protean locally for contributing.
• Testing Protean -- Test strategy, fixtures, and running the suite.
• Building Adapters -- Guidelines for creating custom adapters.