chore: added a 'shadowing' section

Author: aaguiarz

docs/content/best-practices/adoption-patterns.mdx

@@ -168,6 +168,26 @@ Some companies decide to wrap <ProductName format={ProductNameFormat.ShortForm}/
 
 On the other hand, adding another service increases latency and adds additional complexity.
 
+## Shadowing the <ProductName format={ProductNameFormat.ShortForm}/> API
+
+When migrating from an existing authorization system to <ProductName format={ProductNameFormat.ShortForm}/>, it's recommended to first run both systems in parallel, with <ProductName format={ProductNameFormat.ShortForm}/> in "shadow mode". This means that while the existing system continues to make the actual authorization decisions, you also make calls to <ProductName format={ProductNameFormat.ShortForm}/> asynchornously and compare the results.
+
+This approach has several benefits:
+
+- You can validate that your authorization model and relationship tuples are correctly configured before switching to <ProductName format={ProductNameFormat.ShortForm}/>.
+- You can measure the performance impact of adding <ProductName format={ProductNameFormat.ShortForm}/> calls to your application.
+- You can identify edge cases where the <ProductName format={ProductNameFormat.ShortForm}/> results differ from your existing system.
+- You can gradually build confidence in the <ProductName format={ProductNameFormat.ShortForm}/> implementation.
+
+To implement shadow mode:
+
+1. Configure your application to make authorization checks against both systems
+2. Log any discrepancies between the two systems
+3. Analyze the logs to identify and fix any issues
+4. Once confident in the results, switch to using <ProductName format={ProductNameFormat.ShortForm}/> as the source of truth
+
+This pattern is particularly useful for critical systems where authorization errors could have significant impact.
+
 ## Related Sections
 
 <RelatedSection