Document the Paramore.Brighter core assembly architecture for new contributors

[Copilot]

This PR adds comprehensive documentation for the Paramore.Brighter core assembly to help new contributors understand the internal architecture and design decisions.

What's Added

Created docs/guides/paramore_brighter_core_guide.md - a comprehensive 1,278-line guide covering:

Core Architecture

• Command Dispatcher & Command Processor patterns - How the CommandProcessor orchestrates request handling
• Pipeline-driven architecture - Handler chains with middleware support via attributes
• Handler interface hierarchy - From IHandleRequests to RequestHandler<T> base classes
• Request/response foundation - Commands, Events, Queries, and Messages

Dispatch Mechanisms Deep Dive

Each dispatch method is documented with PlantUML diagrams and implementation details:

• Send - Point-to-point command dispatch with single handler validation
• Publish - Pub-sub event dispatch with parallel handler execution and exception aggregation
• Post - Asynchronous messaging via outbox pattern (DepositPost + ClearOutbox)
• Call - Request-reply pattern supporting both in-memory and external bus scenarios

Advanced Features

• Outbox Pattern - Detailed coverage of transactional messaging with DepositPost/ClearOutbox
• Message transformation pipeline - Custom transforms for compression, encryption, etc.
• Synchronization context - BrighterSynchronizationContext for async operation management
• Resilience patterns - Built-in retry, circuit breaker, timeout, and fallback handlers

Development Guidance

• Testing strategies - Unit testing, integration testing, and test doubles
• Pipeline tracing - Debugging and validation techniques
• Best practices - Handler development, message design, performance considerations
• Custom middleware - How to create attributes and handlers for cross-cutting concerns

Focus on "Under the Hood"

The guide specifically focuses on implementation details that would help contributors understand:

• How pipelines are constructed and executed
• How different request types flow through the system
• How middleware attributes work with the pipeline builder
• How the outbox pattern ensures transactional consistency
• How async operations are managed with custom synchronization contexts

Code Examples

Includes practical examples throughout:

[RequestLogging(1, HandlerTiming.Before)]
[Retry("RetryPolicy", 2)] 
[CircuitBreaker("CBPolicy", 3)]
public override MyCommand Handle(MyCommand command)
{
    // Business logic with declarative middleware
    return base.Handle(command);
}

This documentation complements existing user-facing docs and Contributing.md by providing the architectural context needed to make informed changes to the Brighter codebase.

Fixes #3647.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Clean Code Collective
Want more control? Customize Code Health rules or catch issues early with our IDE extension and CLI tool.

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Clean Code Collective
Want more control? Customize Code Health rules or catch issues early with our IDE extension and CLI tool.

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Clean Code Collective
Want more control? Customize Code Health rules or catch issues early with our IDE extension and CLI tool.