feat: Introduce Roslyn analyzers to enforce architectural patterns and update documentation.

Author: aalmada

BookStore.slnx

@@ -1,4 +1,8 @@
 <Solution>
+  <Folder Name="/src/">
+    <Project Path="src/BookStore.ApiService.Analyzers.Tests/BookStore.ApiService.Analyzers.Tests.csproj" />
+    <Project Path="src/BookStore.ApiService.Analyzers/BookStore.ApiService.Analyzers.csproj" />
+  </Folder>
   <Project Path="src\BookStore.ApiService\BookStore.ApiService.csproj" />
   <Project Path="src\BookStore.AppHost\BookStore.AppHost.csproj" />
   <Project Path="src\BookStore.ServiceDefaults\BookStore.ServiceDefaults.csproj" />

README.md

@@ -52,7 +52,20 @@ The Aspire dashboard opens automatically, providing access to:
 - **Optimistic Concurrency** with ETags
 - **Distributed Tracing** with correlation/causation IDs
 - **API Versioning** (header-based, v1.0)
-- **Soft Deletion** with restore capability
+- **Soft Deletion** - Logical deletes with restore capability
+
+## Architecture Enforcement
+
+The project includes a custom **Roslyn Analyzer** (`BookStore.ApiService.Analyzers`) that enforces Event Sourcing, CQRS, and DDD patterns:
+
+- ✅ Events must be immutable record types
+- ✅ Commands follow CQRS conventions
+- ✅ Aggregates use proper Marten Apply methods
+- ✅ Handlers follow Wolverine conventions
+- ✅ Consistent namespace organization
+
+See [Analyzer Rules Documentation](docs/analyzer-rules.md) for details.
+
 - **Native OpenAPI** with Scalar UI
 - **Structured Logging** with correlation IDs