[AF5] Complete rewrite of multi-tenancy extension for Axon Framework 5

[theoema]

Hey @smcvb @abuijze @CodeDrivenMitch @schananas! Me and my startup founders are planning on using AF5 in production in the coming months. And one of those features we are going to need is multitenancy, so I've taken it upon myself during the last 3 days to rewrite the multitenancy extension for AF5. Its definitely not perfect, but I've tried my best to keep the extension inline with the spirit of AF5 and I think it went really well considering the time spent.

This is quite a big PR, but I've prepared some documentation both here in the PR and in the project to make it as easy as possible to review. I'm sure reviewing this isnt priority number one for any of your right now, but feel free to let me know if theres anything I could do to make the process easier!

---

Summary

This PR represents a complete rewrite of the multi-tenancy extension for Axon Framework 5. The extension has been redesigned from the ground up to align with AF5's core principles: async-native architecture, framework-agnostic design (not tied to Spring), and programmatic configuration.

Key Highlights

• Complete architectural redesign following AF5 patterns
• New TenantComponent concept for tenant-scoped dependency injection
• Programmatic configuration via MultiTenancyConfigurer (Spring optional)
• Full support for both embedded and Axon Server deployments
• Comprehensive integration test suite
• Preliminary documentation covering all major use cases

Note: Since I dont have a Axon Server license, I have not been able to test the functionality with multiple contexts on axon server, but it does have tests for embedded multitenancy, and tests for single-tenant axon server setup.

Architectural Changes from Axon 4

Package Structure

• Renamed from org.axonframework.extensions.multitenancy to org.axonframework.extension.multitenancy (singular) for consistency with AF5 conventions

Configuration Model: From Spring-Centric to Programmatic

Axon 4 relied heavily on Spring XML/YAML configuration and auto-discovery through Spring components.

Axon 5 introduces a layered approach:

1. Core Layer (multitenancy module) - Pure programmatic configuration, zero Spring dependencies
2. Spring Layer (multitenancy-spring) - Optional Spring Data JPA support
3. Spring Boot Layer (multitenancy-spring-boot-autoconfigure) - Auto-configuration for Spring Boot users

// AF5: Programmatic configuration - works without Spring
EventSourcingConfigurer configurer = EventSourcingConfigurer.create();

MultiTenancyConfigurer.enhance(configurer)
    .registerTenantProvider(config -> new SimpleTenantProvider(tenants))
    .registerTargetTenantResolver(config -> new MetadataBasedTenantResolver())
    .tenantComponent(OrderRepository.class, tenant -> new InMemoryOrderRepository());

AxonConfiguration configuration = configurer.start();

Core Abstractions

Component	Axon 4	Axon 5
TenantDescriptor	Complex with configuration responsibilities	Lightweight data holder with tenantId and properties
TenantProvider	Static provider	Dynamic, subscription-based with subscribe(MultiTenantAwareComponent)
TargetTenantResolver	Separate resolvers per message type	Unified generic resolver BiFunction<Message, Collection, TenantDescriptor>
Configuration	Spring-driven	MultiTenancyConfigurer with fluent builder API

---

TenantComponent: Tenant-Scoped Dependency Injection

A key innovation in this rewrite is the TenantComponent concept, enabling automatic injection of tenant-scoped dependencies into message handlers.

The Problem

In multi-tenant systems, components like repositories need to be isolated per tenant. Previously, developers had to manually resolve tenant context and look up the appropriate instance.

The Solution

// Register a tenant-scoped component
MultiTenancyConfigurer.enhance(configurer)
    .tenantComponent(
        OrderRepository.class,
        tenant -> new JpaOrderRepository(getDataSourceForTenant(tenant))
    );

// Automatically injected with the correct tenant's instance
@EventHandler
void handle(OrderCreatedEvent event, OrderRepository repository) {
    repository.save(new OrderProjection(event));
    // repository is automatically the tenant-specific instance!
}

// Or access via ProcessingContext (TenantAwareProcessingContext)
@EventHandler
void handle(OrderCreatedEvent event, ProcessingContext context) {
    OrderRepository repository = context.component(OrderRepository.class);
    // Same tenant-scoped instance
}

How It Works

1. Registration: tenantComponent() registers a factory function that creates instances per tenant
2. Lazy Creation: Instances are created on first access, not on tenant registration
3. Caching: TenantComponentRegistry caches instances in a ConcurrentHashMap
4. Resolution: TenantComponentResolver implements ParameterResolver to inject the correct instance
5. Cleanup: When tenants are removed, AutoCloseable.close() is called automatically

Spring Boot Auto-Discovery

For Spring Boot users, classes implementing TenantComponent are automatically discovered and registered:

  public class TenantAuditService implements TenantComponent<TenantAuditService> {
      private final Clock clock;  // Spring-injected
      private final String tenantId;

      public TenantAuditService(Clock clock) {  // Factory constructor
          this.clock = clock;
          this.tenantId = null;
      }

      @Override
      public TenantAuditService createForTenant(TenantDescriptor tenant) {
          return new TenantAuditService(this.clock, tenant.tenantId());
      }
  }

---

Spring Data JPA: Automatic Tenant-Scoped Repositories

One of the most powerful features for Spring Boot users is the automatic tenant-scoped JPA repository support. When enabled, Spring Data repositories are automatically discovered, wrapped with per-tenant EntityManagerFactory instances, and injected into handlers with zero configuration. A version of this existed in previous versions of the extension, but it relied on Spring Data's AbstractRoutingDataSource, which is blocking and expects there to be a ThreadLocal context which would be the opposite of async, so I designed a strategy that is async, and I actually think its incredible clean. Now with that said I think that there is a case to be made against per tenant EMFs, which we perhaps should have a discussion about.

Enabling the Feature

axon:
  multi-tenancy:
    tenants:
      - tenant-a
      - tenant-b
    jpa:
      tenant-repositories: true  # This is the key setting

Providing a TenantDataSourceProvider

The only required bean is a TenantDataSourceProvider that returns a DataSource per tenant:

  @Bean
  public TenantDataSourceProvider tenantDataSourceProvider() {
      return tenant -> DataSourceBuilder.create()
              .url("jdbc:postgresql://localhost:5432/" + tenant.tenantId())
              .username("postgres")
              .password("password")
              .build();
  }

Zero-Configuration Repository Usage

Just define your repositories as normal Spring Data interfaces:

  public interface OrderRepository extends JpaRepository<Order, String> {
      List<Order> findByCustomerId(String customerId);
  }

And use them directly in event handlers - the correct tenant's instance is injected automatically:

  @EventHandler
  public void on(OrderCreatedEvent event, OrderRepository repository) {
      // repository is automatically scoped to the tenant from event metadata!
      repository.save(new Order(event.orderId(), event.customerId()));
  }

How It Works Under the Hood

1. Discovery: MultiTenancySpringDataJpaAutoConfiguration scans for all Repository interfaces
2. Per-Tenant EMF: TenantEntityManagerFactoryBuilder creates separate EntityManagerFactory per tenant
3. Transaction Management: TenantTransactionManagerBuilder provides per-tenant transaction managers
4. Repository Wrapping: TenantJpaRepositoryFactory creates repository instances with:
   - Tenant-specific SharedEntityManager
   - Transactional proxy wrapping all method calls
   - Automatic caching per tenant
5. Injection: Repositories registered as tenant components, resolved via ParameterResolverFactory

Advanced Configuration

For more control over JPA settings:

  @Bean
  public TenantEntityManagerFactoryBuilder tenantEntityManagerFactoryBuilder(
          TenantDataSourceProvider dataSourceProvider) {
      return TenantEntityManagerFactoryBuilder
              .forDataSourceProvider(dataSourceProvider)
              .packagesToScan("com.myapp.domain")
              .jpaProperty("hibernate.hbm2ddl.auto", "validate")
              .jpaProperty("hibernate.dialect", "org.hibernate.dialect.PostgreSQL10Dialect")
              .persistenceUnitName("myapp")
              .build();
  }

---

Event Processor Design Considerations

The multi-tenant event processor implementation (MultiTenantPooledStreamingEventProcessorModule) works but required several workarounds due to framework limitations, which sadly led to more than desirable code duplication. I believe this could be significantly cleaner with some extensibility improvements in the main framework.

Suggested Framework Improvements

If we were to make a small change in the main framework, a developer with an pre-existing axon framework codebase wouldn't need to rewrite anything to get the extension working. If we adjust the main framework to register EventProcessor as the interface type instead of the concrete PooledStreamingEventProcessor. This would allow the multi-tenancy extension to use the same decorator pattern as CommandBus, QueryBus, and EventStore - enabling zero-code-change multi-tenancy for event processors. This would mean that framework users can basically "flip a switch" to enable multitenancy. All of their slice configurations would remain the same, they only need to add a few lines of "main configuration" like configuring the tenant resolver, correlation provider and tenantprovider.

---

Integration Tests

The extension includes comprehensive integration tests covering four deployment scenarios:

Test Modules

Module	Description	Tests
multitenancy-integration-tests-embedded	Pure AF5, in-memory storage	7 tests
multitenancy-integration-tests-axon-server	AF5 + Axon Server (Docker)	4 tests
multitenancy-integration-tests-springboot-embedded	Spring Boot + JPA (H2)	7 tests
multitenancy-integration-tests-springboot-axonserver	Spring Boot + Axon Server (Docker+H2)	4 tests

Scenarios Covered

• Tenant Isolation: Data from Tenant A not visible in Tenant B
• Same Entity ID Across Tenants: No conflicts when same ID exists in different tenants
• Dynamic Tenant Registration: Adding tenants at runtime via SimpleTenantProvider
• CommandDispatcher Propagation: Tenant context propagates through automation workflows
• Missing Metadata Handling: Proper NoSuchTenantException when tenant not specified
• Spring Data Repository Scoping: Automatic tenant-scoped JPA repositories
• TenantComponent Injection: Correct tenant instance injected into handlers

Test Domain Model

Uses a university course management domain:

• CreateCourse command → CourseCreated event → CoursesStats projection
• WhenCourseCreatedThenNotify automation testing CommandDispatcher propagation

---

JPA-Based Event Store Support

The extension theoretically supports JPA-based event stores through the segment factory pattern:

MultiTenancyConfigurer.enhance(configurer)
    .registerEventStoreSegmentFactory((config, tenant) ->
        createJpaEventStoreForTenant(tenant)
    );

Note: While the architecture supports this, I have not personally tested JPA-based event stores as I'm not familiar with that configuration. The Axon Server and in-memory event store paths are thoroughly tested.

---

Documentation

Preliminary documentation is available in docs/reference/modules/ROOT/pages/:

Setup Guides (4)

• Getting Started - Step-by-step transformation from single to multi-tenant
• Axon Server Integration - Non-Spring applications with Axon Server
• Spring Boot Integration - Spring Boot with embedded storage
• Spring Boot + Axon Server - "Golden path" production setup

Concept Documentation (4)

• Tenant Management - TenantProvider, dynamic tenants
• Message Routing - TargetTenantResolver, metadata propagation
• Infrastructure - Multi-tenant buses and event stores
• Projections - Tenant-scoped repositories and EntityManager

Configuration Reference (4)

• Tenant Resolution - Custom resolvers
• Event Processors - MultiTenantPooledStreamingEventProcessorModule
• Tenant Components - TenantComponent pattern
• Dynamic Tenants - Runtime tenant management

The documentation covers the major use cases but would benefit from community feedback and real-world usage examples. It's functional but I wouldn't call it polished, it was thrown together quite quickly.

---

Breaking Changes from Axon 4 Extension

1. Package rename: extensions.multitenancy → extension.multitenancy
2. Configuration API: Spring-based → Programmatic MultiTenancyConfigurer
3. TenantDescriptor: Simplified to data holder (removed configuration methods)
4. Segment factories: New factory pattern for per-tenant infrastructure

---

Files Changed

• Core module (multitenancy/) - Framework-agnostic multi-tenancy support
• Spring module (multitenancy-spring/) - Spring Data JPA integration
• Spring Boot module (multitenancy-spring-boot-autoconfigure/) - Auto-configuration
• Axon Server connector (multitenancy-axon-server-connector/) - Distributed support
• Integration tests (4 modules) - Comprehensive test coverage
• Documentation (docs/) - 15 AsciiDoc files

---

Checklist

• Code compiles and all tests pass
• Package structure aligned with AF5 conventions
• Programmatic configuration works without Spring
• Spring Boot auto-configuration works
• Axon Server integration tested (with Docker)
• TenantComponent injection working
• CommandDispatcher tenant propagation verified
• Documentation covers major use cases
• JPA event store testing (not personally verified)

---

[CLAassistant]

All committers have signed the CLA.