Revise and expand extension documentation (#30)

Major updates to extension docs: clarified architecture fit, composition, and adoption playbooks; expanded installation and usage instructions; improved compatibility, pipeline, and integration guidance for caching and multitenancy (core, ASP.NET Core, EF Core); added new reference pages and troubleshooting links; updated contributing guidelines and roadmap references.

Author: mheidari988

docs/concepts/architecture-fit.md

@@ -1,9 +1,30 @@
-# Architecture Fit
+# Architecture fit
 
-How extensions align with Jason Taylor's Clean Architecture template.
+CleanArchitecture.Extensions packages are designed to fit the Jason Taylor Clean Architecture template without changing its structure. The goal is to keep boundaries intact while adding cross-cutting behavior through composition.
 
-- Keep the template untouched: extensions plug in via packages, configuration, middleware/behaviors—not by forking or editing the upstream template.
-- Preserve boundaries: respect domain/application/infrastructure/UI separation and dependency direction.
-- Prefer composition: use pipeline behaviors, decorators, filters, and adapters instead of modifying core layers.
-- Match conventions: mirror naming, folder structure, and coding style from the reference `JasonTaylorCleanArchitecture` copy.
-- Stay optional: every extension should be opt-in with clear defaults and minimal required configuration.
+## Design principles
+
+- **No template fork**: packages integrate through DI, middleware, and MediatR behaviors.
+- **Layered boundaries**: Application depends on abstractions, Infrastructure provides adapters, and the host wires everything up.
+- **Opt-in by default**: each extension is optional and can be removed without structural changes.
+- **Convention-aligned**: naming, registration patterns, and pipeline order match the template.
+
+## Placement guidance
+
+| Layer | Typical responsibilities | Extension examples |
+| --- | --- | --- |
+| Application | Behaviors and abstractions | `QueryCachingBehavior`, `TenantEnforcementBehavior`, `ICurrentTenant` |
+| Infrastructure | Adapters and enforcement | `MemoryCacheAdapter`, `TenantSaveChangesInterceptor` |
+| Host (Web/API) | Middleware and endpoint filters | `TenantResolutionMiddleware`, `TenantEnforcementEndpointFilter` |
+
+## Template integration points
+
+- `src/Application/DependencyInjection.cs`: register MediatR behaviors.
+- `src/Infrastructure/DependencyInjection.cs`: register adapter services (caching, EF Core, etc.).
+- `src/Web/Program.cs`: add middleware and endpoint filters.
+
+## Removal strategy
+
+- Remove the NuGet package reference.
+- Remove `AddCleanArchitecture...` registrations and pipeline behaviors.
+- Delete any configuration sections and validation stores that were introduced.

docs/concepts/composition.md

@@ -1,10 +1,45 @@
-# Composition & Invariants
+# Composition and invariants
 
-Principles for combining extensions safely.
+Use the extensions together without losing clarity or breaking the template's ordering.
 
-- Isolation: each extension should have clear dependencies and avoid implicit cross-talk.
-- Pipelines first: prefer mediatr behaviors, filters, and decorators to hook in cross-cutting concerns.
-- Config clarity: document required settings, defaults, and compat matrices; fail fast on invalid configs.
-- Observability: emit structured logs/events for extension lifecycle (init, errors, important decisions).
-- Compatibility: declare supported .NET versions and CleanArchitecture template versions per extension page.
-- Exit strategy: provide guidance for disabling/removing an extension cleanly.
+## Invariants
+
+- **Explicit wiring**: every behavior or middleware is registered intentionally.
+- **No hidden dependencies**: cross-extension integration uses explicit opt-in hooks.
+- **Fail fast**: invalid configuration should be detected early (startup or first request).
+- **Keep handlers clean**: cross-cutting concerns live in pipeline behaviors, filters, or adapters.
+
+## Recommended composition order
+
+### MediatR pipeline (Application)
+
+A common order that aligns with the template is:
+
+1. Logging pre-processors
+2. Exception handling
+3. Authorization
+4. Validation
+5. Multitenancy validation/enforcement
+6. Caching behavior
+7. Performance logging
+
+Adjust for your template, but keep validation/enforcement before caching to avoid caching invalid requests.
+
+### HTTP middleware (Web/API)
+
+- Correlation and localization (if used)
+- Tenant resolution
+- Authentication/authorization
+- MVC/minimal API endpoints
+
+If you rely on claim-based tenant resolution, place authentication before the tenant resolution middleware.
+
+## Cross-extension integration
+
+- **Multitenancy + caching**: call `AddCleanArchitectureMultitenancyCaching` to include tenant IDs in cache keys.
+- **Multitenancy + EF Core**: ensure `TenantSaveChangesInterceptor` is registered and your DbContext uses tenant-aware model customization.
+
+## Compatibility notes
+
+- Keep `MultitenancyOptions` and EF Core options aligned (tenant ID property name, global entities, isolation mode).
+- Use consistent tenant identifiers across resolution sources (header, route, host) to avoid ambiguity.

docs/contributing/index.md

@@ -1,30 +1,39 @@
 # Contributing
 
-We keep the upstream Jason Taylor template pristine and ship everything as opt-in packages. Contributions must follow that contract and stay in sync with the docs and samples.
+We keep the upstream template pristine and ship everything as opt-in packages. Contributions must follow that contract and stay in sync with docs and tests.
 
 ## Principles
-- Template-first: mirror Jason Taylor’s conventions (folder layout, naming, MediatR pipeline ordering). Do **not** modify `JasonTaylorCleanArchitecture/`.
-- Extension = opt-in: minimal required config, no surprises; keep dependencies light.
-- Docs/samples-first: every behavior change lands with updated docs under `docs/` and, where applicable, a sample under `samples/`.
-- Tests-close-to-code: add/adjust tests in `tests/` for the package you touch.
+
+- **Template-first**: mirror Jason Taylor's conventions. Do not modify the upstream template.
+- **Opt-in by default**: minimal required configuration, clear defaults, easy removal.
+- **Docs and tests**: every behavior change updates docs under `docs/` and tests under `tests/`.
+- **Separation of concerns**: Application stays clean; Infrastructure and host adapt via composition.
 
 ## Workflow
-1. Pick the design doc: read the matching `HighLevelDocs/Domain*/CleanArchitecture.Extensions.*.md` before coding.
-2. Branch in this repo; keep changes inside `CleanArchitecture.Extensions/` solution (src/tests/samples/docs/build).
-3. Implement + test: add or update unit/integration tests for your changes.
-4. Update docs: extension page, recipes, reference, and roadmap if scope changes. Keep nav links valid.
-5. Preview docs locally (optional):  
-   ```powershell
-   python -m venv .venv
-   . .venv/Scripts/Activate.ps1
-   pip install -r docs/requirements.txt
-   mkdocs serve
-   ```
-6. Run relevant samples/tests where applicable and note any manual steps in your PR description.
-
-## Style (docs)
-- Follow the documentation strategy templates (overview → when to use → compat → install → usage → troubleshooting → samples/tests).
-- Use fenced code blocks with language tags (`bash`, `powershell`, `csharp`, `json`).
-- Prefer snippets from source to avoid drift; keep examples short and runnable.
-- Keep compatibility info current (template version, target frameworks, dependencies).
-- Format external links as Markdown links, for example `- [Roadmap](https://cleanarchitecture-extensions.github.io/CleanArchitecture.Extensions/roadmap/)` (avoid `Label: URL`).
+
+1) Read the relevant design doc in `HighLevelDocs/Domain*/CleanArchitecture.Extensions.*.md`.
+2) Make changes inside `CleanArchitecture.Extensions/` (src/tests/samples/docs/build).
+3) Update docs and ensure navigation links remain valid.
+4) Add or update tests for the package you touched.
+
+## Documentation style
+
+- Follow the extension template: overview, when to use, compat, install, usage, troubleshooting.
+- Use fenced code blocks with language tags (`csharp`, `powershell`, `json`).
+- Prefer short, runnable snippets and keep them under ~30 lines.
+- Use Markdown links for external URLs (e.g., `[Quickstart](https://...)`).
+
+## Testing expectations
+
+- Add unit tests for behaviors and configuration logic.
+- Add integration tests for EF Core and ASP.NET Core adapters when behavior changes.
+- Keep test names aligned with existing naming conventions.
+
+## Local docs preview
+
+```powershell
+python -m venv .venv
+. .venv/Scripts/Activate.ps1
+pip install -r docs/requirements.txt
+mkdocs serve
+```

docs/extensions/caching.md

@@ -1,103 +1,166 @@
 # Extension: Caching
 
 ## Overview
-Cache abstractions, key conventions, and a MediatR query caching behavior for Clean Architecture applications. Ships memory and distributed adapters, deterministic key generation, and options for stampede protection and TTL tuning without leaking infrastructure into handlers.
+
+CleanArchitecture.Extensions.Caching provides cache abstractions, deterministic key generation, and a MediatR query caching behavior. It is provider-agnostic and can target in-memory or distributed caches without leaking infrastructure concerns into handlers.
 
 ## When to use
 
-- You want query read-through caching without embedding cache calls in handlers.
-- You need deterministic, namespace/tenant-aware cache keys and provider-agnostic entry options.
-- You plan to start with in-memory caching for dev/test and swap to distributed stores (Redis via `IDistributedCache`) later.
+- You want transparent query caching without embedding cache calls in handlers.
+- You need deterministic, namespace-aware cache keys.
+- You want to start with memory caching in development and switch to distributed cache in production.
 
-## Prereqs & Compatibility
+## Prereqs and compatibility
 
-- Target frameworks: `net10.0`.
-- Dependencies: MediatR `13.1.0`, `Microsoft.Extensions.Caching.Abstractions`, `Microsoft.Extensions.Caching.Memory` (defaults); distributed adapter uses `IDistributedCache` (MemoryDistributedCache by default).
-- Pipeline fit: register `QueryCachingBehavior<,>` after authorization and request checks, and before performance logging to avoid skewing timing warnings.
+- Target framework: `net10.0`.
+- Dependencies: MediatR `13.1.0`, `Microsoft.Extensions.Caching.*` `10.0.0`.
 
 ## Install
 
-```bash
-dotnet add src/YourProject/YourProject.csproj package CleanArchitecture.Extensions.Caching
+```powershell
+dotnet add src/Application/Application.csproj package CleanArchitecture.Extensions.Caching
+dotnet add src/Infrastructure/Infrastructure.csproj package CleanArchitecture.Extensions.Caching
 ```
 
-## Usage
-
-### Register caching and pipeline behavior
+## Register services
 
 ```csharp
 using CleanArchitecture.Extensions.Caching;
 using CleanArchitecture.Extensions.Caching.Options;
-using MediatR;
 
-services.AddCleanArchitectureCaching(options =>
+builder.Services.AddCleanArchitectureCaching(options =>
 {
     options.DefaultNamespace = "MyApp";
-    options.MaxEntrySizeBytes = 256 * 1024; // optional
-}, queryOptions =>
+    options.MaxEntrySizeBytes = 256 * 1024;
+}, behaviorOptions =>
 {
-    queryOptions.DefaultTtl = TimeSpan.FromMinutes(5);
-    // Default predicate caches types whose names end with "Query"; override to use a marker instead:
-    // queryOptions.CachePredicate = req => req is IQueryMarker;
+    behaviorOptions.DefaultTtl = TimeSpan.FromMinutes(5);
 });
+```
 
-services.AddMediatR(cfg =>
+## Add the MediatR behavior
+
+```csharp
+builder.Services.AddMediatR(cfg =>
 {
     cfg.RegisterServicesFromAssemblyContaining<Program>();
-    cfg.AddCleanArchitectureCachingPipeline(); // place after request checks
+    cfg.AddCleanArchitectureCachingPipeline();
 });
 ```
 
-### Configure cache keys and TTLs
+## How query caching works
 
-- Keys follow `{namespace}:{tenant?}:{resource}:{hash}` via `ICacheKeyFactory` and `ICacheScope`. Override `ResourceNameSelector`/`HashFactory` in `QueryCachingBehaviorOptions` for custom resource naming or hashing (e.g., when parameters should be normalized).
-- Default TTL comes from `QueryCachingBehaviorOptions.DefaultTtl`; override per request type with `TtlByRequestType[typeof(MyQuery)] = TimeSpan.FromSeconds(30);`.
-- `CachePredicate` controls which requests are cacheable. By default it caches request types whose names end with "Query"; override to use markers or explicit type checks. `ResponseCachePredicate` can skip caching for responses you do not want stored.
+`QueryCachingBehavior<TRequest, TResponse>` applies cache-aside semantics:
 
-### Choose an adapter
+- The default predicate caches request types whose names end with `Query` (case-insensitive).
+- The cache key uses the request type name as the resource and a SHA256 hash of the request payload.
+- Cache hits short-circuit the handler; cache misses store the handler result.
 
-- Memory (default): registered as `ICache` by `AddCleanArchitectureCaching`, uses `MemoryCacheAdapter` with stampede locking and jitter.
-- Distributed: resolve `DistributedCacheAdapter` or replace `ICache` registration:
+Configure request selection and TTLs via `QueryCachingBehaviorOptions`:
 
 ```csharp
-services.AddCleanArchitectureCaching();
-services.AddStackExchangeRedisCache(opts => opts.Configuration = "..."); // or other IDistributedCache
-services.AddSingleton<ICache, DistributedCacheAdapter>(); // override default
+builder.Services.AddCleanArchitectureCaching(
+    configureQueryCaching: options =>
+    {
+        options.CachePredicate = request => request is ICacheableQuery; // your own marker interface
+        options.DefaultTtl = TimeSpan.FromMinutes(2);
+        options.TtlByRequestType[typeof(GetUserQuery)] = TimeSpan.FromSeconds(30);
+        options.CacheNullValues = false;
+    });
 ```
 
-### Entry options and stampede settings
+## Cache keys and scopes
 
-- `CachingOptions.DefaultEntryOptions` sets absolute/sliding expiration, priority, and size hints.
-- `CachingOptions.StampedePolicy` controls locking timeout and jitter for both adapters.
-- `CacheEntryOptions` can be passed per call or mapped by request type inside the behavior.
+- Key format: `{namespace}:{tenant?}:{resource}:{hash}`.
+- `DefaultCacheKeyFactory` hashes the request payload as JSON (deterministic SHA256).
+- `ICacheScope` supplies the namespace and optional tenant segment.
 
-### Response-aware caching
+If you customize keys, keep them deterministic and stable across versions.
 
-Use `QueryCachingBehaviorOptions.ResponseCachePredicate` to skip caching responses you want to exclude (for example, error payloads or partial results).
+## Choose a cache adapter
 
-## Key components
+The default `ICache` implementation is `MemoryCacheAdapter`.
 
-- `ICache`, `CacheEntryOptions`, `CacheStampedePolicy`, `CacheKey`, `ICacheKeyFactory`, `ICacheScope`, `ICacheSerializer`.
-- `MemoryCacheAdapter`, `DistributedCacheAdapter` (for `IDistributedCache`).
-- `QueryCachingBehavior<TRequest,TResponse>` with configurable TTLs, hash selection, predicate, and response filtering.
+!!! note
+    The memory adapter is process-local. In a multi-instance deployment, use a distributed cache.
+
+To use a distributed cache, register `IDistributedCache` and swap the adapter:
+
+```csharp
+using CleanArchitecture.Extensions.Caching.Adapters;
+using Microsoft.Extensions.Caching.StackExchangeRedis;
+
+builder.Services.AddCleanArchitectureCaching();
+builder.Services.AddStackExchangeRedisCache(options =>
+{
+    options.Configuration = "<redis-connection-string>";
+});
+
+builder.Services.AddSingleton<ICache, DistributedCacheAdapter>();
+```
+
+## Serialization
+
+The default serializer is `SystemTextJsonCacheSerializer`. Replace it when needed:
+
+```csharp
+using CleanArchitecture.Extensions.Caching.Serialization;
+
+builder.Services.AddSingleton<ICacheSerializer>(sp =>
+    new SystemTextJsonCacheSerializer(new JsonSerializerOptions(JsonSerializerDefaults.Web)));
+```
 
-## Pipeline ordering
+## Stampede protection and entry options
 
-- Recommended: Authorization → Request checks → **QueryCachingBehavior** → Performance/Logging → Handlers (align with the template order you already use).
-- Place caching after request checks to avoid caching invalid requests and before performance logging to exclude cache hits from handler timing warnings.
+- `CachingOptions.StampedePolicy` controls locking, timeouts, and jitter.
+- `CachingOptions.DefaultEntryOptions` defines expiration, priority, and size hints.
+
+```csharp
+builder.Services.AddCleanArchitectureCaching(options =>
+{
+    options.StampedePolicy = new CacheStampedePolicy
+    {
+        EnableLocking = true,
+        LockTimeout = TimeSpan.FromSeconds(3),
+        Jitter = TimeSpan.FromMilliseconds(50)
+    };
+});
+```
 
 ## Invalidation guidance
 
-- Cache-aside pattern: explicit `ICache.Remove` or `ICache.RemoveAsync` on command success or domain event handlers.
-- Include versioning and tenant segments in keys to avoid collisions; adjust namespace when making breaking DTO changes.
+Caching is read-through; invalidation is explicit. On command success or domain events, remove keys:
+
+```csharp
+await cache.RemoveAsync(cacheScope.Create("GetUserQuery", hash));
+```
+
+Keep key conventions stable and consider bumping the namespace for breaking DTO changes.
+
+## Multitenancy integration
+
+If you use multitenancy, call `AddCleanArchitectureMultitenancyCaching` to include tenant IDs in cache keys:
+
+```csharp
+builder.Services.AddCleanArchitectureCaching();
+builder.Services.AddCleanArchitectureMultitenancyCaching();
+```
+
+## Observability
+
+- `QueryCachingBehavior` logs cache hits and misses at `Debug` level.
+- Adapters log warnings on oversized payloads or deserialization failures.
+
+## Troubleshooting
+
+- Cache is never hit: ensure the request type matches the cache predicate and the behavior is registered.
+- Missing tenant in keys: call `AddCleanArchitectureMultitenancyCaching` after caching registration.
+- Large payloads: raise `MaxEntrySizeBytes` or skip caching via `ResponseCachePredicate`.
 
-## Backlog / Next Iteration
+## Samples and tests
 
-- Add PII/classification guardrails so sensitive payloads can be blocked or redirected to encrypted storage.
-- Provide an optional encrypting serializer wrapper for distributed caches with guidance for key management.
-- Expose instrumentation hooks (hits, misses, latency) without forcing a specific metrics provider.
-- Document and/or implement schema-versioned key strategies to support DTO shape changes safely.
+See the caching tests under `tests/` for behavior coverage and usage patterns.
 
-## Testing
+## Reference
 
-- Use the default memory adapter for Application tests; distributed adapter can use `MemoryDistributedCache` for deterministic runs.
+- [Caching options](../reference/caching-options.md)