Add comprehensive documentation for eventual consistency architecture and implementation

[Copilot]

This PR provides detailed documentation explaining how the NetCorePal Cloud Framework ensures eventual consistency in distributed systems and identifies the key packages used for integration events.

What's Added

📚 Comprehensive Documentation

• docs/content/eventual-consistency-architecture.md - In-depth explanation of the framework's eventual consistency implementation
• docs/content/architecture-diagrams.md - Visual diagrams illustrating the architecture with Mermaid charts
• EVENTUAL_CONSISTENCY_ANSWER.md - Direct answers to the original questions

🔧 Key Findings Documented

Packages Used for Integration Events:

• DotNetCore.CAP - Core distributed transaction and event handling
• MediatR - Local domain event processing
• Entity Framework Core - Data persistence and transaction management
• RabbitMQ (via CAP) - Message queue integration

Eventual Consistency Mechanisms:

1. Outbox Pattern - Integration events are persisted in the same database transaction as business data
2. Two-Phase Processing - Local transactions ensure strong consistency, async event publishing ensures eventual consistency
3. Reliable Delivery - CAP guarantees that persisted events will eventually be published
4. Retry Mechanisms - Automatic retry for failed event processing (default 10 times)
5. Idempotency - Event handlers must support duplicate message processing

🏗️ Architecture Overview

The framework uses a sophisticated approach combining:

• Local strong consistency within service boundaries using database transactions
• Eventual consistency across services using the outbox pattern and message queues
• Fault tolerance through CAP's built-in retry and error handling mechanisms

Key components include:

• CapIntegrationEventPublisher - Publishes integration events via CAP
• IPublisherTransactionHandler - Coordinates database and CAP transactions
• AppDbContextBase - Provides unit of work pattern with transaction management
• CommandUnitOfWorkBehavior - Ensures commands execute within transactions

📊 Visual Documentation

The documentation includes detailed sequence diagrams, class diagrams, and architecture flowcharts that illustrate:

• Complete event processing lifecycle from command to remote service processing
• Transaction boundaries and consistency guarantees
• Component relationships and data flow
• Error handling and retry mechanisms

This documentation serves as a comprehensive guide for developers wanting to understand how the framework achieves distributed system reliability and consistency.

Fixes #7.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

@Frogley 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.