mkdocs.yml

site_name: Protean
site_url: https://docs.proteanhq.com
repo_name: proteanhq/protean
repo_url: https://github.com/proteanhq/protean
copyright: Copyright © 2019 - 2026 Subhash Bhushan

theme:
  name: material
  custom_dir: docs/overrides
  logo: assets/logo.png
  favicon: assets/favicon.png
  language: custom
  font:
    text: Inter
    code: JetBrains Mono
  palette:
  - media: '(prefers-color-scheme: light)'
    scheme: default
    primary: teal
    accent: teal
    toggle:
      icon: material/lightbulb
      name: Switch to dark mode
  - media: '(prefers-color-scheme: dark)'
    scheme: slate
    primary: teal
    accent: teal
    toggle:
      icon: material/lightbulb-outline
      name: Switch to light mode

  features:
    - content.code.annotate
    - content.code.copy
    - content.code.select
    - content.tabs.link
    - content.tooltips
    - navigation.footer
    - navigation.indexes
    - navigation.sections
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.instant.progress
    - navigation.path
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.suggest
    - toc.follow

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js
  - javascripts/mermaid-init.js

exclude_docs: |
  adr/

not_in_nav: |
  CLAUDE.md

plugins:
  - privacy
  - search
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths:
            - src
          options:
            docstring_style: google
            docstring_section_style: spacy
            show_docstring_attributes: true
            show_docstring_parameters: true
            show_docstring_returns: true
            show_docstring_raises: true
            show_docstring_examples: true
            members_order: source
            show_source: true
            show_bases: true
            show_root_heading: true
            show_root_full_path: false
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            merge_init_into_class: true
            inherited_members: false
            group_by_category: true
            show_signature_annotations: true
            separate_signature: true
            signature_crossrefs: true
            heading_level: 2
            filters:
              - "!^_[^_]"
              - "!^__pydantic"
              - "!^__new__"
              - "!^model_config"
              - "!^model_fields"
markdown_extensions:
  - admonition
  - attr_list
  - tables
  - md_in_html
  - mdx_include
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.snippets:
      check_paths: true
      base_path: docs_src
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
nav:
  - Protean:
    - index.md
    - start-here.md
    - why-protean.md
    - concepts/philosophy/index.md
    - contents.md
    - how-do-i.md

  - Getting Started:
    - guides/getting-started/installation.md
    - "Hello, Protean!": guides/getting-started/hello.md
    - guides/getting-started/quickstart.md
    - Tutorial:
      - guides/getting-started/tutorial/index.md
      - "Part I - Building the Domain":
        - "1. Your First Aggregate": guides/getting-started/tutorial/01-your-first-aggregate.md
        - "2. Rich Fields and Value Objects": guides/getting-started/tutorial/02-fields-and-value-objects.md
        - "3. Entities and Associations": guides/getting-started/tutorial/03-entities-and-associations.md
        - "4. Business Rules": guides/getting-started/tutorial/04-business-rules.md
      - "Part II - Making It Real":
        - "5. Commands and Handlers": guides/getting-started/tutorial/05-commands.md
        - "6. Events and Reactions": guides/getting-started/tutorial/06-events-and-reactions.md
        - "7. Projections": guides/getting-started/tutorial/07-projections.md
        - "8. Connecting a Real Database": guides/getting-started/tutorial/08-persistence.md
        - "9. Structuring the Project": guides/getting-started/tutorial/09-project-structure.md
        - "10. Exposing the Domain Through an API": guides/getting-started/tutorial/10-api.md
        - "11. Testing Your Domain": guides/getting-started/tutorial/11-testing.md
      - "Part III - Growing the System":
        - "12. Going Async — The Server": guides/getting-started/tutorial/12-going-async.md
        - "13. Domain Services": guides/getting-started/tutorial/13-domain-services.md
        - "14. Subscribers": guides/getting-started/tutorial/14-subscribers.md
        - "15. Fact Events": guides/getting-started/tutorial/15-fact-events.md
      - "Part IV - Production Operations":
        - "16. Message Tracing": guides/getting-started/tutorial/16-message-tracing.md
        - "17. Dead Letter Queues": guides/getting-started/tutorial/17-dead-letter-queues.md
        - "18. Monitoring Health": guides/getting-started/tutorial/18-monitoring.md
        - "19. Priority Lanes": guides/getting-started/tutorial/19-priority-lanes.md
      - "Part V - System Mastery":
        - "20. Process Managers": guides/getting-started/tutorial/20-process-managers.md
        - "21. Advanced Query Patterns": guides/getting-started/tutorial/21-query-patterns.md
        - "22. The Full Picture": guides/getting-started/tutorial/22-full-picture.md
    - "Event Sourcing Tutorial":
      - guides/getting-started/es-tutorial/index.md
      - "Part I - Building the Foundation":
        - "1. The Faithful Ledger": guides/getting-started/es-tutorial/01-the-faithful-ledger.md
        - "2. Deposits and Withdrawals": guides/getting-started/es-tutorial/02-deposits-and-withdrawals.md
        - "3. Commands and the Pipeline": guides/getting-started/es-tutorial/03-commands-and-pipeline.md
        - "4. Business Rules": guides/getting-started/es-tutorial/04-business-rules.md
        - "5. Testing the Ledger": guides/getting-started/es-tutorial/05-testing-the-ledger.md
      - "Part II - Growing the Platform":
        - "6. The Account Dashboard": guides/getting-started/es-tutorial/06-account-dashboard.md
        - "7. Reacting to Events": guides/getting-started/es-tutorial/07-reacting-to-events.md
        - "8. Going Async": guides/getting-started/es-tutorial/08-going-async.md
        - "9. Transferring Funds": guides/getting-started/es-tutorial/09-transferring-funds.md
        - "10. Entities Inside Aggregates": guides/getting-started/es-tutorial/10-entities-inside-aggregates.md
      - "Part III - Evolution and Adaptation":
        - "11. Event Upcasting": guides/getting-started/es-tutorial/11-event-upcasting.md
        - "12. Snapshots": guides/getting-started/es-tutorial/12-snapshots.md
        - "13. Temporal Queries": guides/getting-started/es-tutorial/13-temporal-queries.md
        - "14. External Integrations": guides/getting-started/es-tutorial/14-connecting-outside-world.md
      - "Part IV - Production Operations":
        - "15. Fact Events": guides/getting-started/es-tutorial/15-fact-events.md
        - "16. Message Tracing": guides/getting-started/es-tutorial/16-message-tracing.md
        - "17. Dead Letter Queues": guides/getting-started/es-tutorial/17-dead-letter-queues.md
        - "18. Monitoring Health": guides/getting-started/es-tutorial/18-monitoring-health.md
        - "19. Priority Lanes": guides/getting-started/es-tutorial/19-priority-lanes.md
      - "Part V - Mastery":
        - "20. Rebuilding Projections": guides/getting-started/es-tutorial/20-rebuilding-projections.md
        - "21. The Event Store as a Database": guides/getting-started/es-tutorial/21-event-store-database.md
        - "22. The Full Picture": guides/getting-started/es-tutorial/22-the-full-picture.md

  - Guides:
    - guides/index.md
    - Choose a Path:
      - guides/pathways/index.md
      - guides/pathways/ddd.md
      - guides/pathways/cqrs.md
      - guides/pathways/event-sourcing.md
      - guides/pathways/migrating-between-architectures.md
    - Set Up the Domain:
      - guides/compose-a-domain/index.md
      - guides/compose-a-domain/register-elements.md
      - guides/compose-a-domain/initialize-domain.md
      - guides/compose-a-domain/activate-domain.md
      - guides/compose-a-domain/when-to-compose.md
      - guides/compose-a-domain/inspecting-the-ir.md
      - guides/compose-a-domain/schema-generation.md
    - Model Your Domain:
      - guides/domain-definition/index.md
      - guides/domain-definition/aggregates.md
      - guides/domain-definition/entities.md
      - guides/domain-definition/value-objects.md
      - guides/domain-definition/relationships.md
      - guides/domain-definition/events.md
      - concepts/building-blocks/choosing-element-types.md
    - Add Rules and Behavior:
      - guides/domain-behavior/index.md
      - guides/domain-behavior/validations.md
      - guides/domain-behavior/invariants.md
      - guides/domain-behavior/aggregate-mutation.md
      - guides/domain-behavior/status-transitions.md
      - guides/domain-behavior/raising-events.md
      - guides/domain-behavior/message-tracing.md
      - guides/domain-behavior/message-enrichment.md
      - guides/domain-behavior/domain-services.md
    - Change State:
      - guides/change-state/index.md
      - guides/change-state/application-services.md
      - guides/change-state/commands.md
      - guides/change-state/command-handlers.md
      - guides/change-state/repositories.md
      - guides/change-state/persist-aggregates.md
      - guides/change-state/retrieve-aggregates.md
      - guides/change-state/temporal-queries.md
      - guides/change-state/unit-of-work.md
    - React to Changes:
      - guides/consume-state/index.md
      - guides/consume-state/event-handlers.md
      - guides/consume-state/process-managers.md
      - guides/consume-state/projections.md
      - guides/consume-state/projectors.md
      - guides/consume-state/query-handlers.md
      - guides/consume-state/subscribers.md
      - guides/consume-state/cloudevents.md
      - guides/consume-state/event-upcasting.md
    - Expose Your Domain:
      - guides/fastapi/index.md
      - guides/fastapi/testing-endpoints.md
    - Run the Server:
      - guides/server/index.md
      - guides/server/error-handling.md
      - guides/server/production-deployment.md
      - guides/server/logging.md
      - guides/server/monitoring.md
      - guides/server/using-priority-lanes.md
      - guides/server/external-event-dispatch.md
    - Multi-Domain Applications:
      - guides/multi-domain-applications.md
    - Test Your Application:
      - guides/testing/index.md
      - guides/testing/domain-model-tests.md
      - guides/testing/application-tests.md
      - guides/testing/event-sourcing-tests.md
      - guides/testing/integration-tests.md
      - guides/testing/fixtures-and-patterns.md

  - Reference:
    - reference/index.md
    - Domain Elements:
      - reference/domain-elements/index.md
      - reference/domain-elements/element-decorators.md
      - reference/domain-elements/object-model.md
      - reference/domain-elements/identity.md
    - Fields:
      - reference/fields/index.md
      - reference/fields/defining-fields.md
      - reference/fields/simple-fields.md
      - reference/fields/container-fields.md
      - reference/fields/association-fields.md
      - reference/fields/arguments.md
    - Configuration:
      - reference/configuration/index.md
    - CLI:
      - reference/cli/index.md
      - Project:
        - reference/cli/project/index.md
        - reference/cli/project/new.md
        - reference/cli/project/discovery.md
        - reference/cli/project/shell.md
        - reference/cli/project/docs.md
      - Runtime:
        - reference/cli/runtime/index.md
        - reference/cli/runtime/server.md
        - reference/cli/runtime/observatory.md
        - reference/cli/runtime/subscriptions.md
      - IR:
        - reference/cli/ir.md
      - Schema:
        - reference/cli/schema.md
      - Data:
        - reference/cli/data/index.md
        - reference/cli/data/database.md
        - reference/cli/data/dlq.md
        - reference/cli/data/events.md
        - reference/cli/data/snapshot.md
        - reference/cli/data/projection.md
    - Server:
      - reference/server/index.md
      - reference/server/subscription-types.md
      - reference/server/configuration.md
      - reference/server/supervisor.md
      - reference/server/observability.md
    - Adapters:
      - reference/adapters/index.md
      - Database:
        - reference/adapters/database/index.md
        - reference/adapters/database/memory.md
        - reference/adapters/database/sqlite.md
        - reference/adapters/database/postgresql.md
        - reference/adapters/database/elasticsearch.md
        - reference/adapters/database/custom-databases.md
      - Brokers:
        - reference/adapters/broker/index.md
        - reference/adapters/broker/inline.md
        - reference/adapters/broker/redis.md
        - reference/adapters/broker/redis-pubsub.md
        - reference/adapters/broker/custom-brokers.md
      - Caches:
        - reference/adapters/cache/index.md
        - reference/adapters/cache/redis.md
      - Event Stores:
        - reference/adapters/eventstore/index.md
        - reference/adapters/eventstore/message-db.md
    - Type Checking:
      - reference/type-checking/index.md
    - Testing:
      - reference/testing/index.md
      - reference/testing/pytest-plugin.md
      - reference/testing/conformance.md
    - Migration:
      - reference/migration/index.md
      - reference/migration/v0-15.md
    - Troubleshooting:
      - reference/troubleshooting.md

  - Concepts:
    - concepts/index.md
    - Philosophy & Principles:
      - concepts/philosophy/index.md
      - concepts/philosophy/always-valid.md
    - Foundations:
      - concepts/foundations/index.md
      - concepts/foundations/ubiquitous-language.md
      - concepts/foundations/bounded-contexts.md
      - concepts/foundations/analysis-model.md
      - concepts/foundations/identity.md
      - concepts/foundations/invariants.md
      - concepts/foundations/changing-state.md
      - concepts/foundations/streams.md
    - Architecture Patterns:
      - concepts/architecture/index.md
      - concepts/architecture/ddd.md
      - concepts/architecture/cqrs.md
      - concepts/architecture/event-sourcing.md
      - concepts/architecture/architecture-decision.md
    - Building Blocks:
      - concepts/building-blocks/index.md
      - concepts/building-blocks/aggregates.md
      - concepts/building-blocks/entities.md
      - concepts/building-blocks/value-objects.md
      - concepts/building-blocks/domain-services.md
      - concepts/building-blocks/events.md
      - concepts/building-blocks/commands.md
      - concepts/building-blocks/command-handlers.md
      - concepts/building-blocks/event-handlers.md
      - concepts/building-blocks/application-services.md
      - concepts/building-blocks/repositories.md
      - concepts/building-blocks/subscribers.md
      - concepts/building-blocks/projections.md
      - concepts/building-blocks/projectors.md
      - concepts/building-blocks/query-handlers.md
      - concepts/building-blocks/process-managers.md
    - Async Processing:
      - concepts/async-processing/index.md
      - concepts/async-processing/engine.md
      - concepts/async-processing/subscriptions.md
      - concepts/async-processing/outbox.md
      - concepts/async-processing/priority-lanes.md
      - concepts/async-processing/stream-categories.md
    - Ports & Adapters:
      - concepts/ports-and-adapters/index.md
    - Internals:
      - concepts/internals/index.md
      - concepts/internals/field-system.md
      - concepts/internals/shadow-fields.md
      - concepts/internals/query-system.md
      - concepts/internals/event-sourcing.md
      - concepts/internals/event-upcasting.md
      - concepts/internals/ir-specification.md

  - Patterns & Recipes:
    - patterns/index.md
    - Aggregate Design:
      - patterns/design-small-aggregates.md
      - patterns/one-aggregate-per-transaction.md
      - patterns/optimistic-concurrency-as-design-tool.md
      - patterns/encapsulate-state-changes.md
      - patterns/replace-primitives-with-value-objects.md
      - patterns/factory-methods-for-aggregate-creation.md
      - patterns/aggregate-state-machines.md
    - Event-Driven Patterns:
      - patterns/design-events-for-consumers.md
      - patterns/idempotent-event-handlers.md
      - patterns/event-versioning-and-evolution.md
      - patterns/command-idempotency.md
      - patterns/coordinating-long-running-processes.md
      - patterns/process-manager-lifecycle.md
      - patterns/message-tracing.md
      - patterns/message-enrichment.md
      - patterns/multi-tenancy.md
      - patterns/cloudevents-interoperability.md
    - Architecture & Quality:
      - patterns/organize-by-domain-concept.md
      - patterns/validation-layering.md
      - patterns/thin-handlers-rich-domain.md
      - patterns/application-service-vs-command-handler.md
      - patterns/projection-granularity.md
      - patterns/projection-rebuilds-as-deployment.md
      - patterns/eventual-consistency-in-uis.md
      - patterns/testing-domain-logic-in-isolation.md
      - patterns/dual-mode-testing.md
      - patterns/testing-event-driven-flows.md
      - patterns/setting-up-and-tearing-down-database-for-tests.md
    - Identity & Communication:
      - patterns/creating-identities-early.md
      - patterns/connect-concepts-across-domains.md
      - patterns/consuming-events-from-other-domains.md
      - patterns/sharing-event-classes-across-domains.md
      - patterns/fact-events-as-integration-contracts.md
      - patterns/publishing-events-to-external-brokers.md
    - Operations:
      - patterns/running-data-migrations-with-priority-lanes.md
      - patterns/classify-async-processing-errors.md
      - patterns/temporal-queries.md

  - API:
    - api/index.md
    - api/domain.md
    - api/aggregate.md
    - api/entity.md
    - api/value-object.md
    - api/messages.md
    - api/handlers.md
    - api/services.md
    - api/repository.md
    - api/unit-of-work.md
    - api/queryset.md
    - api/database-model.md
    - api/read-models.md
    - api/event-processing.md
    - Fields:
      - api/fields/index.md
      - api/fields/simple.md
      - api/fields/containers.md
      - api/fields/association.md
      - api/fields/embedded.md
      - api/fields/spec.md
    - Ports:
      - api/ports/index.md
      - api/ports/provider.md
      - api/ports/broker.md
      - api/ports/event-store.md
      - api/ports/cache.md
    - Utilities:
      - api/testing.md
      - api/processing.md
      - api/eventing.md

  - glossary.md

  - Community:
    - community/index.md
    - Contributing:
      - community/contributing/setup.md
      - community/contributing/testing.md
      - community/contributing/adapters.md
    - Quality Report: community/quality.md