📚 Documentation Cross-References¶

This document provides cross-references between all the persistence-related documentation in the Neuroglia framework.

🏛️ Persistence Documentation Hierarchy¶

Primary Guides¶

1. 🏛️ Persistence Patterns - Start Here

2. Purpose: Complete overview and decision framework for choosing persistence approaches

3. Contains: Pattern comparison, complexity levels, decision matrix, implementation examples

4. When to Read: When starting a new feature or project and need to choose persistence approach

5. 🔄 Unit of Work Pattern - Core Infrastructure

6. Purpose: Deep dive into the coordination layer that works with all persistence patterns
7. Contains: UnitOfWork implementation, event collection, pipeline integration
8. When to Read: When implementing command handlers or need to understand event coordination

Feature-Specific Guides¶

1. 🏛️ State-Based Persistence - Simple Approach

2. Purpose: Detailed implementation guide for Entity + State persistence pattern

3. Contains: Entity design, repositories, command handlers, event integration

4. When to Read: When implementing the simple persistence pattern

5. 🎯 Simple CQRS - Command/Query Handling

6. Purpose: CQRS implementation that works with both persistence patterns

7. Contains: Command/Query handlers, mediator usage, pipeline behaviors

8. When to Read: When implementing application layer handlers

9. 🔧 Pipeline Behaviors - Cross-Cutting Concerns

10. Purpose: Middleware patterns for validation, transactions, event dispatching
11. Contains: Pipeline behavior implementation, ordering, integration patterns
12. When to Read: When implementing cross-cutting concerns like validation or logging

Pattern Documentation¶

1. 🏛️ Domain Driven Design - Foundation Patterns
2. Purpose: Core DDD patterns and abstractions used by all approaches
3. Contains: Entity vs AggregateRoot patterns, domain events, DDD principles
4. When to Read: When learning DDD concepts or designing domain models

🗺️ Reading Path by Use Case¶

New to Neuroglia Framework¶

1. Start with Persistence Patterns for overview
2. Read Domain Driven Design for foundation concepts
3. Choose specific pattern guide based on your needs:
4. Simple: Persistence Patterns - Simple Entity
5. Complex: Domain Driven Design Event Sourcing sections
6. Learn coordination with Unit of Work
7. Implement handlers with Simple CQRS

Implementing Simple CRUD Application¶

1. Persistence Patterns → Choose Entity + State Persistence
2. Persistence Patterns - Simple Entity → Implementation guide
3. Unit of Work → Event coordination
4. Simple CQRS → Command/Query handlers

Building Complex Domain with Event Sourcing¶

1. Persistence Patterns → Choose AggregateRoot + Event Sourcing
2. Domain Driven Design → Full DDD patterns
3. Unit of Work → Event coordination
4. Simple CQRS → Command/Query handlers
5. Pipeline Behaviors → Cross-cutting concerns

Migrating Between Patterns¶

1. Persistence Patterns → Hybrid approach section
2. Unit of Work → Same infrastructure for both patterns
3. Specific implementation guides based on source and target patterns

Understanding Event Coordination¶

1. Unit of Work → Core coordination patterns
2. Pipeline Behaviors → Event dispatching middleware
3. Domain Driven Design → Domain event patterns

Implementing Cross-Cutting Concerns¶

1. Pipeline Behaviors → Core patterns
2. Unit of Work → Integration with event coordination
3. Simple CQRS → Handler integration

🔗 Key Relationships¶

All Patterns Use Same Infrastructure¶

• Unit of Work coordinates events for both Entity and AggregateRoot patterns
• Pipeline Behaviors provide cross-cutting concerns for both approaches
• CQRS/Mediator handles commands/queries regardless of persistence pattern
• Domain Events work the same way in both simple and complex patterns

Complexity Progression¶

Entity + State Persistence (⭐⭐☆☆☆)
    ↓ (add business complexity)
AggregateRoot + Event Sourcing (⭐⭐⭐⭐⭐)
    ↓ (mix both approaches)
Hybrid Approach (⭐⭐⭐☆☆)

Framework Integration Points¶

• Unit of Work ← All persistence patterns use this for event coordination
• Pipeline Behaviors ← All handlers use this for cross-cutting concerns
• Mediator ← All commands/queries route through this
• Domain Events ← All patterns raise events, same dispatching mechanism

📖 Quick Reference¶

This documentation structure ensures you can find the right information for your specific use case while understanding how all the pieces work together in the Neuroglia framework.