Skip to content

Start Here

A guided reading order through Protean's documentation. Follow the sections below from top to bottom, or jump to the topic you need.

Installation

Get Protean up and running. The Installation guide walks you through setting up Python, creating a virtual environment, and installing Protean.

Hello, Protean!

New to Protean? Start with Hello, Protean! — define an aggregate, save it, and load it back in under 20 lines. This is the fastest way to see what Protean feels like.

Quickstart

Want to go further? The Quickstart builds a working domain in 5 minutes — an aggregate, a command, an event, and handlers — all running in-memory with zero infrastructure.

Tutorial

For a guided, end-to-end learning experience, work through Building Bookshelf — a 10-part tutorial that takes you from your first aggregate to a fully tested application with a real database. It covers:

  • Part I — Aggregates, fields, value objects, entities, and business rules
  • Part II — Commands, domain events, and event handlers
  • Part III — Projections and real database persistence
  • Part IV — Testing strategies and next steps

Event Sourcing Tutorial

If you're interested in Event Sourcing, work through Building Fidelis — a 22-chapter deep dive that builds a banking ledger with immutable audit trails, projections, and production tooling. It assumes familiarity with the Bookshelf tutorial above.

Upgrading from 0.14?

If you're migrating an existing project, the Migration Guide covers required changes, behavioral differences, and what's new.

Core concepts

Get to know the driving principles and core ideas that shape this framework in Philosophy. In Domain Elements, explore key DDD elements like Aggregates, Repositories, Events, and more to understand the core structures of Protean.

Building with Protean

Everything you need to know to build ambitious applications with Protean is in the Guides section.

Protean supports three architectural approaches — DDD, CQRS, and Event Sourcing — each building on the one before it. Start with DDD and evolve later. See Choose a Path to compare the options.

Within the guides, you'll find everything from crafting rich domain models to adding behavior and business rules, wiring up commands and handlers, and reacting to state changes with event handlers and projections.

Finding your way around

If you know what you want to do but aren't sure where to look, start here:

  • How Do I...? — A task-oriented index. Look up what you're trying to accomplish and jump straight to the right guide.
  • Contents — A flat, searchable listing of every page in the documentation.

Configuration and infrastructure

Protean uses a simple configuration file (domain.toml) to wire in databases, brokers, caches, and other infrastructure without changing domain code. See Configuration for details.

For infrastructure adapters — PostgreSQL, Elasticsearch, Redis, MessageDB, and more — see Adapters.

Async processing

The Protean Server is an async engine that processes events, commands, and external messages in the background. It supports the outbox pattern for reliable delivery and includes built-in observability.

CLI

The protean command-line tool helps you scaffold projects, run the server, manage databases, and more. See CLI for the full list of commands.

Testing

Protean provides pytest fixtures and a layered testing strategy — from fast in-memory domain model tests to full integration tests with real infrastructure. See Testing.

Patterns and best practices

Looking for architectural guidance? The Patterns section covers recurring design patterns — aggregate sizing, idempotent handlers, validation layering, event versioning, and more.

Glossary

Stuck on a term? There is a comprehensive Glossary to help you find clear definitions for all the concepts and jargon you'll encounter as you navigate Protean.

Community

You're not alone on this journey. Join our Community to connect with fellow Protean users, share experiences, and get your questions answered. Together, we can make Protean even better!