Decision Trees & Guidelines

Quick decision trees and guidelines to help you make the right architectural choices when using Axon Framework with EAF.

🎯 How to Use This Guide

Each decision tree follows this pattern:

1. Start with a question about your use case
2. Follow the arrows based on your answers
3. Arrive at a recommendation with reasoning
4. See examples of the recommended pattern

🏗️ Aggregate Design Decisions

When to Create a New Aggregate?

Decision Factors:

Factor	New Aggregate	Entity within Aggregate
Identity	Globally unique business identity	Identity dependent on parent
Lifecycle	Independent creation/deletion	Created/deleted with parent
Invariants	Enforces own business rules	Participates in parent's rules
Consistency	Own transaction boundary	Part of parent's transaction
Size	Reasonable number of events	Doesn't bloat parent aggregate

Examples:

// ✅ Good: Separate aggregates
class Order { ... }        // Independent lifecycle
class Customer { ... }     // Independent lifecycle
class Product { ... }      // Independent lifecycle

// ✅ Good: Entity within aggregate
class Order {
    private val lineItems: MutableList<OrderLineItem> = mutableListOf()
    // OrderLineItem has no independent lifecycle
}

// ❌ Avoid: Everything in one aggregate
class OrderAggregate {
    // Order, Customer, Product, Payment, Shipping all in one
    // This violates aggregate boundaries
}

Aggregate Size Guidelines

📊 Event Store Strategy

PostgreSQL vs Axon Server Decision

When to Use EAF PostgreSQL:

• ✅ Starting with CQRS/ES
• ✅ Single instance deployment
• ✅ < 1M events per day
• ✅ Need multi-tenancy
• ✅ Want database familiarity

When to Consider Axon Server:

• ✅ Need horizontal scaling
• ✅ Multiple service instances
• ✅ > 1M events per day
• ✅ Need advanced routing
• ✅ Plan for distributed architecture

🔄 Event Processing Strategy

Tracking vs Subscribing Processors

Configuration Examples:

// ✅ Real-time projections - Tracking
config.registerTrackingEventProcessor("user-projections") {
    TrackingEventProcessorConfiguration
        .forParallelProcessing(2)
        .andBatchSize(10) // Small batches for real-time
        .andInitialTrackingToken { it.eventStore().createHeadToken() }
}

// ✅ Analytics - Tracking with large batches
config.registerTrackingEventProcessor("user-analytics") {
    TrackingEventProcessorConfiguration
        .forSingleThreadedProcessing()
        .andBatchSize(100) // Large batches for efficiency
        .andInitialTrackingToken { it.eventStore().createHeadToken() }
}

// ⚠️ Only when you absolutely cannot use Tracking
config.registerSubscribingEventProcessor("immediate-notifications")

🏢 Multi-Tenancy Patterns

Tenant Isolation Strategy

EAF Recommendation: Row-Level Tenancy

// ✅ EAF Standard Pattern
@Entity
@Table(name = "user_projections")
data class UserProjection(
    @Id val userId: String,
    @Column(nullable = false) val tenantId: String, // Always include
    // ... other fields
)

// Always filter by tenant
interface UserProjectionRepository : JpaRepository<UserProjection, String> {
    fun findByTenantIdAndUserId(tenantId: String, userId: String): UserProjection?
    fun findAllByTenantId(tenantId: String): List<UserProjection>
}

// Always validate tenant context
@EventHandler
fun on(event: UserCreatedEvent, @MetaData("tenant_id") tenantId: String) {
    require(event.tenantId == tenantId) { "Tenant mismatch" }
    // ... handle event
}

🔄 Saga Usage Decisions

When to Use Sagas

Saga Use Cases:

// ✅ Good Saga use case - Order fulfillment
@Saga
class OrderFulfillmentSaga {
    // Coordinates: Inventory → Payment → Shipping → Notification
    // Handles: Timeouts, compensation, external service calls
}

// ✅ Good Saga use case - User onboarding
@Saga
class UserOnboardingSaga {
    // Coordinates: Account creation → License allocation → Welcome email
    // Handles: External service integration, compensation
}

// ❌ Avoid Saga - Simple event propagation
// Just use event handlers instead:
@EventHandler
fun on(event: UserCreatedEvent) {
    // Simple notification - no saga needed
    notificationService.sendWelcomeEmail(event.userId)
}

📈 Performance Decisions

Optimization Strategy

Performance Tuning Checklist:

// ✅ Command Optimization
@CommandHandler
fun handle(command: CreateUserCommand) {
    // Keep business logic minimal
    // Defer heavy operations to event handlers
    val user = User(command)
    repository.save(user)
}

// ✅ Query Optimization
@Entity
@Table(indexes = [
    Index(name = "idx_tenant_user", columnList = "tenantId,userId"),
    Index(name = "idx_tenant_email", columnList = "tenantId,email")
])
data class UserProjection(...)

// ✅ Event Processing Optimization
config.registerTrackingEventProcessor("projections") {
    TrackingEventProcessorConfiguration
        .forParallelProcessing(4) // Parallel threads
        .andBatchSize(50) // Optimize batch size
}

// ✅ Caching
@Cacheable(value = ["users"], key = "#userId")
fun findUser(userId: String): UserProjection?

🧪 Testing Strategy Decisions

What to Test and How

🚨 Common Anti-Patterns to Avoid

❌ What NOT to Do

🎯 Quick Decision Summary

Decision	Small Scale	Medium Scale	Large Scale
Event Store	EAF PostgreSQL	EAF PostgreSQL	Consider Axon Server
Processors	Tracking (small batches)	Tracking (medium batches)	Tracking (large batches)
Tenancy	Row-level	Row-level	Schema-level
Aggregates	Simple boundaries	Clear boundaries	Very clear boundaries
Testing	Unit + Integration	Unit + Integration + E2E	All levels + Performance
Monitoring	Basic metrics	Comprehensive metrics	Full observability

---

💡 Remember: These are guidelines, not rigid rules. Always consider your specific context and requirements when making architectural decisions!