Guides

The guides section is your comprehensive reference for building applications with Protean. Whether you're modeling your first aggregate or architecting an event-sourced system, you'll find detailed, practical guidance for every concept and pattern Protean supports.

If you haven't already, start with the Tutorial to build a complete application from scratch. These guides go deeper into each topic and serve as a reference you'll return to as your application grows.

Choose Your Path

Protean supports three architectural approaches. Each builds on the one before it, so they also serve as a natural learning progression — start simple and add sophistication as your needs evolve.

graph LR
    DDD["<strong>Domain-Driven Design</strong><br/>Application Services<br/>Repositories<br/>Events"]
    CQRS["<strong>CQRS</strong><br/>Commands & Handlers<br/>Projections<br/>Read/Write Separation"]
    ES["<strong>Event Sourcing</strong><br/>Event Replay<br/>Temporal Queries<br/>Full Audit Trail"]

    DDD --> CQRS --> ES

    style DDD fill:#e8f5e9,stroke:#43a047
    style CQRS fill:#e3f2fd,stroke:#1e88e5
    style ES fill:#fce4ec,stroke:#e53935

Domain-Driven Design

For teams that want clean domain modeling with application services, repositories, and event-driven side effects. The simplest way to use Protean.

Start here if: You're new to Protean, building a straightforward application, or your team is new to DDD.

DDD Pathway

CQRS

Adds Commands, Command Handlers, and read-optimized Projections on top of DDD. Separates your write and read models for better scalability and clarity.

Start here if: You need independent scaling of reads and writes, want explicit command/query separation, or are building a system with complex read requirements.

CQRS Pathway

Event Sourcing

Derives aggregate state entirely from event replay. Full audit trail, temporal queries, and complete traceability.

Start here if: You need regulatory audit trails, temporal analysis, or your domain has complex state transitions where history matters.

Event Sourcing Pathway

Browse by Topic

• Domain Model

  ---

  Model your business concepts with aggregates, entities, value objects, and rich behavior.

  Compose a Domain · Define Concepts · Add Behavior

• Application Layer

  ---

  Process state changes through application services, commands, and command handlers.

  Change State

• Reactive Layer

  ---

  Respond to state changes with event handlers, projections, and subscribers.

  Consume State

• Infrastructure

  ---

  Configure databases, run the async processing server, and use the CLI.

  Configuration · Server · CLI

• Testing

  ---

  Strategies for testing every layer of your application.

  Testing

How Do I...?

A quick reference for common tasks. See the full task index for more.

I want to...	Go to
Define an aggregate	Aggregates
Add a child entity	Entities
Enforce business rules	Invariants
Handle a request (synchronous)	Application Services
Handle a request (via commands)	Commands + Handlers
Save or load an aggregate	Persist · Retrieve
React to a domain event	Event Handlers
Build a read-optimized view	Projections
Choose between CQRS and ES	Architecture Decision
Test my domain logic	Testing

What Elements Do I Need?

This matrix shows which Protean domain elements are used in each architectural approach:

Element	DDD	CQRS	Event Sourcing
Aggregates	✓	✓	✓
Entities	✓	✓	✓
Value Objects	✓	✓	✓
Domain Services	✓	✓	✓
Repositories	✓	✓	—
Application Services	✓	—	—
Commands	—	✓	✓
Command Handlers	—	✓	✓
Events	✓	✓	✓
Event Handlers	✓	✓	✓
Subscribers	✓	✓	✓
Projections	—	✓	✓
Projectors	—	✓	✓
ES Repositories	—	—	✓
@apply decorator	—	—	✓

✓ = core to this path, — = not used