From f406aa2f21ede2e3de67966132dabd73156f1972 Mon Sep 17 00:00:00 2001
From: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Date: Mon, 14 Sep 2026 13:46:11 +0530
Subject: [PATCH] docs: collect refreshed mongo-ops wiki site (API-correct
 overhaul, v0.1.5)

---
 mongo-ops/01_overview/index.html              | 166 ++++++-
 mongo-ops/02_components/index.html            | 459 ++++++++++++------
 .../03_use_cases/01_basic_crud/index.html     | 273 +++++++----
 .../03_use_cases/02_custom_repo/index.html    | 225 ++++++---
 .../03_use_cases/03_transactions/index.html   | 213 +++++---
 .../03_use_cases/04_pagination/index.html     | 231 ++++++---
 .../03_use_cases/05_soft_deletes/index.html   | 239 +++++----
 .../03_use_cases/06_multi_model/index.html    | 225 ++++++---
 mongo-ops/03_use_cases/07_caching/index.html  | 242 ++++-----
 .../03_use_cases/08_population/index.html     | 195 ++++----
 .../09_advanced_population/index.html         | 215 ++++----
 .../10_cache_and_population/index.html        | 229 +++++----
 .../11_cache_lifecycle/index.html             | 104 ++--
 .../12_transaction_helper/index.html          | 199 ++++----
 .../03_use_cases/13_index_creation/index.html | 146 +++---
 .../03_use_cases/14_testing_guide/index.html  | 314 +++++++-----
 mongo-ops/04_best_practices/index.html        | 103 +++-
 mongo-ops/05_patterns/index.html              | 175 ++++---
 mongo-ops/06_error_handling/index.html        | 201 ++++++--
 mongo-ops/07_testing_example/index.html       | 142 ++++--
 mongo-ops/404.html                            |   2 +-
 mongo-ops/index.html                          | 105 +++-
 mongo-ops/search/search_index.json            |   2 +-
 mongo-ops/sitemap.xml.gz                      | Bin 127 -> 127 bytes
 24 files changed, 2880 insertions(+), 1525 deletions(-)

diff --git a/mongo-ops/01_overview/index.html b/mongo-ops/01_overview/index.html
index fe90fad..a61789f 100644
--- a/mongo-ops/01_overview/index.html
+++ b/mongo-ops/01_overview/index.html
@@ -388,6 +388,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -420,6 +422,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -428,9 +432,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#library-overview" class="md-nav__link">
+  <a href="#architecture" class="md-nav__link">
     <span class="md-ellipsis">
-      Library Overview
+      🏗️ Architecture
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#lifecycle-rules" class="md-nav__link">
+    <span class="md-ellipsis">
+      🔄 Lifecycle Rules
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#which-repository-should-you-use" class="md-nav__link">
+    <span class="md-ellipsis">
+      🧭 Which Repository Should You Use?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#read-next" class="md-nav__link">
+    <span class="md-ellipsis">
+      ➡️ Read Next
     </span>
   </a>
   
@@ -501,7 +532,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -998,18 +1029,125 @@
 
 
 
-  <h1>Overview</h1>
-
-<h2 id="library-overview">Library Overview</h2>
-<p><code>mongo-ops</code> is a modular MongoDB operations layer for FastAPI microservices. It provides:</p>
-<ul>
-<li>Async connection management</li>
-<li>Base document models with auto-timestamps</li>
-<li>Generic CRUD repository pattern</li>
-<li>Transaction support</li>
-<li>Model registration system</li>
-</ul>
+<h1 id="library-overview">Library Overview</h1>
+<p><code>mongo-ops</code> gives FastAPI/microservice teams a small, opinionated toolkit for talking to MongoDB asynchronously. This page builds the mental model: what the layers are, in what order they must be wired up, and which repository to reach for.</p>
 <hr />
+<h2 id="architecture">🏗️ Architecture</h2>
+<div class="language-text highlight"><span class="filename">Text Only</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>┌───────────────────────────────────────────────────────────┐
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>│  Application (FastAPI)                                    │
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>│  ┌─────────────┬───────────────┬───────────────┬─────────┐ │
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>│  │ CachedBase  │ Populating    │ BaseRepository│  Raw    │ │
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>│  │ Repository  │ Repository    │ (CRUDMixin)   │ Motor   │ │
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>│  └──────┬──────┴───────┬───────┴───────┬───────┴─────────┘ │
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>│         │              │               │                   │
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>│  ┌──────┴──────┐  ┌────┴──────┐  ┌─────┴─────────────────┐ │
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>│  │ Cache backend│  │ Population│  │ TransactionManager    │ │
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>│  │ memory/redis │  │ Engine    │  │ (session helpers)     │ │
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>│  └──────┬──────┘  └────┬──────┘  └─────────┬─────────────┘ │
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>│  ┌──────┴──────────────────────────────────┴─────────────┐ │
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>│  │ ModelRegistry  (models, indexes, cache lifecycle)      │ │
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>│  └──────┬─────────────────────────────────────────────────┘ │
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>│  ┌──────┴─────────────────────────────────────────────────┐ │
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>│  │ MongoConnectionManager  (Motor client + database)      │ │
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>│  └──────────────────────────┬──────────────────────────────┘ │
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>└─────────────────────────────┼────────────────────────────────┘
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>                              ▼
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>                        MongoDB (Motor / PyMongo)
+</code></pre></div>
+<p>The layers build on each other:</p>
+<ol>
+<li><strong>Connection</strong> — <code>MongoConnectionManager</code> owns the Motor client and active database.</li>
+<li><strong>Models</strong> — <code>BaseDocument</code> (Pydantic v2) gives every document <code>id</code> (aliased <code>_id</code>) plus <code>created_at</code> / <code>updated_at</code>.</li>
+<li><strong>CRUD</strong> — <code>CRUDMixin</code> / <code>BaseRepository</code> implement generic async CRUD against a collection.</li>
+<li><strong>Startup</strong> — <code>ModelRegistry</code> centralizes model + index registration and cache lifecycle for multi-collection services.</li>
+<li><strong>Advanced layers</strong> — caching and population compose <em>around</em> a repository:</li>
+<li><code>CachedBaseRepository</code> wraps <code>BaseRepository</code> with a <code>CacheBackend</code>.</li>
+<li><code>PopulatingRepository</code> wraps <code>BaseRepository</code> with a <code>PopulationEngine</code>.</li>
+<li><strong>Transactions</strong> — <code>TransactionManager</code> runs a list of async operations atomically on a session.</li>
+</ol>
+<hr />
+<h2 id="lifecycle-rules">🔄 Lifecycle Rules</h2>
+<p><code>mongo-ops</code> has a strict startup order. Violating it raises fast, loud exceptions:</p>
+<table>
+<thead>
+<tr>
+<th>Step</th>
+<th>Call</th>
+<th>Why</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>1</td>
+<td><code>await MongoConnectionManager.connect(uri, db_name)</code></td>
+<td>Without a connection, <code>get_database()</code>/<code>get_client()</code> raise <code>RuntimeError("Database not connected...")</code>.</td>
+</tr>
+<tr>
+<td>2</td>
+<td><code>await ModelRegistry.initialize_all()</code></td>
+<td>Create registered indexes (idempotent via <code>create_index</code>).</td>
+</tr>
+<tr>
+<td>3</td>
+<td><code>await ModelRegistry.set_cache_backend(...)</code> then <code>await ModelRegistry.initialize_cache()</code></td>
+<td>Must happen <strong>after</strong> connection, <strong>before</strong> any cache-backed operation. Raises <code>RuntimeError("No cache backend registered...")</code> if skipped.</td>
+</tr>
+<tr>
+<td>4</td>
+<td>Use repositories</td>
+<td>Constructed repos resolve the collection from the live database.</td>
+</tr>
+<tr>
+<td>5</td>
+<td><code>await ModelRegistry.shutdown_cache()</code> + <code>await MongoConnectionManager.disconnect()</code></td>
+<td>On shutdown (in-memory TTL task cancelled; Redis pub/sub closed).</td>
+</tr>
+</tbody>
+</table>
+<p>The canonical wiring is the FastAPI <strong>lifespan</strong> context manager (see <a href="../03_use_cases/01_basic_crud/">use case 01</a>).</p>
+<hr />
+<h2 id="which-repository-should-you-use">🧭 Which Repository Should You Use?</h2>
+<table>
+<thead>
+<tr>
+<th>Repository</th>
+<th>Use when</th>
+<th>Adds</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>BaseRepository[T]</code></td>
+<td>Plain CRUD — the default</td>
+<td>nothing extra</td>
+</tr>
+<tr>
+<td><code>CachedBaseRepository[T]</code></td>
+<td>Read‑heavy, low‑write fields (lookups by <code>_id</code>)</td>
+<td>cache‑first <code>get_by_id</code>, cache on <code>create</code>, invalidate on <code>update</code>/<code>delete</code>, <code>warm_cache</code></td>
+</tr>
+<tr>
+<td><code>PopulatingRepository[T]</code></td>
+<td>You return related docs (FK references) denormalized</td>
+<td><code>_populate</code> on read, <code>_depopulate</code> on write, FK‑guarded <code>patch</code></td>
+</tr>
+<tr>
+<td><code>CRUDMixin</code></td>
+<td>Reusing CRUD inside an existing class</td>
+<td>raw CRUD against a collection you already have</td>
+</tr>
+</tbody>
+</table>
+<blockquote>
+<p>There is <strong>no built‑in <code>CachedPopulatingRepository</code></strong>. <a href="../03_use_cases/10_cache_and_population/">Use case 10</a> shows how to compose caching + population in a small subclass.</p>
+</blockquote>
+<hr />
+<h2 id="read-next">➡️ Read Next</h2>
+<ul>
+<li><a href="../02_components/">Core Components</a> — the validated public API surface.</li>
+<li><a href="../03_use_cases/01_basic_crud/">Use case 01</a> — the minimal FastAPI app.</li>
+<li><a href="../04_best_practices/">Best Practices</a> — team-wide conventions.</li>
+</ul>
 
 
 
diff --git a/mongo-ops/02_components/index.html b/mongo-ops/02_components/index.html
index dc614b8..955cad6 100644
--- a/mongo-ops/02_components/index.html
+++ b/mongo-ops/02_components/index.html
@@ -20,7 +20,7 @@
     
     
       
-        <title>02 components - Mongo Ops Documentation</title>
+        <title>Core Components - Mongo Ops Documentation</title>
       
     
     
@@ -108,7 +108,7 @@
         <div class="md-header__topic" data-md-component="header-topic">
           <span class="md-ellipsis">
             
-              02 components
+              Core Components
             
           </span>
         </div>
@@ -458,13 +458,15 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -477,7 +479,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -490,6 +492,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -498,16 +502,6 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#core-components" class="md-nav__link">
-    <span class="md-ellipsis">
-      Core Components
-    </span>
-  </a>
-  
-    <nav class="md-nav" aria-label="Core Components">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
   <a href="#1-mongoconnectionmanager" class="md-nav__link">
     <span class="md-ellipsis">
       1. MongoConnectionManager
@@ -515,93 +509,120 @@
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#2-basedocument" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#2-basedocument-pyobjectid" class="md-nav__link">
     <span class="md-ellipsis">
-      2. BaseDocument
+      2. BaseDocument &amp; PyObjectId
     </span>
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#3-baserepositoryt" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#3-crudmixint" class="md-nav__link">
     <span class="md-ellipsis">
-      3. BaseRepository[T]
+      3. CRUDMixin[T]
     </span>
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#4-transactionmanager" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#4-baserepositoryt" class="md-nav__link">
     <span class="md-ellipsis">
-      4. TransactionManager
+      4. BaseRepository[T]
     </span>
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#5-modelregistry" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#5-populatingrepositoryt" class="md-nav__link">
     <span class="md-ellipsis">
-      5. ModelRegistry
+      5. PopulatingRepository[T]
     </span>
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#6-cache-backend" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#6-transactionmanager" class="md-nav__link">
     <span class="md-ellipsis">
-      6. Cache Backend
+      6. TransactionManager
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="6. Cache Backend">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#7-modelregistry" class="md-nav__link">
+    <span class="md-ellipsis">
+      7. ModelRegistry
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#8-cache-layer" class="md-nav__link">
+    <span class="md-ellipsis">
+      8. Cache Layer
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="8. Cache Layer">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#61-cachebackend-abstract" class="md-nav__link">
+  <a href="#81-cachebackend-abstract" class="md-nav__link">
     <span class="md-ellipsis">
-      6.1 CacheBackend (abstract)
+      8.1 CacheBackend (abstract)
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#62-cacheconfig" class="md-nav__link">
+  <a href="#82-cachestats" class="md-nav__link">
     <span class="md-ellipsis">
-      6.2 CacheConfig
+      8.2 CacheStats
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#63-inmemorycachebackend" class="md-nav__link">
+  <a href="#83-cacheconfig" class="md-nav__link">
     <span class="md-ellipsis">
-      6.3 InMemoryCacheBackend
+      8.3 CacheConfig
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#64-rediscachebackend" class="md-nav__link">
+  <a href="#84-inmemorycachebackend" class="md-nav__link">
     <span class="md-ellipsis">
-      6.4 RedisCacheBackend
+      8.4 InMemoryCacheBackend
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#65-cachedbaserepositoryt" class="md-nav__link">
+  <a href="#85-rediscachebackend" class="md-nav__link">
     <span class="md-ellipsis">
-      6.5 CachedBaseRepository[T]
+      8.5 RedisCacheBackend
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#86-cachedbaserepositoryt" class="md-nav__link">
+    <span class="md-ellipsis">
+      8.6 CachedBaseRepository[T]
     </span>
   </a>
   
@@ -611,39 +632,39 @@
     </nav>
   
 </li>
-        
-          <li class="md-nav__item">
-  <a href="#7-population-engine" class="md-nav__link">
+      
+        <li class="md-nav__item">
+  <a href="#9-population-layer" class="md-nav__link">
     <span class="md-ellipsis">
-      7. Population Engine
+      9. Population Layer
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="7. Population Engine">
+    <nav class="md-nav" aria-label="9. Population Layer">
       <ul class="md-nav__list">
         
           <li class="md-nav__item">
-  <a href="#71-populaterule" class="md-nav__link">
+  <a href="#91-populaterule" class="md-nav__link">
     <span class="md-ellipsis">
-      7.1 PopulateRule
+      9.1 PopulateRule
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#72-populationengine" class="md-nav__link">
+  <a href="#92-populationengine" class="md-nav__link">
     <span class="md-ellipsis">
-      7.2 PopulationEngine
+      9.2 PopulationEngine
     </span>
   </a>
   
 </li>
         
           <li class="md-nav__item">
-  <a href="#73-populatingrepositoryt" class="md-nav__link">
+  <a href="#93-circularreferenceerrorvalueerror" class="md-nav__link">
     <span class="md-ellipsis">
-      7.3 PopulatingRepository[T]
+      9.3 CircularReferenceError(ValueError)
     </span>
   </a>
   
@@ -653,9 +674,13 @@
     </nav>
   
 </li>
-        
-      </ul>
-    </nav>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
   
 </li>
       
@@ -1157,100 +1182,252 @@
 
 
 
-  <h1>02 components</h1>
-
-<h2 id="core-components">Core Components</h2>
-<h3 id="1-mongoconnectionmanager">1. MongoConnectionManager</h3>
-<p>Manages MongoDB connections with async lifecycle.
-<strong>Methods:</strong></p>
+<h1 id="core-components">Core Components</h1>
+<p>A validated reference to the public API. Signatures match the code in <code>mongo_ops/</code> exactly. See the use cases for runnable recipes.</p>
+<hr />
+<h2 id="1-mongoconnectionmanager">1. MongoConnectionManager</h2>
+<p>Singleton-style owner of the Motor client and active database.</p>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Signature</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>connect</code></td>
+<td><code>async (uri: str, db_name: str, **kwargs) -&gt; AsyncIOMotorDatabase</code></td>
+<td>Creates <code>AsyncIOMotorClient(uri, **kwargs)</code> and selects the database. Idempotent.</td>
+</tr>
+<tr>
+<td><code>disconnect</code></td>
+<td><code>async () -&gt; None</code></td>
+<td>Closes the client and clears state.</td>
+</tr>
+<tr>
+<td><code>get_database</code></td>
+<td><code>() -&gt; AsyncIOMotorDatabase</code></td>
+<td>Returns the active database; raises <code>RuntimeError("Database not connected. Call connect() first.")</code>.</td>
+</tr>
+<tr>
+<td><code>get_client</code></td>
+<td><code>() -&gt; AsyncIOMotorClient</code></td>
+<td>Returns the active client; raises <code>RuntimeError("Client not connected. Call connect() first.")</code>.</td>
+</tr>
+<tr>
+<td><code>lifespan</code></td>
+<td><code>async ctx manager (uri, db_name, **kwargs)</code></td>
+<td><code>connect()</code> on entry, yields the database, <code>disconnect()</code> on exit. Designed for FastAPI lifespan.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="2-basedocument-pyobjectid">2. BaseDocument &amp; PyObjectId</h2>
+<p><code>BaseDocument(BaseModel)</code> — inherit for every Mongo entity.</p>
 <ul>
-<li><code>connect(uri, db_name, **kwargs)</code> - Connect to MongoDB</li>
-<li><code>disconnect()</code> - Close connection</li>
-<li><code>get_database()</code> - Get current database instance</li>
-<li><code>get_client()</code> - Get current client instance</li>
-<li><code>lifespan(uri, db_name, **kwargs)</code> - Context manager for FastAPI lifespan</li>
+<li><code>id: Optional[PyObjectId]</code> — aliased to <code>_id</code>, serialized to <code>str</code>.</li>
+<li><code>created_at: datetime</code> — defaults to <code>datetime.utcnow()</code>.</li>
+<li><code>updated_at: datetime</code> — defaults to <code>datetime.utcnow()</code>.</li>
+<li><code>Config.populate_by_name = True</code>, <code>arbitrary_types_allowed = True</code>, <code>json_encoders = {ObjectId: str}</code>.</li>
 </ul>
-<h3 id="2-basedocument">2. BaseDocument</h3>
-<p>Base model for all MongoDB documents. Provides:</p>
+<p><code>PyObjectId(ObjectId)</code> — Pydantic v2-compatible <code>ObjectId</code> that accepts <code>str</code> or <code>ObjectId</code> and validates with <code>ObjectId.is_valid</code>.</p>
+<hr />
+<h2 id="3-crudmixint">3. CRUDMixin[T]</h2>
+<p>Generic CRUD over a Motor collection. The building block of all repositories.</p>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Signature</th>
+<th>Notes</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>create</code></td>
+<td><code>async (data: T) -&gt; T</code></td>
+<td>Dumps model (excludes <code>id</code>, <code>None</code>), stamps <code>created_at</code>/<code>updated_at</code>, inserts, returns model with assigned <code>_id</code>.</td>
+</tr>
+<tr>
+<td><code>get_by_id</code></td>
+<td><code>async (id: str \| ObjectId) -&gt; Optional[T]</code></td>
+<td><code>str</code> is accepted and converted to <code>ObjectId</code>.</td>
+</tr>
+<tr>
+<td><code>get_many</code></td>
+<td><code>async (filter: dict \| None = None, skip: int = 0, limit: int = 100, sort: list[tuple] \| None = None) -&gt; list[T]</code></td>
+<td>Cursor <code>.skip().limit().sort(...)</code> then <code>to_list(limit)</code>. <code>limit=0</code> disables the limit clause.</td>
+</tr>
+<tr>
+<td><code>update</code></td>
+<td><code>async (id, data: dict[str, Any]) -&gt; Optional[T]</code></td>
+<td><code>$set</code> + refreshed <code>updated_at</code> via <code>find_one_and_update</code>.</td>
+</tr>
+<tr>
+<td><code>patch</code></td>
+<td><code>async (id, data: dict[str, Any]) -&gt; Optional[T]</code></td>
+<td>Same as <code>update</code> but intended for REST PATCH semantics.</td>
+</tr>
+<tr>
+<td><code>delete</code></td>
+<td><code>async (id) -&gt; bool</code></td>
+<td>True if a document was deleted.</td>
+</tr>
+<tr>
+<td><code>count</code></td>
+<td><code>async (filter: dict \| None = None) -&gt; int</code></td>
+<td><code>count_documents</code>.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="4-baserepositoryt">4. BaseRepository[T]</h2>
+<p><code>BaseRepository(collection_name: str, model: type[T])</code> — resolves the collection from <code>MongoConnectionManager.get_database()[collection_name]</code>. <strong>Requires an active connection at construction time.</strong> Provides everything in <code>CRUDMixin</code> plus <code>collection_name</code>.</p>
+<hr />
+<h2 id="5-populatingrepositoryt">5. PopulatingRepository[T]</h2>
+<p><code>PopulatingRepository(collection_name, model, population_engine: PopulationEngine | None = None, populate_rules: list[PopulateRule] | None = None)</code>.</p>
 <ul>
-<li><code>id</code> (aliased to <code>_id</code>) - ObjectId</li>
-<li><code>created_at</code> - Auto-generated timestamp</li>
-<li><code>updated_at</code> - Auto-updated timestamp</li>
+<li><code>set_population_engine(engine)</code> / <code>set_populate_rules(rules)</code> — swap engine/rules at runtime.</li>
+<li><code>data_to_model</code> hooks <code>_populate</code> — <code>get_by_id</code>/<code>get_many</code> return fully populated models.</li>
+<li><code>_depopulate(document)</code> — collapses populated FK fields back to <code>ObjectId</code> before <code>create</code>/<code>update</code>.</li>
+<li><code>create</code> / <code>update</code> accept a <strong>model</strong> <code>T</code> (not a dict) so depopulation can run.</li>
+<li><code>patch</code> blocks FK fields — raises <code>ValueError("Cannot patch FK fields via patch(): ... Use update() to change FK fields.")</code>.</li>
 </ul>
-<h3 id="3-baserepositoryt">3. BaseRepository[T]</h3>
-<p>Generic repository with CRUD operations:</p>
+<blockquote>
+<p><strong>Populate semantics (important):</strong> a <code>PopulateRule</code> names a field that holds either an <code>ObjectId</code> or a <code>list[ObjectId]</code> <strong>and is the same field that gets replaced</strong> with the resolved document(s). There is no separate "ref field" vs "target field". See <a href="../03_use_cases/08_population/">use case 08</a>.</p>
+</blockquote>
+<hr />
+<h2 id="6-transactionmanager">6. TransactionManager</h2>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Signature</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>start_session</code></td>
+<td><code>async ctx manager (**kwargs) -&gt; AsyncIOMotorClientSession</code></td>
+<td>Yields a session with an active transaction. Pass <code>session=</code> to every collection call inside.</td>
+</tr>
+<tr>
+<td><code>execute_transaction</code></td>
+<td><code>async (operations: list[Callable[[session], Awaitable[Any]]], **kwargs) -&gt; list[Any]</code></td>
+<td>Runs each op inside one transaction and returns results in order; any exception aborts the transaction and propagates.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="7-modelregistry">7. ModelRegistry</h2>
+<p>Centralized models, indexes, and cache lifecycle for multi-collection services.</p>
+<table>
+<thead>
+<tr>
+<th>Method</th>
+<th>Signature</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>register</code></td>
+<td><code>(collection_name: str, model: type[BaseDocument], indexes: list[Any] \| None = None)</code></td>
+<td>Records model + index specs. Index specs are passed <strong>as-is</strong> to pymongo <code>create_index</code> — single tuples, compound lists, or dicts with <code>keys</code>/<code>options</code>.</td>
+</tr>
+<tr>
+<td><code>initialize_all</code></td>
+<td><code>async (db: AsyncIOMotorDatabase \| None = None) -&gt; None</code></td>
+<td><code>create_index</code> per registered spec (idempotent). Uses the manager database if <code>db</code> omitted.</td>
+</tr>
+<tr>
+<td><code>get_model</code></td>
+<td><code>(collection_name) -&gt; type[BaseDocument]</code></td>
+<td>Raises <code>KeyError</code> if unregistered.</td>
+</tr>
+<tr>
+<td><code>list_collections</code></td>
+<td><code>() -&gt; list[str]</code></td>
+<td>Registered collection names.</td>
+</tr>
+<tr>
+<td><code>set_cache_backend</code></td>
+<td><code>(backend: CacheBackend) -&gt; None</code></td>
+<td>Register the single shared backend.</td>
+</tr>
+<tr>
+<td><code>initialize_cache</code></td>
+<td><code>async () -&gt; None</code></td>
+<td>Starts the backend (background TTL cleanup) — raises <code>RuntimeError</code> if no backend registered.</td>
+</tr>
+<tr>
+<td><code>shutdown_cache</code></td>
+<td><code>async () -&gt; None</code></td>
+<td>Stops the backend cleanly and clears it.</td>
+</tr>
+<tr>
+<td><code>get_cache_backend</code></td>
+<td><code>() -&gt; Optional[CacheBackend]</code></td>
+<td>Current backend, if any.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="8-cache-layer">8. Cache Layer</h2>
+<h3 id="81-cachebackend-abstract">8.1 CacheBackend (abstract)</h3>
+<p>Async interface: <code>get(key) -&gt; Optional[bytes]</code>, <code>set(key, value: bytes, ttl | None)</code>, <code>delete(key)</code>, <code>exists(key)</code>, <code>clear_pattern(pattern)</code>, <code>get_stats() -&gt; CacheStats</code>, <code>initialize()</code>, <code>shutdown()</code>. Values are <strong>bytes</strong> (JSON-encoded).</p>
+<h3 id="82-cachestats">8.2 CacheStats</h3>
+<p>Dataclass: <code>hits</code>, <code>misses</code>, <code>sets</code>, <code>deletes</code>, <code>current_size</code>, <code>max_size</code>.</p>
+<h3 id="83-cacheconfig">8.3 CacheConfig</h3>
+<p>Dataclass: <code>enabled: bool = True</code>, <code>backend: Literal["memory", "redis"] = "memory"</code>, <code>redis_client</code>, <code>default_ttl: int = 300</code>, <code>max_entries: int = 10000</code>, <code>key_prefix: str = ""</code>, <code>cleanup_interval: int = 60</code>. Raises <code>ValueError</code> if <code>backend="redis"</code> without a client, and <code>ImportError</code> if <code>redis</code> is not installed.</p>
+<h3 id="84-inmemorycachebackend">8.4 InMemoryCacheBackend</h3>
+<p><code>InMemoryCacheBackend(max_entries=10000, default_ttl=300, cleanup_interval=60)</code> — LRU <code>OrderedDict</code> + TTL heap; <code>initialize()</code> spawns the periodic cleanup task (TTL 0 expires immediately).</p>
+<h3 id="85-rediscachebackend">8.5 RedisCacheBackend</h3>
+<p><code>RedisCacheBackend(redis_client, key_prefix="", default_ttl=300)</code> — <code>setex</code> storage, SCAN-based <code>clear_pattern</code>, and <code>publish_invalidate(key)</code> for cross-service invalidation on <code>delete</code> via the <code>mongo_ops:cache:invalidate</code> channel.</p>
+<h3 id="86-cachedbaserepositoryt">8.6 CachedBaseRepository[T]</h3>
+<p><code>CachedBaseRepository(collection_name, model, cache_backend: CacheBackend, config: CacheConfig | None = None)</code>.</p>
 <ul>
-<li><code>create(data: T) -&gt; T</code></li>
-<li><code>get_by_id(id: str | ObjectId) -&gt; Optional[T]</code></li>
-<li><code>get_many(filter, skip, limit, sort) -&gt; List[T]</code></li>
-<li><code>update(id, data: Dict) -&gt; Optional[T]</code></li>
-<li><code>delete(id) -&gt; bool</code></li>
-<li><code>count(filter) -&gt; int</code></li>
-</ul>
-<h3 id="4-transactionmanager">4. TransactionManager</h3>
-<p>Handles multi-document transactions:</p>
-<ul>
-<li><code>start_session()</code> - Context manager for transactions</li>
-<li><code>execute_transaction(operations)</code> - Execute multiple operations atomically</li>
-</ul>
-<h3 id="5-modelregistry">5. ModelRegistry</h3>
-<p>Register and initialize models:</p>
-<ul>
-<li><code>register(collection_name, model, indexes)</code> - Register a model</li>
-<li><code>initialize_all()</code> - Create all indexes</li>
-<li><code>get_model(collection_name)</code> - Get registered model</li>
-<li><code>list_collections()</code> - List all registered collections</li>
+<li>Cache keys are <code>"{key_prefix}{id}"</code> (prefix defaults to <code>"{collection_name}:"</code>).</li>
+<li><code>get_by_id</code> — cache-first; cache miss reads DB and stores <code>model_dump(by_alias=True)</code> (JSON-encoded) for <code>default_ttl</code>. Honors <code>config.enabled=False</code> (bypass).</li>
+<li><code>create</code> — inserts then caches the result.</li>
+<li><code>update</code>/<code>delete</code> — refresh or remove the cache entry.</li>
+<li><code>warm_cache(ids) -&gt; int</code> — prefetch a list of IDs, returns count warmed.</li>
+<li><code>invalidate_cache(id)</code> — manual eviction.</li>
 </ul>
 <hr />
-<h3 id="6-cache-backend">6. Cache Backend</h3>
-<h4 id="61-cachebackend-abstract">6.1 CacheBackend (abstract)</h4>
+<h2 id="9-population-layer">9. Population Layer</h2>
+<h3 id="91-populaterule">9.1 PopulateRule</h3>
+<p>Dataclass:</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nd">@dataclass</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="k">class</span><span class="w"> </span><span class="nc">PopulateRule</span><span class="p">:</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>    <span class="n">field_name</span><span class="p">:</span> <span class="nb">str</span>          <span class="c1"># field holding the ObjectId / list[ObjectId]; replaced in-place with the resolved doc(s)</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>    <span class="n">collection_name</span><span class="p">:</span> <span class="nb">str</span>     <span class="c1"># collection the references point at</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="n">nested_rules</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">PopulateRule</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="n">max_depth</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="nb">filter</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>      <span class="c1"># DECLARED but NOT yet applied by the engine</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">projection</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># DECLARED but NOT yet applied by the engine</span>
+</code></pre></div>
+<blockquote>
+<p>⚠️ <code>filter</code> and <code>projection</code> are accepted but currently <strong>ignored</strong> by <code>PopulationEngine</code> — do not rely on them yet.</p>
+</blockquote>
+<h3 id="92-populationengine">9.2 PopulationEngine</h3>
+<p><code>PopulationEngine(repos: dict[str, Any], global_max_depth: int = 10)</code> — <code>repos</code> maps <code>collection_name</code> → repository.</p>
 <ul>
-<li>Defines the async interface for cache operations: <code>get</code>, <code>set</code>, <code>delete</code>, <code>exists</code>, <code>clear_pattern</code>, <code>get_stats</code>, <code>initialize</code>, <code>shutdown</code>.</li>
-<li>Provides <code>CacheStats</code> for hit/miss/size metrics and <code>CircularReferenceError</code> for cycle detection.</li>
-</ul>
-<h4 id="62-cacheconfig">6.2 CacheConfig</h4>
-<ul>
-<li>Dataclass to configure caching (<code>enabled</code>, <code>backend</code>, <code>redis_client</code>, <code>default_ttl</code>, <code>max_entries</code>, <code>key_prefix</code>, <code>cleanup_interval</code>).</li>
-</ul>
-<h4 id="63-inmemorycachebackend">6.3 InMemoryCacheBackend</h4>
-<ul>
-<li>In‑process cache using an LRU <code>OrderedDict</code> and a TTL heap.</li>
-<li>Background task periodically evicts expired entries.</li>
-</ul>
-<h4 id="64-rediscachebackend">6.4 RedisCacheBackend</h4>
-<ul>
-<li>Distributed cache based on <code>redis.asyncio</code>.</li>
-<li>JSON serialisation, optional pub/sub invalidation.</li>
-</ul>
-<h4 id="65-cachedbaserepositoryt">6.5 CachedBaseRepository[T]</h4>
-<ul>
-<li>Extends <code>BaseRepository</code> with transparent ID‑based caching.</li>
-<li>Methods:</li>
-<li><code>get_by_id</code> – cache‑first lookup.</li>
-<li><code>create</code> – stores newly created doc in cache.</li>
-<li><code>update</code> / <code>delete</code> – invalidate or refresh cache.</li>
-<li><code>warm_cache(ids)</code> – pre‑load a list of IDs.</li>
-<li><code>invalidate_cache(id)</code> – manual invalidation.</li>
+<li><code>register_repo(collection_name, repo)</code> — add repositories at runtime.</li>
+<li><code>populate(document, rules, depth=0)</code> — resolves refs recursively, replacing <code>field_name</code> in place; raises <code>CircularReferenceError(collection, doc_id, path)</code> when a <code>(Class, id)</code> pair is revisited.</li>
+<li><code>depopulate(document, rules)</code> — collapse populated docs back to IDs (for storage).</li>
+<li><code>global_max_depth</code> caps recursion; per-rule <code>max_depth</code> bounds a rule's descent.</li>
 </ul>
+<h3 id="93-circularreferenceerrorvalueerror">9.3 CircularReferenceError(ValueError)</h3>
+<p>Holds <code>collection</code>, <code>doc_id</code>, and the visited <code>path</code> for debugging cycle messages.</p>
 <hr />
-<h3 id="7-population-engine">7. Population Engine</h3>
-<h4 id="71-populaterule">7.1 PopulateRule</h4>
+<h2 id="related">Related</h2>
 <ul>
-<li>Dataclass defining a population rule: <code>field_name</code>, <code>collection_name</code>, <code>ref_field</code>, optional <code>nested_rules</code>, <code>max_depth</code>, <code>filter</code>, <code>projection</code>.</li>
+<li><a href="../03_use_cases/01_basic_crud/">Use case 01 – Basic CRUD</a> · <a href="../03_use_cases/07_caching/">07 – Caching</a> · <a href="../03_use_cases/08_population/">08 – Population</a></li>
 </ul>
-<h4 id="72-populationengine">7.2 PopulationEngine</h4>
-<ul>
-<li>Recursively resolves references according to <code>PopulateRule</code> list.</li>
-<li>Detects circular references and raises <code>CircularReferenceError</code>.</li>
-<li>Supports per‑rule depth limits, filters and projections.</li>
-</ul>
-<h4 id="73-populatingrepositoryt">7.3 PopulatingRepository[T]</h4>
-<ul>
-<li>Extends <code>BaseRepository</code> to automatically populate related documents.</li>
-<li>Accepts an optional <code>PopulationEngine</code> and a list of <code>PopulateRule</code>.</li>
-<li>Provides <code>_populate</code> and <code>_depopulate</code> helpers used in <code>get_by_id</code> and elsewhere.</li>
-</ul>
-<hr />
 
 
 
diff --git a/mongo-ops/03_use_cases/01_basic_crud/index.html b/mongo-ops/03_use_cases/01_basic_crud/index.html
index 3cae0e0..088d805 100644
--- a/mongo-ops/03_use_cases/01_basic_crud/index.html
+++ b/mongo-ops/03_use_cases/01_basic_crud/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -529,6 +529,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -561,6 +563,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -569,9 +573,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-1-basic-fastapi-crud-api" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 1: Basic FastAPI CRUD API
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,114 +1035,144 @@
 
 
 
-  <h1>Basic CRUD</h1>
-
-<h3 id="use-case-1-basic-fastapi-crud-api">Use Case 1: Basic FastAPI CRUD API</h3>
-<p><strong>Scenario:</strong> Create a simple user management API with CRUD operations.</p>
+<h1 id="use-case-1-basic-fastapi-crud-api">Use Case 1: Basic FastAPI CRUD API</h1>
+<p><strong>Scenario:</strong> A simple user management API with CRUD endpoints, index registration, and a correct connection lifecycle.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>MongoConnectionManager.lifespan</code></td>
+<td>Connect on startup, disconnect on shutdown.</td>
+</tr>
+<tr>
+<td><code>BaseRepository[User]</code></td>
+<td>Generic CRUD — no endpoint-level Mongo code.</td>
+</tr>
+<tr>
+<td><code>ModelRegistry.register</code></td>
+<td>Declares the <code>email</code> index; <code>initialize_all</code> creates it at startup.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
 <div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">Depends</span><span class="p">,</span> <span class="n">HTTPException</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">Field</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="n">MongoConnectionManager</span><span class="p">,</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="n">BaseDocument</span><span class="p">,</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">BaseRepository</span><span class="p">,</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">ModelRegistry</span><span class="p">,</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="p">)</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="c1"># Model Definition</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">is_active</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="c1"># Repository</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="c1"># Register the model only once</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">Depends</span><span class="p">,</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">Field</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># Model</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">is_active</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># Repository</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># Registration + index</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
 <a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a><span class="c1"># FastAPI Lifespan</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;Manage MongoDB connection during the app lifecycle.&quot;&quot;&quot;</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="p">):</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>        <span class="k">yield</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="c1"># Lifecycle</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="n">uri</span><span class="o">=</span><span class="n">os</span><span class="o">.</span><span class="n">getenv</span><span class="p">(</span><span class="s2">&quot;MONGO_URI&quot;</span><span class="p">,</span> <span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">),</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="p">):</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
 <a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a><span class="c1"># Dependency — created per request, after connect()</span>
 <a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a><span class="c1"># Dependency Injection</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="k">def</span><span class="w"> </span><span class="nf">get_user_repository</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n">UserRepository</span><span class="p">:</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;Dependency-injected repository for users.&quot;&quot;&quot;</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>    <span class="k">return</span> <span class="n">UserRepository</span><span class="p">()</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="c1"># Routes</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="c1"># ---------------------------</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">,</span> <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>    <span class="k">return</span> <span class="n">user</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">User</span><span class="p">])</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_users</span><span class="p">(</span>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>    <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
-<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>    <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">),</span>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="p">):</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="n">limit</span><span class="p">)</span>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>
-<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a><span class="nd">@app</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_user</span><span class="p">(</span>
-<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>    <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">),</span>
-<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a><span class="p">):</span>
-<a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">user_id</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="n">email</span><span class="p">})</span>
-<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
-<a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a>    <span class="k">return</span> <span class="n">user</span>
-<a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a>
-<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>
-<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a><span class="nd">@app</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">delete_user</span><span class="p">(</span>
-<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
-<a id="__codelineno-0-98" name="__codelineno-0-98" href="#__codelineno-0-98"></a>    <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">),</span>
-<a id="__codelineno-0-99" name="__codelineno-0-99" href="#__codelineno-0-99"></a><span class="p">):</span>
-<a id="__codelineno-0-100" name="__codelineno-0-100" href="#__codelineno-0-100"></a>    <span class="n">deleted</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
-<a id="__codelineno-0-101" name="__codelineno-0-101" href="#__codelineno-0-101"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">deleted</span><span class="p">:</span>
-<a id="__codelineno-0-102" name="__codelineno-0-102" href="#__codelineno-0-102"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-103" name="__codelineno-0-103" href="#__codelineno-0-103"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;User deleted successfully&quot;</span><span class="p">}</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a><span class="k">def</span><span class="w"> </span><span class="nf">get_user_repository</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="n">UserRepository</span><span class="p">:</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>    <span class="k">return</span> <span class="n">UserRepository</span><span class="p">()</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="c1"># Routes</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">,</span> <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>    <span class="k">return</span> <span class="n">user</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">User</span><span class="p">])</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_users</span><span class="p">(</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>    <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>    <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>    <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">),</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="p">):</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="n">limit</span><span class="p">)</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="nd">@app</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_user</span><span class="p">(</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span>
+<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>    <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">),</span>
+<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a><span class="p">):</span>
+<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">user_id</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="n">email</span><span class="p">})</span>
+<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
+<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>    <span class="k">return</span> <span class="n">user</span>
+<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a>
+<a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a>
+<a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a><span class="nd">@app</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">delete_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">repo</span><span class="p">:</span> <span class="n">UserRepository</span> <span class="o">=</span> <span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
+<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>    <span class="n">deleted</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
+<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">deleted</span><span class="p">:</span>
+<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;User deleted successfully&quot;</span><span class="p">}</span>
 </code></pre></div>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li><code>UserRepository()</code> is created <strong>inside the dependency</strong>, i.e., only after the lifespan has connected. Instantiating a repository at module import time raises <code>RuntimeError</code> because the database isn't connected yet.</li>
+<li><code>BaseRepository.update(id, {...})</code> takes a <strong>dict</strong>; only <code>PopulatingRepository.update</code> takes a model.</li>
+<li>Use <code>patch()</code> for REST PATCH semantics — it accepts a partial dict like <code>update</code>, but <code>PopulatingRepository</code> rejects FK fields.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../02_custom_repo/">02 – Custom repository</a> · <a href="../04_pagination/">04 – Pagination</a> · <a href="../../01_overview/">Overview</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/02_custom_repo/index.html b/mongo-ops/03_use_cases/02_custom_repo/index.html
index cf2480d..0a8de64 100644
--- a/mongo-ops/03_use_cases/02_custom_repo/index.html
+++ b/mongo-ops/03_use_cases/02_custom_repo/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -552,6 +552,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -584,6 +586,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -592,9 +596,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-2-custom-repository-with-business-logic" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 2: Custom Repository with Business Logic
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,81 +1035,127 @@
 
 
 
-  <h1>Custom Repo</h1>
-
-<h3 id="use-case-2-custom-repository-with-business-logic">Use Case 2: Custom Repository with Business Logic</h3>
-<p><strong>Scenario:</strong> E-commerce product catalog with custom search and filtering.</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">List</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">Field</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="k">class</span><span class="w"> </span><span class="nc">Product</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="n">description</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">price</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">gt</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">category</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">in_stock</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">quantity</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="mi">0</span><span class="p">,</span> <span class="n">ge</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">tags</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProductRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Product</span><span class="p">]):</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;products&quot;</span><span class="p">,</span> <span class="n">Product</span><span class="p">)</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_by_name</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Search products by name (case-insensitive)&quot;&quot;&quot;</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>        <span class="n">docs</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">({</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>            <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$regex&quot;</span><span class="p">:</span> <span class="n">query</span><span class="p">,</span> <span class="s2">&quot;$options&quot;</span><span class="p">:</span> <span class="s2">&quot;i&quot;</span><span class="p">}</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>        <span class="p">})</span><span class="o">.</span><span class="n">to_list</span><span class="p">(</span><span class="n">length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="k">return</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">doc</span><span class="p">)</span> <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">docs</span><span class="p">]</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_category</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">category</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">in_stock_only</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get products by category&quot;&quot;&quot;</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>        <span class="n">filter_query</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;category&quot;</span><span class="p">:</span> <span class="n">category</span><span class="p">}</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>        <span class="k">if</span> <span class="n">in_stock_only</span><span class="p">:</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>            <span class="n">filter_query</span><span class="p">[</span><span class="s2">&quot;in_stock&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="n">filter_query</span><span class="p">)</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_low_stock</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">threshold</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get products with low stock&quot;&quot;&quot;</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>            <span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$lt&quot;</span><span class="p">:</span> <span class="n">threshold</span><span class="p">},</span> <span class="s2">&quot;in_stock&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">}</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>        <span class="p">)</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_stock</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Update product stock (increment/decrement)&quot;&quot;&quot;</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one_and_update</span><span class="p">(</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>            <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">product_id</span><span class="p">)},</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>            <span class="p">{</span><span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="n">quantity_delta</span><span class="p">},</span> <span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()}},</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>            <span class="n">return_document</span><span class="o">=</span><span class="kc">True</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>        <span class="p">)</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">result</span><span class="p">)</span> <span class="k">if</span> <span class="n">result</span> <span class="k">else</span> <span class="kc">None</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="c1"># Usage in FastAPI</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">Query</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a><span class="n">product_repo</span> <span class="o">=</span> <span class="n">ProductRepository</span><span class="p">()</span>
+<h1 id="use-case-2-custom-repository-with-business-logic">Use Case 2: Custom Repository with Business Logic</h1>
+<p><strong>Scenario:</strong> An e-commerce product catalog needs search, filtering, and stock updates without Mongo leaking into routes.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>Repository methods</td>
+<td>Encapsulate queries (<code>$regex</code>, filters, <code>$inc</code>) behind domain methods.</td>
+</tr>
+<tr>
+<td><code>get_many</code></td>
+<td>Filtering + default pagination via the base repository.</td>
+</tr>
+<tr>
+<td>Direct <code>collection</code> access</td>
+<td>For operations with no base-repo helper (regex search, atomic <code>$inc</code>).</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span><span class="p">,</span> <span class="n">Query</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="c1"># Model</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">Product</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">description</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">price</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">category</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">in_stock</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">quantity</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="c1"># Repository</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProductRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Product</span><span class="p">]):</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;products&quot;</span><span class="p">,</span> <span class="n">Product</span><span class="p">)</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_by_name</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">query</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Case-insensitive name search.&quot;&quot;&quot;</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="n">docs</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find</span><span class="p">(</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>            <span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$regex&quot;</span><span class="p">:</span> <span class="n">query</span><span class="p">,</span> <span class="s2">&quot;$options&quot;</span><span class="p">:</span> <span class="s2">&quot;i&quot;</span><span class="p">}}</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>        <span class="p">)</span><span class="o">.</span><span class="n">to_list</span><span class="p">(</span><span class="n">length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>        <span class="k">return</span> <span class="p">[</span><span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">doc</span><span class="p">)</span> <span class="k">for</span> <span class="n">doc</span> <span class="ow">in</span> <span class="n">docs</span><span class="p">]</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_category</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">category</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">in_stock_only</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>        <span class="n">filter_query</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;category&quot;</span><span class="p">:</span> <span class="n">category</span><span class="p">}</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="k">if</span> <span class="n">in_stock_only</span><span class="p">:</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>            <span class="n">filter_query</span><span class="p">[</span><span class="s2">&quot;in_stock&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="n">filter_query</span><span class="p">)</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_low_stock</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">threshold</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">]:</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$lt&quot;</span><span class="p">:</span> <span class="n">threshold</span><span class="p">},</span> <span class="s2">&quot;in_stock&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_stock</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Product</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Atomically increment/decrement stock.&quot;&quot;&quot;</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one_and_update</span><span class="p">(</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">product_id</span><span class="p">)},</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="p">{</span><span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="n">quantity_delta</span><span class="p">},</span> <span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()}},</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="n">return_document</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="p">)</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">result</span><span class="p">)</span> <span class="k">if</span> <span class="n">result</span> <span class="k">else</span> <span class="kc">None</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>
 <a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/search&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_products</span><span class="p">(</span><span class="n">q</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">1</span><span class="p">)):</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">search_by_name</span><span class="p">(</span><span class="n">q</span><span class="p">)</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="n">product_repo</span> <span class="o">=</span> <span class="n">ProductRepository</span><span class="p">()</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>
 <a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/category/</span><span class="si">{category}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">products_by_category</span><span class="p">(</span><span class="n">category</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">in_stock</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">):</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">get_by_category</span><span class="p">(</span><span class="n">category</span><span class="p">,</span> <span class="n">in_stock</span><span class="p">)</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/search&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_products</span><span class="p">(</span><span class="n">q</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">1</span><span class="p">)):</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">search_by_name</span><span class="p">(</span><span class="n">q</span><span class="p">)</span>
 <a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/low-stock&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">low_stock_products</span><span class="p">(</span><span class="n">threshold</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">get_low_stock</span><span class="p">(</span><span class="n">threshold</span><span class="p">)</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="nd">@app</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="s2">&quot;/products/</span><span class="si">{product_id}</span><span class="s2">/stock&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_product_stock</span><span class="p">(</span><span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>    <span class="n">product</span> <span class="o">=</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">update_stock</span><span class="p">(</span><span class="n">product_id</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">)</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">product</span><span class="p">:</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Product not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>    <span class="k">return</span> <span class="n">product</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/category/</span><span class="si">{category}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">products_by_category</span><span class="p">(</span><span class="n">category</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">in_stock</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">):</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">get_by_category</span><span class="p">(</span><span class="n">category</span><span class="p">,</span> <span class="n">in_stock</span><span class="p">)</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/low-stock&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">Product</span><span class="p">])</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">low_stock_products</span><span class="p">(</span><span class="n">threshold</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">get_low_stock</span><span class="p">(</span><span class="n">threshold</span><span class="p">)</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a><span class="nd">@app</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="s2">&quot;/products/</span><span class="si">{product_id}</span><span class="s2">/stock&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_product_stock</span><span class="p">(</span><span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">:</span> <span class="nb">int</span><span class="p">):</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>    <span class="n">product</span> <span class="o">=</span> <span class="k">await</span> <span class="n">product_repo</span><span class="o">.</span><span class="n">update_stock</span><span class="p">(</span><span class="n">product_id</span><span class="p">,</span> <span class="n">quantity_delta</span><span class="p">)</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">product</span><span class="p">:</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Product not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="k">return</span> <span class="n">product</span>
 </code></pre></div>
+<blockquote>
+<p><strong>Note:</strong> this snippet omits the FastAPI <code>lifespan</code> connection wiring for brevity — copy it from <a href="../01_basic_crud/">use case 01</a> so <code>ProductRepository()</code> is created only after <code>MongoConnectionManager.connect()</code>.</p>
+</blockquote>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li>Methods that hit <code>self.collection</code> directly (regex search, <code>$inc</code>) <strong>bypass</strong> the caching and population layers. If a feature composes them — extend <code>CachedBaseRepository</code> or <code>PopulatingRepository</code> instead and add the domain methods there.</li>
+<li>Prefer <code>get_many(filter=...)</code> over raw <code>find</code> when you want pagination/sort defaults for free.</li>
+<li>Reuse <code>self.model(**doc)</code> to convert raw dicts to model instances consistently.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../01_basic_crud/">01 – Basic CRUD</a> · <a href="../04_pagination/">04 – Pagination</a> · <a href="../05_soft_deletes/">05 – Soft deletes</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/03_transactions/index.html b/mongo-ops/03_use_cases/03_transactions/index.html
index e2e6a46..96da10e 100644
--- a/mongo-ops/03_use_cases/03_transactions/index.html
+++ b/mongo-ops/03_use_cases/03_transactions/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -575,6 +575,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -607,6 +609,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -615,9 +619,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-3-transaction-support-for-multi-document-operations" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 3: Transaction Support for Multi-Document Operations
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,71 +1035,129 @@
 
 
 
-  <h1>Transactions</h1>
-
-<h3 id="use-case-3-transaction-support-for-multi-document-operations">Use Case 3: Transaction Support for Multi-Document Operations</h3>
-<p><strong>Scenario:</strong> Order processing system that updates inventory and creates order atomically.</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">TransactionManager</span>
+<h1 id="use-case-3-transaction-support-for-multi-document-operations">Use Case 3: Transaction Support for Multi-Document Operations</h1>
+<p><strong>Scenario:</strong> Order processing must update inventory and create an order <strong>atomically</strong>. Any failure rolls both back.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>TransactionManager.start_session</code></td>
+<td>Async context manager yielding a session with an active transaction.</td>
+</tr>
+<tr>
+<td><code>session=</code> kwarg</td>
+<td>Pass to every <code>insert_one</code> / <code>update_one</code> / <code>find_one</code> inside the block.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
 <a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">List</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">Field</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="k">class</span><span class="w"> </span><span class="nc">Order</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">items</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">dict</span><span class="p">]</span>  <span class="c1"># [{&quot;product_id&quot;: &quot;...&quot;, &quot;quantity&quot;: 2}]</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">total_amount</span><span class="p">:</span> <span class="nb">float</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;pending&quot;</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">OrderRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Order</span><span class="p">]):</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;orders&quot;</span><span class="p">,</span> <span class="n">Order</span><span class="p">)</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="n">TransactionManager</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">Order</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">items</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">dict</span><span class="p">]</span>  <span class="c1"># [{&quot;product_id&quot;: &quot;...&quot;, &quot;quantity&quot;: 2}]</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">total_amount</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;pending&quot;</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
 <a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="k">class</span><span class="w"> </span><span class="nc">OrderService</span><span class="p">:</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">order_repo</span><span class="p">:</span> <span class="n">OrderRepository</span><span class="p">,</span> <span class="n">product_repo</span><span class="p">:</span> <span class="n">ProductRepository</span><span class="p">):</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">order_repo</span> <span class="o">=</span> <span class="n">order_repo</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">product_repo</span> <span class="o">=</span> <span class="n">product_repo</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="k">class</span><span class="w"> </span><span class="nc">Inventory</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">product_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">quantity</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
 <a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order_with_inventory_update</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Order</span><span class="p">:</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Create order and update inventory atomically&quot;&quot;&quot;</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>        <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order_transaction</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>            <span class="c1"># Insert order</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>            <span class="n">order_doc</span> <span class="o">=</span> <span class="n">order</span><span class="o">.</span><span class="n">model_dump</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">},</span> <span class="n">exclude_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>            <span class="n">order_doc</span><span class="p">[</span><span class="s2">&quot;created_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>            <span class="n">order_doc</span><span class="p">[</span><span class="s2">&quot;updated_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>            <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">order_doc</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="k">class</span><span class="w"> </span><span class="nc">OrderRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Order</span><span class="p">]):</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;orders&quot;</span><span class="p">,</span> <span class="n">Order</span><span class="p">)</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="k">class</span><span class="w"> </span><span class="nc">InventoryRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Inventory</span><span class="p">]):</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;inventory&quot;</span><span class="p">,</span> <span class="n">Inventory</span><span class="p">)</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
 <a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>            <span class="c1"># Update inventory for each item</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>            <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="p">:</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>                <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">product_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>                    <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;product_id&quot;</span><span class="p">])},</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>                    <span class="p">{</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>                        <span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="o">-</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;quantity&quot;</span><span class="p">]},</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>                        <span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()}</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>                    <span class="p">},</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>                    <span class="n">session</span><span class="o">=</span><span class="n">session</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>                <span class="p">)</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order_with_inventory_update</span><span class="p">(</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">,</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="n">order_repo</span><span class="p">:</span> <span class="n">OrderRepository</span><span class="p">,</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">inv_repo</span><span class="p">:</span> <span class="n">InventoryRepository</span><span class="p">,</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Order</span><span class="p">:</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">insert_order</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="n">doc</span> <span class="o">=</span> <span class="n">order</span><span class="o">.</span><span class="n">model_dump</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">},</span> <span class="n">exclude_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;created_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;updated_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">result</span><span class="o">.</span><span class="n">inserted_id</span><span class="p">},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
 <a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>            <span class="c1"># Fetch created order</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>            <span class="n">created</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">(</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>                <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">result</span><span class="o">.</span><span class="n">inserted_id</span><span class="p">},</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>                <span class="n">session</span><span class="o">=</span><span class="n">session</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="p">)</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="k">return</span> <span class="n">Order</span><span class="p">(</span><span class="o">**</span><span class="n">created</span><span class="p">)</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="c1"># Execute in transaction</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>        <span class="k">async</span> <span class="k">with</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">start_session</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>            <span class="k">return</span> <span class="k">await</span> <span class="n">create_order_transaction</span><span class="p">(</span><span class="n">session</span><span class="p">)</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="c1"># Usage in FastAPI</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/orders/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">):</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>    <span class="n">order_service</span> <span class="o">=</span> <span class="n">OrderService</span><span class="p">(</span><span class="n">order_repo</span><span class="p">,</span> <span class="n">product_repo</span><span class="p">)</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>    <span class="k">try</span><span class="p">:</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">order_service</span><span class="o">.</span><span class="n">create_order_with_inventory_update</span><span class="p">(</span><span class="n">order</span><span class="p">)</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_inventory</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="p">:</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="k">await</span> <span class="n">inv_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>                <span class="p">{</span><span class="s2">&quot;product_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;product_id&quot;</span><span class="p">])},</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>                <span class="p">{</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>                    <span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="o">-</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;quantity&quot;</span><span class="p">]},</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>                    <span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()},</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>                <span class="p">},</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>                <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>            <span class="p">)</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>        <span class="k">return</span> <span class="kc">None</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">start_session</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>        <span class="n">created</span> <span class="o">=</span> <span class="k">await</span> <span class="n">insert_order</span><span class="p">(</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="k">await</span> <span class="n">update_inventory</span><span class="p">(</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="k">return</span> <span class="n">Order</span><span class="p">(</span><span class="o">**</span><span class="n">created</span><span class="p">)</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="c1"># FastAPI wiring</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="n">order_repo</span> <span class="o">=</span> <span class="n">OrderRepository</span><span class="p">()</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="n">inv_repo</span> <span class="o">=</span> <span class="n">InventoryRepository</span><span class="p">()</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;shop&quot;</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>    <span class="p">):</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a><span class="n">app</span><span class="o">.</span><span class="n">lifespan</span> <span class="o">=</span> <span class="n">lifespan</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/orders/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">):</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="k">try</span><span class="p">:</span>
+<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">create_order_with_inventory_update</span><span class="p">(</span><span class="n">order</span><span class="p">,</span> <span class="n">order_repo</span><span class="p">,</span> <span class="n">inv_repo</span><span class="p">)</span>
+<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
+<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="nb">str</span><span class="p">(</span><span class="n">exc</span><span class="p">))</span>
 </code></pre></div>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li>Repositories are created <strong>inside</strong> the lifespan (or a dependency) so the database is connected — see the note in <a href="../01_basic_crud/">use case 01</a>.</li>
+<li>Every operation inside the transaction context must receive <code>session=&lt;session&gt;</code> — a missing session silently runs outside the transaction.</li>
+<li>MongoDB transactions require a replica set (or the local standalone test server that emulates one).</li>
+<li>For a list-of-operations style, see <code>TransactionManager.execute_transaction</code> in <a href="../12_transaction_helper/">use case 12</a>.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../06_multi_model/">06 – Multi-model</a> · <a href="../12_transaction_helper/">12 – Transaction helper</a> · <a href="../../06_error_handling/">Error Handling</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/04_pagination/index.html b/mongo-ops/03_use_cases/04_pagination/index.html
index 5b4b27a..f274209 100644
--- a/mongo-ops/03_use_cases/04_pagination/index.html
+++ b/mongo-ops/03_use_cases/04_pagination/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -598,6 +598,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -630,6 +632,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -638,9 +642,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-4-pagination-filtering" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 4: Pagination &amp; Filtering
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,107 +1035,147 @@
 
 
 
-  <h1>Pagination</h1>
-
-<h3 id="use-case-4-pagination-filtering">Use Case 4: Pagination &amp; Filtering</h3>
-<p><strong>Scenario:</strong> Blog post API with pagination and filtering.</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span><span class="p">,</span> <span class="n">Field</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">List</span><span class="p">,</span> <span class="n">Optional</span><span class="p">,</span> <span class="n">Generic</span><span class="p">,</span> <span class="n">TypeVar</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="n">T</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s2">&quot;T&quot;</span><span class="p">)</span>
+<h1 id="use-case-4-pagination-filtering">Use Case 4: Pagination &amp; Filtering</h1>
+<p><strong>Scenario:</strong> A blog post API lists posts with page metadata, filtering, and sorting.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>BaseRepository.get_many</code></td>
+<td><code>filter</code>, <code>skip</code>, <code>limit</code>, <code>sort</code> in one call.</td>
+</tr>
+<tr>
+<td><code>BaseRepository.count</code></td>
+<td>Total matching documents for page metadata.</td>
+</tr>
+<tr>
+<td><code>PaginatedResponse</code></td>
+<td>Reusable generic response wrapper.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Generic</span><span class="p">,</span> <span class="n">TypeVar</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">Query</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseModel</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
 <a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">PaginatedResponse</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">,</span> <span class="n">Generic</span><span class="p">[</span><span class="n">T</span><span class="p">]):</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">items</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="n">T</span><span class="p">]</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">total</span><span class="p">:</span> <span class="nb">int</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">page</span><span class="p">:</span> <span class="nb">int</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">total_pages</span><span class="p">:</span> <span class="nb">int</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">has_next</span><span class="p">:</span> <span class="nb">bool</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">has_prev</span><span class="p">:</span> <span class="nb">bool</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPost</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">published</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">tags</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">views</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPostRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]):</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;blog_posts&quot;</span><span class="p">,</span> <span class="n">BlogPost</span><span class="p">)</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="n">T</span> <span class="o">=</span> <span class="n">TypeVar</span><span class="p">(</span><span class="s2">&quot;T&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="k">class</span><span class="w"> </span><span class="nc">PaginatedResponse</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">,</span> <span class="n">Generic</span><span class="p">[</span><span class="n">T</span><span class="p">]):</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">items</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">T</span><span class="p">]</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">total</span><span class="p">:</span> <span class="nb">int</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">page</span><span class="p">:</span> <span class="nb">int</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">total_pages</span><span class="p">:</span> <span class="nb">int</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">has_next</span><span class="p">:</span> <span class="nb">bool</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">has_prev</span><span class="p">:</span> <span class="nb">bool</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPost</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="n">published</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>    <span class="n">views</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
 <a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">paginate</span><span class="p">(</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>        <span class="bp">self</span><span class="p">,</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>        <span class="n">page</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>        <span class="n">filter_dict</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">dict</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="n">sort_by</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;created_at&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="n">sort_order</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">PaginatedResponse</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]:</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get paginated blog posts&quot;&quot;&quot;</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="n">filter_dict</span> <span class="o">=</span> <span class="n">filter_dict</span> <span class="ow">or</span> <span class="p">{}</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="n">skip</span> <span class="o">=</span> <span class="p">(</span><span class="n">page</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">*</span> <span class="n">page_size</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="c1"># Get total count</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="n">total</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">filter_dict</span><span class="p">)</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="c1"># Get items</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPostRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]):</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;blog_posts&quot;</span><span class="p">,</span> <span class="n">BlogPost</span><span class="p">)</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">paginate</span><span class="p">(</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="bp">self</span><span class="p">,</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="n">page</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>        <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="n">filter_dict</span><span class="p">:</span> <span class="nb">dict</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="n">sort_by</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;created_at&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="n">sort_order</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">PaginatedResponse</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]:</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="n">filter_dict</span> <span class="o">=</span> <span class="n">filter_dict</span> <span class="ow">or</span> <span class="p">{}</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="n">skip</span> <span class="o">=</span> <span class="p">(</span><span class="n">page</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">*</span> <span class="n">page_size</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="n">total</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="n">filter_dict</span><span class="p">)</span>
 <a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>        <span class="n">items</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span>
 <a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>            <span class="nb">filter</span><span class="o">=</span><span class="n">filter_dict</span><span class="p">,</span>
 <a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span>
 <a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="n">limit</span><span class="o">=</span><span class="n">page_size</span><span class="p">,</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="n">sort</span><span class="o">=</span><span class="p">[(</span><span class="n">sort_by</span><span class="p">,</span> <span class="n">sort_order</span><span class="p">)]</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="n">sort</span><span class="o">=</span><span class="p">[(</span><span class="n">sort_by</span><span class="p">,</span> <span class="n">sort_order</span><span class="p">)],</span>
 <a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="p">)</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>        <span class="n">total_pages</span> <span class="o">=</span> <span class="p">(</span><span class="n">total</span> <span class="o">+</span> <span class="n">page_size</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">//</span> <span class="n">page_size</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>        <span class="k">return</span> <span class="n">PaginatedResponse</span><span class="p">(</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>            <span class="n">items</span><span class="o">=</span><span class="n">items</span><span class="p">,</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>            <span class="n">total</span><span class="o">=</span><span class="n">total</span><span class="p">,</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>            <span class="n">page</span><span class="o">=</span><span class="n">page</span><span class="p">,</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>            <span class="n">page_size</span><span class="o">=</span><span class="n">page_size</span><span class="p">,</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>            <span class="n">total_pages</span><span class="o">=</span><span class="n">total_pages</span><span class="p">,</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>            <span class="n">has_next</span><span class="o">=</span><span class="n">page</span> <span class="o">&lt;</span> <span class="n">total_pages</span><span class="p">,</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>            <span class="n">has_prev</span><span class="o">=</span><span class="n">page</span> <span class="o">&gt;</span> <span class="mi">1</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>        <span class="p">)</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_author</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">published_only</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">):</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get posts by author&quot;&quot;&quot;</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>        <span class="n">filter_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;author_id&quot;</span><span class="p">:</span> <span class="n">author_id</span><span class="p">}</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>        <span class="k">if</span> <span class="n">published_only</span><span class="p">:</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>            <span class="n">filter_dict</span><span class="p">[</span><span class="s2">&quot;published&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="n">filter_dict</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>        <span class="n">total_pages</span> <span class="o">=</span> <span class="p">(</span><span class="n">total</span> <span class="o">+</span> <span class="n">page_size</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">//</span> <span class="n">page_size</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>        <span class="k">return</span> <span class="n">PaginatedResponse</span><span class="p">(</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>            <span class="n">items</span><span class="o">=</span><span class="n">items</span><span class="p">,</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>            <span class="n">total</span><span class="o">=</span><span class="n">total</span><span class="p">,</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>            <span class="n">page</span><span class="o">=</span><span class="n">page</span><span class="p">,</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>            <span class="n">page_size</span><span class="o">=</span><span class="n">page_size</span><span class="p">,</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>            <span class="n">total_pages</span><span class="o">=</span><span class="n">total_pages</span><span class="p">,</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>            <span class="n">has_next</span><span class="o">=</span><span class="n">page</span> <span class="o">&lt;</span> <span class="n">total_pages</span><span class="p">,</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>            <span class="n">has_prev</span><span class="o">=</span><span class="n">page</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">,</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="p">)</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_author</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">published_only</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]:</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>        <span class="n">filter_dict</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;author_id&quot;</span><span class="p">:</span> <span class="n">author_id</span><span class="p">}</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>        <span class="k">if</span> <span class="n">published_only</span><span class="p">:</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>            <span class="n">filter_dict</span><span class="p">[</span><span class="s2">&quot;published&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="kc">True</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="n">filter_dict</span><span class="p">,</span> <span class="n">sort</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_by_tags</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]:</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$in&quot;</span><span class="p">:</span> <span class="n">tags</span><span class="p">},</span> <span class="s2">&quot;published&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
 <a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">search_by_tags</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">tags</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">List</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">]:</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Search posts by tags&quot;&quot;&quot;</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;tags&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$in&quot;</span><span class="p">:</span> <span class="n">tags</span><span class="p">},</span> <span class="s2">&quot;published&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">})</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a><span class="n">blog_repo</span> <span class="o">=</span> <span class="n">BlogPostRepository</span><span class="p">()</span>
 <a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="c1"># Usage in FastAPI</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>
 <a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/posts/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">PaginatedResponse</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">])</span>
 <a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_posts</span><span class="p">(</span>
 <a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="n">page</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span>
 <a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>    <span class="n">page_size</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">,</span>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>    <span class="n">published</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">bool</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>    <span class="n">published</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
 <a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="p">):</span>
 <a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="n">filter_dict</span> <span class="o">=</span> <span class="p">{}</span>
 <a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>    <span class="k">if</span> <span class="n">published</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
 <a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>        <span class="n">filter_dict</span><span class="p">[</span><span class="s2">&quot;published&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">published</span>
 <a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>    <span class="k">if</span> <span class="n">author_id</span><span class="p">:</span>
 <a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>        <span class="n">filter_dict</span><span class="p">[</span><span class="s2">&quot;author_id&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">author_id</span>
-<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>
-<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">blog_repo</span><span class="o">.</span><span class="n">paginate</span><span class="p">(</span><span class="n">page</span><span class="p">,</span> <span class="n">page_size</span><span class="p">,</span> <span class="n">filter_dict</span><span class="p">)</span>
+<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">blog_repo</span><span class="o">.</span><span class="n">paginate</span><span class="p">(</span><span class="n">page</span><span class="p">,</span> <span class="n">page_size</span><span class="p">,</span> <span class="n">filter_dict</span><span class="p">)</span>
+<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a>
 <a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>
-<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/posts/author/</span><span class="si">{author_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">])</span>
+<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/posts/author/</span><span class="si">{author_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">])</span>
 <a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">posts_by_author</span><span class="p">(</span><span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">published</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span><span class="p">):</span>
 <a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">blog_repo</span><span class="o">.</span><span class="n">get_by_author</span><span class="p">(</span><span class="n">author_id</span><span class="p">,</span> <span class="n">published</span><span class="p">)</span>
 <a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a>
-<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/posts/tags&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">])</span>
-<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">posts_by_tags</span><span class="p">(</span><span class="n">tags</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">)):</span>
-<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">blog_repo</span><span class="o">.</span><span class="n">search_by_tags</span><span class="p">(</span><span class="n">tags</span><span class="p">)</span>
+<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>
+<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/posts/tags&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">BlogPost</span><span class="p">])</span>
+<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">posts_by_tags</span><span class="p">(</span><span class="n">tags</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="n">Query</span><span class="p">(</span><span class="o">...</span><span class="p">)):</span>
+<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">blog_repo</span><span class="o">.</span><span class="n">search_by_tags</span><span class="p">(</span><span class="n">tags</span><span class="p">)</span>
 </code></pre></div>
+<blockquote>
+<p><strong>Note:</strong> add the <code>lifespan</code> wiring from <a href="../01_basic_crud/">use case 01</a> so <code>blog_repo</code> is created after connection.</p>
+</blockquote>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li><code>get_many</code> calls <code>cursor.to_list(limit)</code>; pass <code>limit=0</code> to skip the limit entirely, otherwise a large explicit limit is safer than unbounded reads.</li>
+<li>Always <code>count</code> first for stable metadata — it uses the same filter as the page query.</li>
+<li>Combine with <code>sort=[(field, -1|1)]</code> for deterministic ordering; create matching indexes to avoid full collection scans (see <a href="../13_index_creation/">use case 13</a>).</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../02_custom_repo/">02 – Custom repository</a> · <a href="../13_index_creation/">13 – Indexes</a> · <a href="../05_soft_deletes/">05 – Soft deletes</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/05_soft_deletes/index.html b/mongo-ops/03_use_cases/05_soft_deletes/index.html
index cde05c5..0054786 100644
--- a/mongo-ops/03_use_cases/05_soft_deletes/index.html
+++ b/mongo-ops/03_use_cases/05_soft_deletes/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -621,6 +621,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -653,6 +655,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -661,9 +665,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-5-soft-deletes-pattern" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 5: Soft Deletes Pattern
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,93 +1035,125 @@
 
 
 
-  <h1>Soft Deletes</h1>
-
-<h3 id="use-case-5-soft-deletes-pattern">Use Case 5: Soft Deletes Pattern</h3>
-<p><strong>Scenario:</strong> Implement soft delete functionality for data recovery.</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Optional</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="k">class</span><span class="w"> </span><span class="nc">SoftDeleteDocument</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;Base document with soft delete support&quot;&quot;&quot;</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="n">is_deleted</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">deleted_at</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="n">datetime</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">deleted_by</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="k">class</span><span class="w"> </span><span class="nc">Task</span><span class="p">(</span><span class="n">SoftDeleteDocument</span><span class="p">):</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">description</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">assignee_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;pending&quot;</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">priority</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;medium&quot;</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="k">class</span><span class="w"> </span><span class="nc">SoftDeleteRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">T</span><span class="p">]):</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="w">    </span><span class="sd">&quot;&quot;&quot;Repository with soft delete operations&quot;&quot;&quot;</span>
+<h1 id="use-case-5-soft-deletes-pattern">Use Case 5: Soft Deletes Pattern</h1>
+<p><strong>Scenario:</strong> Deleting a task should be recoverable. Instead of removing the document, set a tombstone flag and filter it from normal queries.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>SoftDeleteDocument</code></td>
+<td>Base model carrying <code>is_deleted</code>, <code>deleted_at</code>, <code>deleted_by</code>.</td>
+</tr>
+<tr>
+<td><code>SoftDeleteRepository[T]</code></td>
+<td>Repository-level soft delete / restore / filtering using <code>update</code> + <code>get_many</code>.</td>
+</tr>
+<tr>
+<td><code>permanent_delete</code></td>
+<td>Escapes to the real <code>delete</code>.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">SoftDeleteDocument</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">is_deleted</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">deleted_at</span><span class="p">:</span> <span class="n">datetime</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">deleted_by</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="k">class</span><span class="w"> </span><span class="nc">Task</span><span class="p">(</span><span class="n">SoftDeleteDocument</span><span class="p">):</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">description</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">assignee_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;pending&quot;</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">priority</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;medium&quot;</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
 <a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">soft_delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">deleted_by</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="n">T</span><span class="p">]:</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Soft delete a document&quot;&quot;&quot;</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="p">{</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>            <span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>            <span class="s2">&quot;deleted_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">(),</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>            <span class="s2">&quot;deleted_by&quot;</span><span class="p">:</span> <span class="n">deleted_by</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>        <span class="p">})</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">restore</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Optional</span><span class="p">[</span><span class="n">T</span><span class="p">]:</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Restore a soft-deleted document&quot;&quot;&quot;</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="nb">id</span><span class="p">,</span> <span class="p">{</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>            <span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>            <span class="s2">&quot;deleted_at&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>            <span class="s2">&quot;deleted_by&quot;</span><span class="p">:</span> <span class="kc">None</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="p">})</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_active</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">100</span><span class="p">):</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get only non-deleted documents&quot;&quot;&quot;</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>            <span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">False</span><span class="p">},</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>            <span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>            <span class="n">limit</span><span class="o">=</span><span class="n">limit</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="p">)</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_deleted</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">100</span><span class="p">):</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Get deleted documents&quot;&quot;&quot;</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">},</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>            <span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>            <span class="n">limit</span><span class="o">=</span><span class="n">limit</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>        <span class="p">)</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">permanent_delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Permanently delete a document&quot;&quot;&quot;</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="k">class</span><span class="w"> </span><span class="nc">TaskRepository</span><span class="p">(</span><span class="n">SoftDeleteRepository</span><span class="p">[</span><span class="n">Task</span><span class="p">]):</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;tasks&quot;</span><span class="p">,</span> <span class="n">Task</span><span class="p">)</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="c1"># Usage in FastAPI</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="nd">@app</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="s2">&quot;/tasks/</span><span class="si">{task_id}</span><span class="s2">&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">soft_delete_task</span><span class="p">(</span><span class="n">task_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>    <span class="n">task</span> <span class="o">=</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">soft_delete</span><span class="p">(</span><span class="n">task_id</span><span class="p">,</span> <span class="n">deleted_by</span><span class="o">=</span><span class="n">user_id</span><span class="p">)</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">task</span><span class="p">:</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Task not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Task deleted&quot;</span><span class="p">,</span> <span class="s2">&quot;task&quot;</span><span class="p">:</span> <span class="n">task</span><span class="p">}</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/tasks/</span><span class="si">{task_id}</span><span class="s2">/restore&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">restore_task</span><span class="p">(</span><span class="n">task_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>    <span class="n">task</span> <span class="o">=</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">restore</span><span class="p">(</span><span class="n">task_id</span><span class="p">)</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">task</span><span class="p">:</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Task not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Task restored&quot;</span><span class="p">,</span> <span class="s2">&quot;task&quot;</span><span class="p">:</span> <span class="n">task</span><span class="p">}</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/tasks/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">Task</span><span class="p">])</span>
-<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_active_tasks</span><span class="p">(</span><span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">get_active</span><span class="p">(</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="p">)</span>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/tasks/deleted&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">List</span><span class="p">[</span><span class="n">Task</span><span class="p">])</span>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_deleted_tasks</span><span class="p">(</span><span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">get_deleted</span><span class="p">(</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="p">)</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="k">class</span><span class="w"> </span><span class="nc">SoftDeleteRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">T</span><span class="p">]):</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">soft_delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">deleted_by</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">(</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>            <span class="nb">id</span><span class="p">,</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>            <span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="s2">&quot;deleted_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">(),</span> <span class="s2">&quot;deleted_by&quot;</span><span class="p">:</span> <span class="n">deleted_by</span><span class="p">},</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="p">)</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">restore</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">update</span><span class="p">(</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>            <span class="nb">id</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span> <span class="s2">&quot;deleted_at&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span> <span class="s2">&quot;deleted_by&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">}</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="p">)</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_active</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">100</span><span class="p">):</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">False</span><span class="p">},</span> <span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="n">limit</span><span class="p">)</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_deleted</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">100</span><span class="p">):</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_many</span><span class="p">(</span><span class="nb">filter</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;is_deleted&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">},</span> <span class="n">skip</span><span class="o">=</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="o">=</span><span class="n">limit</span><span class="p">)</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">permanent_delete</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">bool</span><span class="p">:</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="k">class</span><span class="w"> </span><span class="nc">TaskRepository</span><span class="p">(</span><span class="n">SoftDeleteRepository</span><span class="p">[</span><span class="n">Task</span><span class="p">]):</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;tasks&quot;</span><span class="p">,</span> <span class="n">Task</span><span class="p">)</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a><span class="n">task_repo</span> <span class="o">=</span> <span class="n">TaskRepository</span><span class="p">()</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="nd">@app</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="s2">&quot;/tasks/</span><span class="si">{task_id}</span><span class="s2">&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">soft_delete_task</span><span class="p">(</span><span class="n">task_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="n">task</span> <span class="o">=</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">soft_delete</span><span class="p">(</span><span class="n">task_id</span><span class="p">,</span> <span class="n">deleted_by</span><span class="o">=</span><span class="n">user_id</span><span class="p">)</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">task</span><span class="p">:</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Task not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Task deleted&quot;</span><span class="p">,</span> <span class="s2">&quot;task&quot;</span><span class="p">:</span> <span class="n">task</span><span class="p">}</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/tasks/</span><span class="si">{task_id}</span><span class="s2">/restore&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">restore_task</span><span class="p">(</span><span class="n">task_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>    <span class="n">task</span> <span class="o">=</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">restore</span><span class="p">(</span><span class="n">task_id</span><span class="p">)</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">task</span><span class="p">:</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Task not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="k">return</span> <span class="p">{</span><span class="s2">&quot;message&quot;</span><span class="p">:</span> <span class="s2">&quot;Task restored&quot;</span><span class="p">,</span> <span class="s2">&quot;task&quot;</span><span class="p">:</span> <span class="n">task</span><span class="p">}</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/tasks/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">Task</span><span class="p">])</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_active_tasks</span><span class="p">(</span><span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">get_active</span><span class="p">(</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="p">)</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/tasks/deleted&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="nb">list</span><span class="p">[</span><span class="n">Task</span><span class="p">])</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">list_deleted_tasks</span><span class="p">(</span><span class="n">skip</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">limit</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">10</span><span class="p">):</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">task_repo</span><span class="o">.</span><span class="n">get_deleted</span><span class="p">(</span><span class="n">skip</span><span class="p">,</span> <span class="n">limit</span><span class="p">)</span>
 </code></pre></div>
+<blockquote>
+<p><strong>Note:</strong> add the <code>lifespan</code> wiring from <a href="../01_basic_crud/">use case 01</a> so <code>task_repo</code> is created after connection.</p>
+</blockquote>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li><code>BaseRepository[T]</code> is generic — subclasses must parameterize it (see <code>SoftDeleteRepository[T]</code> above). <code>from mongo_ops import BaseRepository; BaseRepository[T]</code> works out of the box.</li>
+<li>Keep a compound index on <code>{"is_deleted": 1, "status": 1}</code> for active-list queries (see <a href="../13_index_creation/">use case 13</a>).</li>
+<li>Soft-deleted documents should be <strong>excluded at the repository boundary</strong>, never re-filtered ad hoc in endpoints.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../01_basic_crud/">01 – Basic CRUD</a> · <a href="../13_index_creation/">13 – Indexes</a> · <a href="../04_pagination/">04 – Pagination</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/06_multi_model/index.html b/mongo-ops/03_use_cases/06_multi_model/index.html
index c9a77aa..529e8e6 100644
--- a/mongo-ops/03_use_cases/06_multi_model/index.html
+++ b/mongo-ops/03_use_cases/06_multi_model/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -644,6 +644,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -676,6 +678,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -684,9 +688,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#use-case-6-multi-model-service-with-registration" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      Use Case 6: Multi-Model Service with Registration
+      📦 What's New?
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1004,85 +1035,129 @@
 
 
 
-  <h1>Multi Model</h1>
-
-<h3 id="use-case-6-multi-model-service-with-registration">Use Case 6: Multi-Model Service with Registration</h3>
-<p><strong>Scenario:</strong> Complete microservice with multiple related models.</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>    <span class="n">MongoConnectionManager</span><span class="p">,</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>    <span class="n">BaseDocument</span><span class="p">,</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>    <span class="n">BaseRepository</span><span class="p">,</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="p">)</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># Define Models</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">role</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;user&quot;</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="k">class</span><span class="w"> </span><span class="nc">Post</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">likes</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="k">class</span><span class="w"> </span><span class="nc">Comment</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">post_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># Define Repositories</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="k">class</span><span class="w"> </span><span class="nc">PostRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Post</span><span class="p">]):</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="n">Post</span><span class="p">)</span>
+<h1 id="use-case-6-multi-model-service-with-registration">Use Case 6: Multi-Model Service with Registration</h1>
+<p><strong>Scenario:</strong> A social app manages <code>users</code>, <code>posts</code>, and <code>comments</code>. Each has its own model, repository, and indexes — registered centrally and initialized at startup.</p>
+<hr />
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>ModelRegistry.register</code></td>
+<td>One call per collection — model + indexes together.</td>
+</tr>
+<tr>
+<td><code>ModelRegistry.initialize_all</code></td>
+<td>Creates every registered index at startup (idempotent).</td>
+</tr>
+<tr>
+<td>Repositories</td>
+<td>One repository class per collection, all sharing the same connection.</td>
+</tr>
+</tbody>
+</table>
+<hr />
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">role</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;user&quot;</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="k">class</span><span class="w"> </span><span class="nc">Post</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">likes</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="k">class</span><span class="w"> </span><span class="nc">Comment</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">post_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">content</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="k">class</span><span class="w"> </span><span class="nc">PostRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Post</span><span class="p">]):</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="n">Post</span><span class="p">)</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>
 <a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>
 <a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="k">class</span><span class="w"> </span><span class="nc">CommentRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Comment</span><span class="p">]):</span>
 <a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
 <a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;comments&quot;</span><span class="p">,</span> <span class="n">Comment</span><span class="p">)</span>
 <a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="c1"># Register all models</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;username&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="n">Post</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;author_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)])</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;comments&quot;</span><span class="p">,</span> <span class="n">Comment</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;post_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;user_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a><span class="c1"># Setup FastAPI with lifespan</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>    <span class="k">await</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;social_app&quot;</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>    <span class="p">)</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>    <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>    <span class="k">yield</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="k">await</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="c1"># Initialize repositories</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="n">user_repo</span> <span class="o">=</span> <span class="n">UserRepository</span><span class="p">()</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="n">post_repo</span> <span class="o">=</span> <span class="n">PostRepository</span><span class="p">()</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="n">comment_repo</span> <span class="o">=</span> <span class="n">CommentRepository</span><span class="p">()</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="c1"># Central registration + indexes</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;username&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="n">Post</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;author_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;comments&quot;</span><span class="p">,</span> <span class="n">Comment</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;post_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;user_id&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a><span class="c1"># Lifecycle</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a><span class="c1"># ---------------------------</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;social_app&quot;</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>    <span class="p">):</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
 <a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="c1"># Endpoints</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">):</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">user_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/posts/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Post</span><span class="p">)</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_post</span><span class="p">(</span><span class="n">post</span><span class="p">:</span> <span class="n">Post</span><span class="p">):</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">post_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">post</span><span class="p">)</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/comments/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Comment</span><span class="p">)</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_comment</span><span class="p">(</span><span class="n">comment</span><span class="p">:</span> <span class="n">Comment</span><span class="p">):</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">comment_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">comment</span><span class="p">)</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="c1"># Created after connect() — inside the lifespan body is fine, or use a dependency.</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="n">user_repo</span> <span class="o">=</span> <span class="n">UserRepository</span><span class="p">()</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="n">post_repo</span> <span class="o">=</span> <span class="n">PostRepository</span><span class="p">()</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="n">comment_repo</span> <span class="o">=</span> <span class="n">CommentRepository</span><span class="p">()</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">):</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">user_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/posts/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Post</span><span class="p">)</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_post</span><span class="p">(</span><span class="n">post</span><span class="p">:</span> <span class="n">Post</span><span class="p">):</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">post_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">post</span><span class="p">)</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/comments/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Comment</span><span class="p">)</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_comment</span><span class="p">(</span><span class="n">comment</span><span class="p">:</span> <span class="n">Comment</span><span class="p">):</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">comment_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">comment</span><span class="p">)</span>
 </code></pre></div>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li><strong>Place <code>user_repo = ...</code> inside the lifespan/after connect.</strong> Module-level instantiation before <code>connect()</code> raises <code>RuntimeError("Database not connected...")</code>.</li>
+<li>Model relationships here are plain <code>ObjectId</code> strings stored on the child docs. To resolve them on read, see <a href="../08_population/">use case 08 – Population</a>.</li>
+<li>Registering indexes on <code>created_at</code>/<code>author_id</code>/<code>post_id</code> keeps the common queries indexed (see <a href="../13_index_creation/">use case 13</a>).</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../01_basic_crud/">01 – Basic CRUD</a> · <a href="../08_population/">08 – Population</a> · <a href="../13_index_creation/">13 – Indexes</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/07_caching/index.html b/mongo-ops/03_use_cases/07_caching/index.html
index ffba736..c67f69d 100644
--- a/mongo-ops/03_use_cases/07_caching/index.html
+++ b/mongo-ops/03_use_cases/07_caching/index.html
@@ -74,7 +74,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#use-case-7-caching-for-highperformance-reads" class="md-skip">
+        <a href="#use-case-7-caching-for-high-performance-reads" class="md-skip">
           Skip to content
         </a>
       
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -711,54 +711,45 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#1-whats-new" class="md-nav__link">
+  <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      1️⃣ What’s New?
+      📦 What's New?
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#2-quick-start" class="md-nav__link">
+  <a href="#example" class="md-nav__link">
     <span class="md-ellipsis">
-      2️⃣ Quick Start
+      🚀 Example
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#3-using-the-repository" class="md-nav__link">
+  <a href="#redis-backend" class="md-nav__link">
     <span class="md-ellipsis">
-      3️⃣ Using the Repository
+      🔄 Redis Backend
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#4-redis-backend-optional" class="md-nav__link">
+  <a href="#tips" class="md-nav__link">
     <span class="md-ellipsis">
-      4️⃣ Redis Backend (optional)
+      💡 Tips
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#5-when-to-use-caching" class="md-nav__link">
+  <a href="#related" class="md-nav__link">
     <span class="md-ellipsis">
-      5️⃣ When to Use Caching
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#6-related-docs" class="md-nav__link">
-    <span class="md-ellipsis">
-      6️⃣ Related Docs
+      Related
     </span>
   </a>
   
@@ -1053,104 +1044,139 @@
 
 
 
-<h1 id="use-case-7-caching-for-highperformance-reads">Use Case 7: Caching for High‑Performance Reads</h1>
-<p><strong>Scenario:</strong> A read‑heavy API (e.g., product catalog) benefits from an in‑memory cache or Redis cache to reduce latency and DB load.</p>
+<h1 id="use-case-7-caching-for-high-performance-reads">Use Case 7: Caching for High-Performance Reads</h1>
+<p><strong>Scenario:</strong> A read-heavy API (product catalog) reduces DB load by caching documents by <code>_id</code> — in-memory locally, or shared via Redis.</p>
 <hr />
-<h2 id="1-whats-new">1️⃣ What’s New?</h2>
-<ul>
-<li><strong>Cache back‑ends</strong>: <code>InMemoryCacheBackend</code> (TTL + LRU) and <code>RedisCacheBackend</code> (JSON‑serialised values, pub/sub invalidation).</li>
-<li><strong>Cache configuration</strong> via <code>CacheConfig</code> (<code>enabled</code>, <code>backend</code>, <code>default_ttl</code>, …).</li>
-<li><strong><code>CachedBaseRepository</code></strong> extends <code>BaseRepository</code> and adds:</li>
-<li>Transparent ID‑based caching on <code>get_by_id</code>.</li>
-<li>Automatic cache population on <code>create</code>.</li>
-<li>Cache invalidation on <code>update</code>/<code>delete</code>.</li>
-<li>Utility methods <code>warm_cache(ids)</code> and <code>invalidate_cache(id)</code>.</li>
-</ul>
+<h2 id="whats-new">📦 What's New?</h2>
+<table>
+<thead>
+<tr>
+<th>Component</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>InMemoryCacheBackend</code></td>
+<td>TTL + LRU cache with a background cleanup task.</td>
+</tr>
+<tr>
+<td><code>RedisCacheBackend</code></td>
+<td>Distributed cache on <code>redis.asyncio</code> with pub/sub invalidation.</td>
+</tr>
+<tr>
+<td><code>CachedBaseRepository[T]</code></td>
+<td>Extends <code>BaseRepository</code> — cache-first <code>get_by_id</code>, cache on <code>create</code>, invalidate on <code>update</code>/<code>delete</code>, <code>warm_cache(ids)</code>, <code>invalidate_cache(id)</code>.</td>
+</tr>
+<tr>
+<td>Backend lifecycle</td>
+<td>The <strong>same</strong> backend instance must be both passed to the repository AND registered via <code>ModelRegistry.set_cache_backend</code> so <code>initialize_cache()</code> starts its task.</td>
+</tr>
+</tbody>
+</table>
 <hr />
-<h2 id="2-quick-start">2️⃣ Quick Start</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>    <span class="n">BaseDocument</span><span class="p">,</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>    <span class="n">CachedBaseRepository</span><span class="p">,</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>    <span class="n">MongoConnectionManager</span><span class="p">,</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="n">ModelRegistry</span><span class="p">,</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="n">CacheConfig</span><span class="p">,</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="p">)</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">InMemoryCacheBackend</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="c1"># Define a model</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">Product</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">price</span><span class="p">:</span> <span class="nb">float</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="c1"># Initialise cache backend (in‑memory example)</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">10_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="c1"># Register the cache so the registry can initialise it later</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># Repository with caching</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProductRepo</span><span class="p">(</span><span class="n">CachedBaseRepository</span><span class="p">[</span><span class="n">Product</span><span class="p">]):</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;products&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>            <span class="n">model</span><span class="o">=</span><span class="n">Product</span><span class="p">,</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>            <span class="n">cache_backend</span><span class="o">=</span><span class="n">cache</span><span class="p">,</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>            <span class="n">config</span><span class="o">=</span><span class="n">CacheConfig</span><span class="p">(</span><span class="n">enabled</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">backend</span><span class="o">=</span><span class="s2">&quot;memory&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>        <span class="p">)</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="c1"># FastAPI lifespan – initialise DB and cache</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;shop&quot;</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="p">):</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>  <span class="c1"># Starts background cleanup, etc.</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="k">yield</span>
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">CacheConfig</span><span class="p">,</span> <span class="n">CachedBaseRepository</span><span class="p">,</span> <span class="n">InMemoryCacheBackend</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="k">class</span><span class="w"> </span><span class="nc">Product</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">price</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="c1"># One shared backend — used by both the repository and the registry lifecycle.</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">10_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProductRepo</span><span class="p">(</span><span class="n">CachedBaseRepository</span><span class="p">[</span><span class="n">Product</span><span class="p">]):</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;products&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>            <span class="n">model</span><span class="o">=</span><span class="n">Product</span><span class="p">,</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>            <span class="n">cache_backend</span><span class="o">=</span><span class="n">cache</span><span class="p">,</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>            <span class="n">config</span><span class="o">=</span><span class="n">CacheConfig</span><span class="p">(</span><span class="n">enabled</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">backend</span><span class="o">=</span><span class="s2">&quot;memory&quot;</span><span class="p">),</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>        <span class="p">)</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;shop&quot;</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="p">):</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>  <span class="c1"># starts the TTL cleanup task</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">shutdown_cache</span><span class="p">()</span>    <span class="c1"># cancels it on exit</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/products/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Product</span><span class="p">)</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_product</span><span class="p">(</span><span class="n">product</span><span class="p">:</span> <span class="n">Product</span><span class="p">):</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">ProductRepo</span><span class="p">()</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">product</span><span class="p">)</span>  <span class="c1"># created after connect()</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/products/</span><span class="si">{product_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Product</span><span class="p">)</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_product</span><span class="p">(</span><span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>    <span class="n">product</span> <span class="o">=</span> <span class="k">await</span> <span class="n">ProductRepo</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">product_id</span><span class="p">)</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">product</span><span class="p">:</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Product not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>    <span class="k">return</span> <span class="n">product</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="nd">@app</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="s2">&quot;/products/</span><span class="si">{product_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Product</span><span class="p">)</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_product</span><span class="p">(</span><span class="n">product_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span> <span class="n">price</span><span class="p">:</span> <span class="nb">float</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">):</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>    <span class="n">data</span> <span class="o">=</span> <span class="p">{}</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>    <span class="k">if</span> <span class="n">name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="n">data</span><span class="p">[</span><span class="s2">&quot;name&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">name</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>    <span class="k">if</span> <span class="n">price</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>        <span class="n">data</span><span class="p">[</span><span class="s2">&quot;price&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">price</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">ProductRepo</span><span class="p">()</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">product_id</span><span class="p">,</span> <span class="n">data</span><span class="p">)</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="c1"># Outside request handlers:</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="c1">#   await ProductRepo().warm_cache([object_id_1, object_id_2])   # pre-load n ids -&gt; int</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="c1">#   await ProductRepo().invalidate_cache(object_id_3)            # manual eviction</span>
 </code></pre></div>
 <hr />
-<h2 id="3-using-the-repository">3️⃣ Using the Repository</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="n">repo</span> <span class="o">=</span> <span class="n">ProductRepo</span><span class="p">()</span>
-<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="c1"># Create – automatically caches the new document</span>
-<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a><span class="n">product</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">Product</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;Widget&quot;</span><span class="p">,</span> <span class="n">price</span><span class="o">=</span><span class="mf">9.99</span><span class="p">))</span>
-<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>
-<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="c1"># Normal read – will hit the cache after the first DB fetch</span>
-<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a><span class="n">fetched</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">product</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
-<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>
-<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a><span class="c1"># Update – cache entry is refreshed</span>
-<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">product</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;price&quot;</span><span class="p">:</span> <span class="mf">8.99</span><span class="p">})</span>
-<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a>
-<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a><span class="c1"># Delete – cache entry removed</span>
-<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a><span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">delete</span><span class="p">(</span><span class="n">product</span><span class="o">.</span><span class="n">id</span><span class="p">)</span>
-<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a>
-<a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a><span class="c1"># Warm a set of IDs in advance (e.g., during a bulk load)</span>
-<a id="__codelineno-1-15" name="__codelineno-1-15" href="#__codelineno-1-15"></a><span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">warm_cache</span><span class="p">([</span><span class="n">ObjectId</span><span class="p">(</span><span class="s2">&quot;...&quot;</span><span class="p">),</span> <span class="n">ObjectId</span><span class="p">(</span><span class="s2">&quot;...&quot;</span><span class="p">)])</span>
+<h2 id="redis-backend">🔄 Redis Backend</h2>
+<p>Swap the backend — the repository code stays identical:</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">RedisCacheBackend</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">redis.asyncio</span><span class="w"> </span><span class="kn">import</span> <span class="n">Redis</span>
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="n">redis_client</span> <span class="o">=</span> <span class="n">Redis</span><span class="p">(</span><span class="n">host</span><span class="o">=</span><span class="s2">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">6379</span><span class="p">)</span>
+<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a><span class="n">redis_backend</span> <span class="o">=</span> <span class="n">RedisCacheBackend</span><span class="p">(</span><span class="n">redis_client</span><span class="p">,</span> <span class="n">key_prefix</span><span class="o">=</span><span class="s2">&quot;prod:&quot;</span><span class="p">)</span>
+<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>
+<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">redis_backend</span><span class="p">)</span>  <span class="c1"># for the lifecycle in lifespan()</span>
+<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
+<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">ProductRepo</span><span class="p">(</span><span class="n">CachedBaseRepository</span><span class="p">[</span><span class="n">Product</span><span class="p">]):</span>
+<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
+<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;products&quot;</span><span class="p">,</span>
+<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a>            <span class="n">model</span><span class="o">=</span><span class="n">Product</span><span class="p">,</span>
+<a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a>            <span class="n">cache_backend</span><span class="o">=</span><span class="n">redis_backend</span><span class="p">,</span>
+<a id="__codelineno-1-15" name="__codelineno-1-15" href="#__codelineno-1-15"></a>            <span class="n">config</span><span class="o">=</span><span class="n">CacheConfig</span><span class="p">(</span><span class="n">enabled</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">backend</span><span class="o">=</span><span class="s2">&quot;redis&quot;</span><span class="p">),</span>
+<a id="__codelineno-1-16" name="__codelineno-1-16" href="#__codelineno-1-16"></a>        <span class="p">)</span>
 </code></pre></div>
 <hr />
-<h2 id="4-redis-backend-optional">4️⃣ Redis Backend (optional)</h2>
-<p>If you prefer a distributed cache, swap the backend:</p>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">RedisCacheBackend</span>
-<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">redis.asyncio</span><span class="w"> </span><span class="kn">import</span> <span class="n">Redis</span>
-<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>
-<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="n">redis_client</span> <span class="o">=</span> <span class="n">Redis</span><span class="p">(</span><span class="n">host</span><span class="o">=</span><span class="s2">&quot;localhost&quot;</span><span class="p">,</span> <span class="n">port</span><span class="o">=</span><span class="mi">6379</span><span class="p">)</span>
-<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a><span class="n">redis_backend</span> <span class="o">=</span> <span class="n">RedisCacheBackend</span><span class="p">(</span><span class="n">redis_client</span><span class="p">,</span> <span class="n">key_prefix</span><span class="o">=</span><span class="s2">&quot;prod:&quot;</span><span class="p">)</span>
-<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">redis_backend</span><span class="p">)</span>
-</code></pre></div>
-<p>The repository code stays the same – just pass the <code>redis_backend</code> instance to <code>CachedBaseRepository</code>.</p>
-<hr />
-<h2 id="5-when-to-use-caching">5️⃣ When to Use Caching</h2>
+<h2 id="tips">💡 Tips</h2>
 <ul>
-<li>Frequently accessed documents (e.g., product details, configuration settings).</li>
-<li>Low‑write‑to‑read ratios where cache invalidation cost is acceptable.</li>
-<li>Distributed deployments where a shared Redis cache syncs invalidations via pub/sub.</li>
+<li>Cache keys are <code>"{key_prefix}{id}"</code> (default prefix <code>"products:"</code>). <code>clear_pattern("products:*")</code> wipes a whole collection's entries.</li>
+<li>Values are JSON-encoded (<code>json.dumps(obj, default=str)</code>) — nested models inside a cached document are stored as dicts, not objects.</li>
+<li>Enable/disable per repository with <code>CacheConfig(enabled=False)</code>; a disabled repo bypasses the cache entirely.</li>
+<li>Distinguish the two <code>initialize*</code> calls: <code>initialize_cache()</code> starts the backend task; <code>initialize_all()</code> creates indexes. Both belong in the lifespan, <strong>after</strong> <code>connect()</code>.</li>
 </ul>
 <hr />
-<h2 id="6-related-docs">6️⃣ Related Docs</h2>
+<h2 id="related">Related</h2>
 <ul>
-<li><strong>Core Components</strong> – see <code>docs/02_components.md</code> for the <code>CacheBackend</code> abstraction.</li>
-<li><strong>Best Practices</strong> – remember to call <code>ModelRegistry.initialize_cache()</code> after DB connection.</li>
+<li><a href="../11_cache_lifecycle/">11 – Cache lifecycle</a> · <a href="../10_cache_and_population/">10 – Cache + population</a> · <a href="../../02_components/">Components: cache</a></li>
 </ul>
-<hr />
-<p><em>Feel free to adapt the TTL, max entries, and backend to your workload.</em></p>
 
 
 
diff --git a/mongo-ops/03_use_cases/08_population/index.html b/mongo-ops/03_use_cases/08_population/index.html
index 4aeacdc..672a95b 100644
--- a/mongo-ops/03_use_cases/08_population/index.html
+++ b/mongo-ops/03_use_cases/08_population/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -736,16 +736,34 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#quick-example" class="md-nav__link">
+  <a href="#example" class="md-nav__link">
     <span class="md-ellipsis">
-      🚀 Quick Example
+      🚀 Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -1018,10 +1036,9 @@
 
 
 <h1 id="use-case-8-document-population">Use Case 8: Document Population</h1>
-<p><strong>Scenario:</strong><br />
-An API needs to return a single, denormalised JSON payload that includes related documents (e.g., a <code>User</code> with an embedded <code>Profile</code>, or an <code>Order</code> with its <code>LineItem</code>s) without the caller having to issue multiple requests.</p>
+<p><strong>Scenario:</strong> An API returns a <code>User</code> with its related <code>Profile</code> embedded in one JSON payload — no second round-trip from the client, no joins.</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1031,99 +1048,109 @@ An API needs to return a single, denormalised JSON payload that includes related
 </thead>
 <tbody>
 <tr>
-<td><strong><code>PopulateRule</code></strong></td>
-<td>Declarative rule that tells the engine how to populate a field.<br>Key attributes:<br>• <code>field_name</code> – Target attribute on the source model.<br>• <code>collection_name</code> – Collection that stores the referenced documents.<br>• <code>ref_field</code> – Name of the reference field (normally an <code>ObjectId</code>).<br>• Optional <code>nested_rules</code> for deep population, <code>max_depth</code> to bound recursion, and <code>filter</code> / <code>projection</code> for fine‑grained queries.</td>
+<td><code>PopulateRule</code></td>
+<td>Declares <em>which field</em> to resolve. <code>field_name</code> holds the <code>ObjectId</code> (or <code>list[ObjectId]</code>) <strong>and is the same field the resolved document replaces in place</strong>. <code>collection_name</code> says where the referenced documents live.</td>
 </tr>
 <tr>
-<td><strong><code>PopulationEngine</code></strong></td>
-<td>Core engine that resolves a list of <code>PopulateRule</code>s recursively. It:<br>• Detects circular references and raises <code>CircularReferenceError</code>.<br>• Honors per‑rule <code>max_depth</code> and a global <code>global_max_depth</code> (default 10).<br>• Supports MongoDB filters and projections for each populated relation.</td>
+<td><code>PopulationEngine</code></td>
+<td>Holds repositories by collection name and resolves rules recursively, detecting cycles (<code>CircularReferenceError</code>).</td>
 </tr>
 <tr>
-<td><strong><code>PopulatingRepository</code></strong></td>
-<td>Extends <code>BaseRepository</code> with automatic population support. Stores a reference to a <code>PopulationEngine</code> and a list of <code>PopulateRule</code>s, exposing two helpers:<br>• <code>_populate(document)</code> – Returns the same document with the requested relations populated.<br>• <code>_depopulate(document)</code> – Strips populated fields (useful before serialisation).</td>
-</tr>
-<tr>
-<td><strong>Cache‑aware population</strong> (optional) – The engine works with any <code>CacheBackend</code>. When used together with <code>CachedBaseRepository</code>, populated documents benefit from caching in the same way as regular CRUD results.</td>
-<td></td>
+<td><code>PopulatingRepository[T]</code></td>
+<td><code>get_by_id</code>/<code>get_many</code> populate on read; <code>create</code>/<code>update</code> depopulate on write; <code>patch</code> rejects FK fields.</td>
 </tr>
 </tbody>
 </table>
+<blockquote>
+<p>⚠️ <code>PopulateRule</code> does <strong>not</strong> have a separate "ref field" vs "target field" — the ref field is the populated field. <code>filter</code>/<code>projection</code> on <code>PopulateRule</code> are declared but not yet applied by the engine.</p>
+</blockquote>
 <hr />
-<h2 id="quick-example">🚀 Quick Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">,</span> <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">InMemoryCacheBackend</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1"># 1️⃣ Define the data models</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<h2 id="example">🚀 Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">PopulatingRepository</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="c1"># 1. Models — `profile` holds an ObjectId in the DB and becomes a Profile on read.</span>
 <a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">Profile</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
 <a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">avatar_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
 <a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">bio</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
 <a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">profile_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>          <span class="c1"># Reference to Profile</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>       <span class="c1"># Populated field (filled by engine)</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># ObjectId in MongoDB, Profile in memory</span>
 <a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># 2️⃣ (Optional) Set up a cache; helpful for deep graphs</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">10_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="c1"># 3️⃣ Create a PopulationEngine – repositories will be registered later</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="c1"># 4️⃣ Declare how the `profile` field should be populated</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="n">profile_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;profile_id&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="c1"># No further nesting in this simple example</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="p">)</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="c1"># 5️⃣ Repository that uses the engine + rule</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span><span class="n">profile_rule</span><span class="p">],</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>        <span class="p">)</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># 2. Engine + rule — repositories are registered later (after connect()).</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="n">profile_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="p">)</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="c1"># 3. The repository the app uses.</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>            <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span><span class="n">profile_rule</span><span class="p">],</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>        <span class="p">)</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>    <span class="p">):</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>        <span class="c1"># Tells the engine which repository resolves &quot;profiles&quot; refs.</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Profile</span><span class="p">](</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">Profile</span><span class="p">))</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
 <a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="c1"># 6️⃣ Register the repository with the engine so it can resolve refs</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Profile</span><span class="p">](</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">Profile</span><span class="p">))</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">UserRepository</span><span class="p">())</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="c1"># 7️⃣ FastAPI lifespan – initialise DB, indexes, and the cache</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="c1"># 4. Writing — pass the model; the repository depopulates to an ObjectId.</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">():</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>    <span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="n">username</span><span class="o">=</span><span class="s2">&quot;alice&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="n">email</span><span class="o">=</span><span class="s2">&quot;alice@example.com&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="n">profile</span><span class="o">=</span><span class="n">Profile</span><span class="p">(</span><span class="n">avatar_url</span><span class="o">=</span><span class="s2">&quot;alice.png&quot;</span><span class="p">,</span> <span class="n">bio</span><span class="o">=</span><span class="s2">&quot;hi&quot;</span><span class="p">),</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>    <span class="p">)</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>    <span class="k">return</span> <span class="k">await</span> <span class="n">UserRepository</span><span class="p">()</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>    <span class="c1"># ^ stored as {&quot;profile&quot;: &lt;ObjectId&gt;}, returned with profile populated</span>
 <a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>    <span class="p">):</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>        <span class="c1"># If you set up a cache backend (see step 2), initialize it here</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="c1"># 5. Reading — get_by_id resolves the reference on the way back.</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">UserRepository</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>    <span class="k">return</span> <span class="n">user</span>  <span class="c1"># user.profile is a Profile instance</span>
 </code></pre></div>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li><code>Patch</code>ing an FK field raises <code>ValueError</code> — switch FK changes to <code>update(user_id, model)</code> instead. See <a href="../05_soft_deletes/">use case 05</a> for the reasoning with soft deletes.</li>
+<li>Missing references resolve to <code>None</code>, not an error.</li>
+<li>A field holding an embedded dict (instead of an <code>ObjectId</code>) raises a <code>ValueError</code> ("run repair script") — migrate embedded docs to a separate collection first.</li>
+<li>If <code>create</code>/<code>update</code> receives a field that is <em>already</em> an <code>ObjectId</code> under a populate rule, <code>_depopulate</code> raises <code>ValueError("...was populate skipped?")</code> — populate-then-depopulate pairs must be balanced.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../09_advanced_population/">09 – Advanced population</a> · <a href="../10_cache_and_population/">10 – Cache + population</a> · <a href="../14_testing_guide/">14 – Testing guide</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/09_advanced_population/index.html b/mongo-ops/03_use_cases/09_advanced_population/index.html
index 8a5e0ee..d483ac6 100644
--- a/mongo-ops/03_use_cases/09_advanced_population/index.html
+++ b/mongo-ops/03_use_cases/09_advanced_population/index.html
@@ -74,7 +74,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#use-case-9-nested-document-population-circularref-handling" class="md-skip">
+        <a href="#use-case-9-nested-document-population-circular-ref-handling" class="md-skip">
           Skip to content
         </a>
       
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -759,7 +759,7 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
@@ -781,6 +781,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1026,11 +1035,10 @@
 
 
 
-<h1 id="use-case-9-nested-document-population-circularref-handling">Use Case 9: Nested Document Population &amp; Circular‑Ref Handling</h1>
-<p><strong>Scenario:</strong>
-A service must return an <code>Author</code> object with its <code>books</code> populated, and each <code>book</code> must include its <code>publisher</code>. The data model contains a possible circular reference (<code>Author.mentor_id</code> → another <code>Author</code>).</p>
+<h1 id="use-case-9-nested-document-population-circular-ref-handling">Use Case 9: Nested Document Population &amp; Circular-Ref Handling</h1>
+<p><strong>Scenario:</strong> An <code>Author</code> has <code>books</code> (a list of references), each <code>Book</code> references a <code>publisher</code>, and an <code>Author</code> may reference a <code>mentor</code> — which is <em>another</em> <code>Author</code> (a potential cycle).</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1040,117 +1048,120 @@ A service must return an <code>Author</code> object with its <code>books</code>
 </thead>
 <tbody>
 <tr>
-<td><strong><code>PopulateRule</code> (nested)</strong></td>
-<td>Allows you to declare a hierarchy of rules. In this example we populate <code>books</code> on <code>Author</code>, then <code>publisher</code> on each <code>Book</code>.</td>
+<td><code>nested_rules</code></td>
+<td>Populates deeper levels: resolve <code>books</code> on <code>Author</code>, then <code>publisher</code> inside each <code>Book</code>.</td>
 </tr>
 <tr>
-<td><strong><code>max_depth</code></strong></td>
-<td>Prevents infinite recursion when circular references exist.</td>
+<td><code>max_depth</code></td>
+<td>Per-rule recursion bound — the safety net for cyclic graphs.</td>
 </tr>
 <tr>
-<td><strong>Circular‑reference guard</strong></td>
-<td><code>PopulationEngine</code> raises <code>CircularReferenceError</code> if a cycle exceeds <code>max_depth</code> or is revisited.</td>
+<td><code>global_max_depth</code></td>
+<td><code>PopulationEngine(repos, global_max_depth=10)</code> global cap.</td>
+</tr>
+<tr>
+<td><code>CircularReferenceError</code></td>
+<td>Raised when a <code>(Class, id)</code> pair is revisited; carries the visited path.</td>
 </tr>
 </tbody>
 </table>
 <hr />
 <h2 id="example">🚀 Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">,</span> <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="c1"># 1️⃣ Define the data models</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="k">class</span><span class="w"> </span><span class="nc">Publisher</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">country</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">Book</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">publisher_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># Reference to Publisher</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">publisher</span><span class="p">:</span> <span class="n">Publisher</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="k">class</span><span class="w"> </span><span class="nc">Author</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">book_ids</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">ObjectId</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>   <span class="c1"># References to Book documents</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">books</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Book</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">mentor_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>      <span class="c1"># Optional circular reference to another Author</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">mentor</span><span class="p">:</span> <span class="s2">&quot;Author&quot;</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="c1"># 2️⃣ Create a PopulationEngine</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="c1"># 3️⃣ Declare nested rules</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="c1"># Populate the Publisher inside each Book</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="n">book_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;publisher&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;publisher_id&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a><span class="p">)</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="c1"># Populate books on Author, nesting the book_rule</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="n">author_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;book_ids&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>    <span class="n">nested_rules</span><span class="o">=</span><span class="p">[</span><span class="n">book_rule</span><span class="p">],</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="n">max_depth</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span>  <span class="c1"># safety net for deep graphs</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a><span class="p">)</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="c1"># Optional mentor rule (demonstrates circular‑ref handling)</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="n">mentor_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;mentor&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;mentor_id&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>    <span class="n">max_depth</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="p">)</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="c1"># 4️⃣ Repository that uses the engine + rules</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="k">class</span><span class="w"> </span><span class="nc">AuthorRepository</span><span class="p">(</span><span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Author</span><span class="p">]):</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>            <span class="n">model</span><span class="o">=</span><span class="n">Author</span><span class="p">,</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span><span class="n">author_rule</span><span class="p">,</span> <span class="n">mentor_rule</span><span class="p">],</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>        <span class="p">)</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="c1"># 5️⃣ Register all repositories with the engine</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Publisher</span><span class="p">](</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span> <span class="n">Publisher</span><span class="p">))</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;books&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Book</span><span class="p">](</span><span class="s2">&quot;books&quot;</span><span class="p">,</span> <span class="n">Book</span><span class="p">))</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span> <span class="n">AuthorRepository</span><span class="p">())</span>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="n">PopulatingRepository</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">CircularReferenceError</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># 1. Models — each ref field holds ObjectId(s) in the DB and becomes model(s) in memory.</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="k">class</span><span class="w"> </span><span class="nc">Publisher</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">country</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="k">class</span><span class="w"> </span><span class="nc">Book</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">publisher</span><span class="p">:</span> <span class="n">Publisher</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># ObjectId in DB, Publisher in memory</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="k">class</span><span class="w"> </span><span class="nc">Author</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">books</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">Book</span><span class="p">]</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>      <span class="c1"># list[ObjectId] in DB, list[Book] in memory</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="n">mentor</span><span class="p">:</span> <span class="s2">&quot;Author&quot;</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>        <span class="c1"># self-reference — potential cycle</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># 2. Engine + nested rules.</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="n">publisher_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;publisher&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="p">)</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="n">book_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>    <span class="n">nested_rules</span><span class="o">=</span><span class="p">[</span><span class="n">publisher_rule</span><span class="p">],</span>  <span class="c1"># fetch each book, then its publisher</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>    <span class="n">max_depth</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="p">)</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="n">mentor_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;mentor&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>    <span class="n">max_depth</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span>  <span class="c1"># stops mentor chains early — also avoids unbounded cycles</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="p">)</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a><span class="k">class</span><span class="w"> </span><span class="nc">AuthorRepository</span><span class="p">(</span><span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Author</span><span class="p">]):</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>            <span class="n">model</span><span class="o">=</span><span class="n">Author</span><span class="p">,</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span><span class="n">book_rule</span><span class="p">,</span> <span class="n">mentor_rule</span><span class="p">],</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="p">)</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;library&quot;</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="p">):</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>        <span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Publisher</span><span class="p">](</span><span class="s2">&quot;publishers&quot;</span><span class="p">,</span> <span class="n">Publisher</span><span class="p">))</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>        <span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;books&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Book</span><span class="p">](</span><span class="s2">&quot;books&quot;</span><span class="p">,</span> <span class="n">Book</span><span class="p">))</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>        <span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;authors&quot;</span><span class="p">,</span> <span class="n">AuthorRepository</span><span class="p">())</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
 <a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="c1"># 6️⃣ FastAPI lifespan – initialise DB &amp; cache (if any)</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span>
-<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;library&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>    <span class="p">):</span>
-<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>
-<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/authors/</span><span class="si">{author_id}</span><span class="s2">&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_author</span><span class="p">(</span><span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>    <span class="k">try</span><span class="p">:</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>        <span class="n">author</span> <span class="o">=</span> <span class="k">await</span> <span class="n">AuthorRepository</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">author_id</span><span class="p">)</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>    <span class="k">except</span> <span class="n">CircularReferenceError</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">409</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="sa">f</span><span class="s2">&quot;Circular reference: </span><span class="si">{</span><span class="n">exc</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">author</span><span class="p">:</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Author not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="k">return</span> <span class="n">author</span>
 </code></pre></div>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li>Use <code>max_depth</code> conservatively; a value of <code>2‑3</code> is enough for most graphs.</li>
-<li>When you <em>know</em> there are no cycles, you can omit <code>max_depth</code> on nested rules.</li>
-<li>The <code>CircularReferenceError</code> includes the visited path, which helps debugging.</li>
+<li><code>CircularReferenceError</code> is a <code>ValueError</code> subtype exposing <code>.collection</code>, <code>.doc_id</code>, and the visited <code>.path</code> — use it in error responses and logging.</li>
+<li>Keep <code>max_depth</code> conservative (2–3) for most graphs; combine with the global <code>global_max_depth=10</code> default.</li>
+<li>List refs depopulate back to <code>list[ObjectId]</code> on <code>create</code>/<code>update</code>, mirroring the scalar case.</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../08_population/">08 – Population</a> · <a href="../10_cache_and_population/">10 – Cache + population</a> · <a href="../../06_error_handling/">Error Handling</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/10_cache_and_population/index.html b/mongo-ops/03_use_cases/10_cache_and_population/index.html
index a6598b6..bc97796 100644
--- a/mongo-ops/03_use_cases/10_cache_and_population/index.html
+++ b/mongo-ops/03_use_cases/10_cache_and_population/index.html
@@ -74,7 +74,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#use-case-10-caching-population-readthrough-populated-docs" class="md-skip">
+        <a href="#use-case-10-caching-population-read-through-populated-on-read" class="md-skip">
           Skip to content
         </a>
       
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -782,7 +782,7 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
@@ -804,6 +804,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1026,11 +1035,10 @@
 
 
 
-<h1 id="use-case-10-caching-population-readthrough-populated-docs">Use Case 10: Caching + Population (Read‑Through + Populated Docs)</h1>
-<p><strong>Scenario:</strong>
-A service needs fast reads of a <code>User</code> document <strong>and</strong> its related <code>Profile</code>. The repository should cache the final populated result so subsequent calls hit the cache directly.</p>
+<h1 id="use-case-10-caching-population-read-through-populated-on-read">Use Case 10: Caching + Population (Read-Through, Populated on Read)</h1>
+<p><strong>Scenario:</strong> A service needs fast reads of a <code>User</code> <strong>and</strong> its related <code>Profile</code>. We want the cache-hit path to skip the DB entirely while still returning a populated document.</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1040,116 +1048,139 @@ A service needs fast reads of a <code>User</code> document <strong>and</strong>
 </thead>
 <tbody>
 <tr>
-<td><strong><code>CachedBaseRepository</code></strong></td>
-<td>Provides transparent ID‑based caching for CRUD operations.</td>
+<td><code>CachedBaseRepository</code></td>
+<td>Provides the cache layer (<code>cache-first get_by_id</code>, invalidation on <code>update</code>/<code>delete</code>).</td>
 </tr>
 <tr>
-<td><strong><code>PopulatingRepository</code></strong></td>
-<td>Adds automatic population of referenced documents.</td>
+<td><code>PopulationEngine</code></td>
+<td>Provides the reference resolution.</td>
 </tr>
 <tr>
-<td><strong>Combined usage</strong></td>
-<td>By inheriting from <code>CachedBaseRepository</code> <em>and</em> wiring a <code>PopulationEngine</code>, the repository caches the <strong>populated</strong> document, eliminating both DB and population overhead on cache hits.</td>
+<td><strong>Composed subclass</strong></td>
+<td>A small <code>CachedBaseRepository</code> subclass adds two <code>_populate</code> helpers so cache hits return populated models.</td>
 </tr>
 </tbody>
 </table>
+<blockquote>
+<p>⚠️ <strong>Known limitation:</strong> there is <strong>no built-in <code>CachedPopulatingRepository</code></strong> in the library. This use case documents the composition. We cache the <strong>raw (depopulated)</strong> document — references stay <code>ObjectId</code>s until read time, so <code>Profile</code> changes are reflected on the next fetch (within TTL) and <code>update</code>/<code>delete</code> invalidation remains correct.</p>
+</blockquote>
 <hr />
 <h2 id="example">🚀 Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">CachedBaseRepository</span><span class="p">,</span> <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">InMemoryCacheBackend</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1"># 1️⃣ Define models</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">Profile</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">avatar_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">bio</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">profile_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>        <span class="c1"># Reference to Profile</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>     <span class="c1"># Populated field</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># 2️⃣ Initialise cache backend (in‑memory example)</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">20_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">600</span><span class="p">)</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="c1"># 3️⃣ Set up a PopulationEngine (repositories will be registered later)</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="n">profile_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;profile_id&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="p">)</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="c1"># 4️⃣ Cached + Populating repository</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">CachedBaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>            <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>            <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>            <span class="n">cache_backend</span><span class="o">=</span><span class="n">cache</span><span class="p">,</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="n">config</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>  <span class="c1"># defaults to enabled=True, backend=&quot;memory&quot;</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="p">)</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>        <span class="c1"># Attach the population engine after the base repo is ready</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">population_engine</span> <span class="o">=</span> <span class="n">engine</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">_populate_rules</span> <span class="o">=</span> <span class="p">[</span><span class="n">profile_rule</span><span class="p">]</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>    <span class="c1"># Override get_by_id to include population before caching</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_id</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>        <span class="c1"># First attempt cache lookup (as in CachedBaseRepository)</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>        <span class="n">cached</span> <span class="o">=</span> <span class="k">await</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>        <span class="k">if</span> <span class="n">cached</span><span class="p">:</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>            <span class="k">return</span> <span class="n">cached</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="c1"># Not in cache – fetch from DB and populate</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="n">doc</span> <span class="o">=</span> <span class="k">await</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>  <span class="c1"># this will hit the DB (no cache hit)</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="k">if</span> <span class="n">doc</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>            <span class="k">return</span> <span class="kc">None</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>        <span class="c1"># Populate related docs</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>        <span class="n">populated</span> <span class="o">=</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">populate</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">_populate_rules</span><span class="p">)</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>        <span class="c1"># Store the fully populated result in cache for next call</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>        <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_cache_key</span><span class="p">(</span><span class="nb">id</span><span class="p">),</span> <span class="n">populated</span><span class="p">)</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>        <span class="k">return</span> <span class="n">populated</span>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Any</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">CacheConfig</span><span class="p">,</span> <span class="n">CachedBaseRepository</span><span class="p">,</span> <span class="n">InMemoryCacheBackend</span><span class="p">,</span> <span class="n">decode_value</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="c1"># 1. Models — `profile` holds an ObjectId in DB, a Profile in memory.</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">Profile</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">avatar_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">bio</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="c1"># 2. Engine + rule.</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="n">engine</span> <span class="o">=</span> <span class="n">PopulationEngine</span><span class="p">({})</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="n">profile_rule</span> <span class="o">=</span> <span class="n">PopulateRule</span><span class="p">(</span><span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span> <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="c1"># 3. Composed repository.</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="k">class</span><span class="w"> </span><span class="nc">CachedUserRepository</span><span class="p">(</span><span class="n">CachedBaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="bp">self</span><span class="p">,</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>        <span class="n">cache_backend</span><span class="p">:</span> <span class="n">InMemoryCacheBackend</span><span class="p">,</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="n">population_engine</span><span class="p">:</span> <span class="n">PopulationEngine</span><span class="p">,</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>        <span class="n">populate_rules</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="n">PopulateRule</span><span class="p">],</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="n">config</span><span class="p">:</span> <span class="n">CacheConfig</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="p">):</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">cache_backend</span><span class="p">,</span> <span class="n">config</span><span class="p">)</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">population_engine</span> <span class="o">=</span> <span class="n">population_engine</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">_populate_rules</span> <span class="o">=</span> <span class="n">populate_rules</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">_populate</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">data</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">]:</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="w">        </span><span class="sd">&quot;&quot;&quot;Dict-level resolution (mirrors PopulatingRepository._populate).&quot;&quot;&quot;</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="k">for</span> <span class="n">rule</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">_populate_rules</span><span class="p">:</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="n">ref</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">rule</span><span class="o">.</span><span class="n">field_name</span><span class="p">)</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>            <span class="k">if</span> <span class="n">ref</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>                <span class="k">continue</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">ref</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>  <span class="c1"># JSON round-trip turns ObjectId into hex str</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>                <span class="n">ref</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">ref</span><span class="p">)</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>            <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">ref</span><span class="p">,</span> <span class="nb">list</span><span class="p">):</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>                <span class="n">resolved</span> <span class="o">=</span> <span class="p">[]</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>                <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">ref</span><span class="p">:</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>                    <span class="n">item</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">item</span><span class="p">)</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">item</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="k">else</span> <span class="n">item</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>                    <span class="n">repo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">population_engine</span><span class="o">.</span><span class="n">_repos</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">rule</span><span class="o">.</span><span class="n">collection_name</span><span class="p">)</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>                    <span class="n">doc</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">item</span><span class="p">)</span> <span class="k">if</span> <span class="n">repo</span> <span class="k">else</span> <span class="kc">None</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>                    <span class="n">resolved</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">doc</span><span class="p">)</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>                <span class="n">data</span><span class="p">[</span><span class="n">rule</span><span class="o">.</span><span class="n">field_name</span><span class="p">]</span> <span class="o">=</span> <span class="n">resolved</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>            <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">ref</span><span class="p">,</span> <span class="n">ObjectId</span><span class="p">):</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>                <span class="n">repo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">population_engine</span><span class="o">.</span><span class="n">_repos</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">rule</span><span class="o">.</span><span class="n">collection_name</span><span class="p">)</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>                <span class="n">data</span><span class="p">[</span><span class="n">rule</span><span class="o">.</span><span class="n">field_name</span><span class="p">]</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">ref</span><span class="p">)</span> <span class="k">if</span> <span class="n">repo</span> <span class="k">else</span> <span class="kc">None</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>        <span class="k">return</span> <span class="n">data</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_by_id</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">id</span><span class="p">):</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>        <span class="k">if</span> <span class="ow">not</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache_config</span><span class="o">.</span><span class="n">enabled</span><span class="p">:</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>            <span class="k">return</span> <span class="k">await</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>  <span class="c1"># no cache -&gt; raw, unpopulated</span>
 <a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a><span class="c1"># 5️⃣ Register repositories with the engine for population resolution</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">PopulatingRepository</span><span class="p">[</span><span class="n">Profile</span><span class="p">](</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span> <span class="n">Profile</span><span class="p">))</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">UserRepository</span><span class="p">())</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>        <span class="n">cached</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_cache</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_cache_key</span><span class="p">(</span><span class="nb">id</span><span class="p">))</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="k">if</span> <span class="n">cached</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>            <span class="c1"># Cache hit: decode the RAW doc, then populate before returning.</span>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>            <span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_populate</span><span class="p">(</span><span class="n">decode_value</span><span class="p">(</span><span class="n">cached</span><span class="p">))</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>            <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">data</span><span class="p">)</span>
 <a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="c1"># 6️⃣ FastAPI lifespan – initialise DB, create indexes, and start cache cleanup</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>        <span class="c1"># Cache miss: single DB read; the base class caches the raw (depopulated) doc.</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>        <span class="k">if</span> <span class="n">result</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>            <span class="k">return</span> <span class="kc">None</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_populate</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">model_dump</span><span class="p">(</span><span class="n">by_alias</span><span class="o">=</span><span class="kc">True</span><span class="p">)))</span>
 <a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;app_db&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>    <span class="p">):</span>
-<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>
-<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="c1"># 4. Wire-up — one backend for both the repo and the registry lifecycle.</span>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">20_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">600</span><span class="p">)</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>
+<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>
+<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;app_db&quot;</span>
+<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a>    <span class="p">):</span>
+<a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>        <span class="c1"># Register the repositories the engine resolves refs against:</span>
+<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a>        <span class="c1"># engine.register_repo(&quot;profiles&quot;, ProfileRepo())</span>
+<a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a>        <span class="n">engine</span><span class="o">.</span><span class="n">register_repo</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">CachedUserRepository</span><span class="p">(</span><span class="n">cache</span><span class="p">,</span> <span class="n">engine</span><span class="p">,</span> <span class="p">[</span><span class="n">profile_rule</span><span class="p">]))</span>
+<a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>
+<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">shutdown_cache</span><span class="p">()</span>
+<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a>
+<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a>
+<a id="__codelineno-0-98" name="__codelineno-0-98" href="#__codelineno-0-98"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
 </code></pre></div>
+<blockquote>
+<p><strong>Note:</strong> replace the placeholder <code>engine.register_repo("profiles", ...)</code> line with a repository for <code>Profile</code>. A matching <code>CachedBaseRepository[Profile]("profiles", Profile, cache)</code> keeps profile reads cached too — e.g. <code>engine.register_repo("profiles", CachedBaseRepository[Profile]("profiles", Profile, cache))</code>.</p>
+</blockquote>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li>The example overrides <code>get_by_id</code> to keep the caching logic simple; you could also create a mixin that composes <code>CachedBaseRepository</code> and <code>PopulatingRepository</code>.</li>
-<li>Remember to call <code>await ModelRegistry.initialize_cache()</code> <strong>after</strong> the DB connection is ready; otherwise the background cleanup task will never start.</li>
-<li>Cache keys are generated by <code>CachedBaseRepository._cache_key(id)</code>. If you change the repository’s <code>config.key_prefix</code>, the same prefix will be used for populated results.</li>
+<li><strong>Cache the raw doc, populate at read time.</strong> Ref fields stay <code>ObjectId</code>s in the cache; JSON round-trips them to hex strings, so <code>_populate</code> must normalize <code>str → ObjectId</code> (shown above).</li>
+<li><code>update</code>/<code>delete</code> from the base class still invalidate the right key because we never repopulate <em>in</em> the cache.</li>
+<li>Set a sensible <code>default_ttl</code> — cached <code>User</code> entries resolve <code>Profile</code> on each read, so profile edits show up within the TTL (or call <code>invalidate_cache(user_id)</code> explicitly).</li>
+<li>If you want one repo class used app-wide, keep the populate helpers in a mixin shared with regular <code>PopulatingRepository</code>.</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../07_caching/">07 – Caching</a> · <a href="../08_population/">08 – Population</a> · <a href="../11_cache_lifecycle/">11 – Cache lifecycle</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/11_cache_lifecycle/index.html b/mongo-ops/03_use_cases/11_cache_lifecycle/index.html
index ef9a2f3..3917f59 100644
--- a/mongo-ops/03_use_cases/11_cache_lifecycle/index.html
+++ b/mongo-ops/03_use_cases/11_cache_lifecycle/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -805,7 +805,7 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
@@ -818,21 +818,15 @@
     </span>
   </a>
   
-    <nav class="md-nav" aria-label="🚀 Example">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
-  <a href="#why-a-separate-shutdown-step" class="md-nav__link">
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#what-actually-happens" class="md-nav__link">
     <span class="md-ellipsis">
-      Why a separate shutdown step?
+      🔁 What Actually Happens
     </span>
   </a>
   
-</li>
-        
-      </ul>
-    </nav>
-  
 </li>
       
         <li class="md-nav__item">
@@ -842,6 +836,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1042,10 +1045,9 @@
 
 
 <h1 id="use-case-11-proper-cache-lifecycle-in-fastapi">Use Case 11: Proper Cache Lifecycle in FastAPI</h1>
-<p><strong>Scenario:</strong>
-A microservice uses <code>InMemoryCacheBackend</code> (or Redis) and needs to start the cache cleanup task when the app starts, then shut it down cleanly on termination.</p>
+<p><strong>Scenario:</strong> A microservice uses an in-memory (or Redis) cache backend and must start the cleanup task on app start, then shut it down cleanly on termination.</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1055,55 +1057,69 @@ A microservice uses <code>InMemoryCacheBackend</code> (or Redis) and needs to st
 </thead>
 <tbody>
 <tr>
+<td><code>ModelRegistry.set_cache_backend(backend)</code></td>
+<td>Registers the single shared backend.</td>
+</tr>
+<tr>
 <td><code>ModelRegistry.initialize_cache()</code></td>
-<td>Starts the async background task for the registered cache backend.</td>
+<td>Starts the backend (spawns the in-memory TTL cleanup task). Raises <code>RuntimeError</code> if no backend was registered.</td>
 </tr>
 <tr>
 <td><code>ModelRegistry.shutdown_cache()</code></td>
-<td>Gracefully stops the background task and releases resources.</td>
+<td>Cancels the cleanup task, closes pub/sub, clears the backend.</td>
 </tr>
 <tr>
-<td>FastAPI lifespan integration</td>
-<td>Demonstrates where to call both init and shutdown methods.</td>
+<td>If a repo uses a backend directly</td>
+<td>Same instance must be registered so <code>initialize_cache</code> starts <em>its</em> task.</td>
 </tr>
 </tbody>
 </table>
 <hr />
 <h2 id="example">🚀 Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">InMemoryCacheBackend</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="c1"># Initialise a cache backend (in‑memory example)</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">10_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="c1"># Start MongoDB connection and cache background task</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span><span class="p">,</span>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">InMemoryCacheBackend</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="n">cache</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span><span class="n">max_entries</span><span class="o">=</span><span class="mi">10_000</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">set_cache_backend</span><span class="p">(</span><span class="n">cache</span><span class="p">)</span>  <span class="c1"># before any cache-backed repo is used</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span>
 <a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>   <span class="c1"># create indexes</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>  <span class="c1"># start cache cleanup</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>    <span class="c1"># create indexes (idempotent)</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_cache</span><span class="p">()</span>  <span class="c1"># start the TTL cleanup task</span>
 <a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>        <span class="k">yield</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="c1"># FastAPI will exit the `with` block here – clean up cache</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">shutdown_cache</span><span class="p">()</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">shutdown_cache</span><span class="p">()</span>    <span class="c1"># cancel task + close cleanly</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">(</span><span class="n">lifespan</span><span class="o">=</span><span class="n">lifespan</span><span class="p">)</span>
 </code></pre></div>
-<h3 id="why-a-separate-shutdown-step">Why a separate shutdown step?</h3>
+<hr />
+<h2 id="what-actually-happens">🔁 What Actually Happens</h2>
 <ul>
-<li>The cache backend may spawn an <code>asyncio.Task</code> that periodically removes expired entries. If the task is left dangling, the event loop may complain about pending tasks on shutdown.</li>
-<li><code>shutdown_cache()</code> cancels the internal task and waits for it to finish, ensuring a clean exit.</li>
+<li><code>InMemoryCacheBackend.initialize()</code> spawns an <code>asyncio.Task</code> that evicts expired entries every <code>cleanup_interval</code> seconds. Without a shutdown, the event loop flags the dangling task on exit — <code>shutdown_cache()</code> cancels it and awaits it.</li>
+<li><code>shutdown_cache()</code> also NULs the registry cache backend and closes the Redis pub/sub handle (if Redis).</li>
+<li>If <code>initialize_cache()</code> is called before <code>set_cache_backend()</code>, it raises:</li>
 </ul>
+<div class="language-text highlight"><span class="filename">Text Only</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>RuntimeError: No cache backend registered. Call set_cache_backend() first.
+</code></pre></div>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li>Register the cache <strong>before</strong> calling <code>initialize_cache()</code>; otherwise the registry won’t know which backend to start.</li>
-<li>For Redis backends, the shutdown step also closes the underlying <code>redis.asyncio.Redis</code> client connection.</li>
-<li>You can also hook the shutdown into a FastAPI <code>@app.on_event("shutdown")</code> handler if you prefer not to use the lifespan context manager.</li>
+<li>Per-repository toggling is independent of the lifecycle: <code>CacheConfig(enabled=False)</code> bypasses the cache for that repo even after <code>initialize_cache()</code>.</li>
+<li>The cleanup task uses <code>cleanup_interval</code> seconds for scans; entries also expire on access via the TTL heap (<code>default_ttl=0</code> expires immediately).</li>
+<li>Register the backend <strong>before</strong> constructing any <code>CachedBaseRepository</code> that references it — otherwise a repo may hold an uninitialized backend (no cleanup task, no Redis pub/sub).</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../07_caching/">07 – Caching</a> · <a href="../../02_components/">Components: ModelRegistry</a> · <a href="../10_cache_and_population/">10 – Cache + population</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/12_transaction_helper/index.html b/mongo-ops/03_use_cases/12_transaction_helper/index.html
index d5faa48..afefb31 100644
--- a/mongo-ops/03_use_cases/12_transaction_helper/index.html
+++ b/mongo-ops/03_use_cases/12_transaction_helper/index.html
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -828,7 +828,7 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
@@ -850,6 +850,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1027,10 +1036,9 @@
 
 
 <h1 id="use-case-12-using-transactionmanagerexecute_transaction">Use Case 12: Using <code>TransactionManager.execute_transaction</code></h1>
-<p><strong>Scenario:</strong>
-You need to perform several writes across different collections atomically (e.g., creating an <code>Order</code> and updating the <code>Inventory</code> for each ordered item). The low‑level <code>start_session</code> context manager works, but the high‑level <code>execute_transaction</code> helper makes the code cleaner and returns all operation results in a list.</p>
+<p><strong>Scenario:</strong> Perform several writes across different collections atomically — e.g., create an <code>Order</code> <strong>and</strong> decrement <code>Inventory</code>. The low-level <code>start_session</code> context works, but <code>execute_transaction</code> collects results from a list of async operations.</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1041,112 +1049,113 @@ You need to perform several writes across different collections atomically (e.g.
 <tbody>
 <tr>
 <td><code>TransactionManager.execute_transaction</code></td>
-<td>Accepts a list of async callables (each receiving a <code>session</code>) and executes them inside a single MongoDB transaction. Returns a list of each callable’s result.</td>
+<td>Runs a list of async callables (each receives a session) inside one transaction; returns the result of each callable, in order.</td>
 </tr>
 <tr>
 <td>Automatic rollback</td>
-<td>If any operation raises an exception, the transaction is aborted and the exception propagates.</td>
+<td>Any raised exception aborts the transaction and propagates to the caller.</td>
+</tr>
+<tr>
+<td><code>start_session</code></td>
+<td>The underlying async context manager <code>async with TransactionManager.start_session() as session:</code>.</td>
 </tr>
 </tbody>
 </table>
 <hr />
 <h2 id="example">🚀 Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="n">ModelRegistry</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.transactions</span><span class="w"> </span><span class="kn">import</span> <span class="n">TransactionManager</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.repository</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseRepository</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="c1"># 1️⃣ Define simple models</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="k">class</span><span class="w"> </span><span class="nc">Order</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">items</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">dict</span><span class="p">]</span>  <span class="c1"># [{&quot;product_id&quot;: ObjectId, &quot;qty&quot;: int}]</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">total</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="k">class</span><span class="w"> </span><span class="nc">Inventory</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">product_id</span><span class="p">:</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">quantity</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># 2️⃣ Repositories</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="k">class</span><span class="w"> </span><span class="nc">OrderRepo</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Order</span><span class="p">]):</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;orders&quot;</span><span class="p">,</span> <span class="n">Order</span><span class="p">)</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="k">class</span><span class="w"> </span><span class="nc">InventoryRepo</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Inventory</span><span class="p">]):</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;inventory&quot;</span><span class="p">,</span> <span class="n">Inventory</span><span class="p">)</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="n">order_repo</span> <span class="o">=</span> <span class="n">OrderRepo</span><span class="p">()</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="n">inv_repo</span> <span class="o">=</span> <span class="n">InventoryRepo</span><span class="p">()</span>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.repository</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseRepository</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.transactions</span><span class="w"> </span><span class="kn">import</span> <span class="n">TransactionManager</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="c1"># 1. Models</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">Order</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">items</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">dict</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>  <span class="c1"># [{&quot;product_id&quot;: ObjectId, &quot;qty&quot;: int}]</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">total</span><span class="p">:</span> <span class="nb">float</span> <span class="o">=</span> <span class="mf">0.0</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="k">class</span><span class="w"> </span><span class="nc">Inventory</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">product_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">quantity</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="c1"># 2. Repositories (constructed inside the lifespan — after connect()).</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="k">class</span><span class="w"> </span><span class="nc">OrderRepo</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Order</span><span class="p">]):</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;orders&quot;</span><span class="p">,</span> <span class="n">Order</span><span class="p">)</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="k">class</span><span class="w"> </span><span class="nc">InventoryRepo</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Inventory</span><span class="p">]):</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;inventory&quot;</span><span class="p">,</span> <span class="n">Inventory</span><span class="p">)</span>
 <a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a><span class="c1"># 3️⃣ Transaction helper</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order_with_inventory</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">):</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">insert_order</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="c1"># Insert the order document</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="n">doc</span> <span class="o">=</span> <span class="n">order</span><span class="o">.</span><span class="n">model_dump</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">},</span> <span class="n">exclude_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;created_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;updated_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="nb">__import__</span><span class="p">(</span><span class="s2">&quot;datetime&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">result</span><span class="o">.</span><span class="n">inserted_id</span><span class="p">},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_inventory</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="c1"># Decrease quantity for each ordered item</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>        <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="p">:</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="k">await</span> <span class="n">inv_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>                <span class="p">{</span><span class="s2">&quot;product_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;product_id&quot;</span><span class="p">])},</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>                <span class="p">{</span><span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="o">-</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;qty&quot;</span><span class="p">]}},</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>                <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>            <span class="p">)</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>        <span class="k">return</span> <span class="s2">&quot;inventory-updated&quot;</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="c1"># Execute both operations atomically</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>    <span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">execute_transaction</span><span class="p">([</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="k">lambda</span> <span class="n">s</span><span class="p">:</span> <span class="n">insert_order</span><span class="p">(</span><span class="n">s</span><span class="p">),</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="k">lambda</span> <span class="n">s</span><span class="p">:</span> <span class="n">update_inventory</span><span class="p">(</span><span class="n">s</span><span class="p">),</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>    <span class="p">])</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>    <span class="c1"># `results[0]` is the created order document, `results[1]` is the marker string</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>    <span class="k">return</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a><span class="c1"># 4️⃣ FastAPI lifespan – initialise DB and run the example endpoint</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a><span class="c1"># 3. The atomic operation.</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order_with_inventory</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">,</span> <span class="n">order_repo</span><span class="p">:</span> <span class="n">OrderRepo</span><span class="p">,</span> <span class="n">inv_repo</span><span class="p">:</span> <span class="n">InventoryRepo</span><span class="p">):</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">insert_order</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="n">doc</span> <span class="o">=</span> <span class="n">order</span><span class="o">.</span><span class="n">model_dump</span><span class="p">(</span><span class="n">exclude</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">},</span> <span class="n">exclude_none</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;created_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">doc</span><span class="p">[</span><span class="s2">&quot;updated_at&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">insert_one</span><span class="p">(</span><span class="n">doc</span><span class="p">,</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">order_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">result</span><span class="o">.</span><span class="n">inserted_id</span><span class="p">},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">update_inventory</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">order</span><span class="o">.</span><span class="n">items</span><span class="p">:</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="k">await</span> <span class="n">inv_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">(</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>                <span class="p">{</span><span class="s2">&quot;product_id&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">(</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;product_id&quot;</span><span class="p">])},</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>                <span class="p">{</span><span class="s2">&quot;$inc&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;quantity&quot;</span><span class="p">:</span> <span class="o">-</span><span class="n">item</span><span class="p">[</span><span class="s2">&quot;qty&quot;</span><span class="p">]}},</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>                <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">,</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>            <span class="p">)</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="k">return</span> <span class="s2">&quot;inventory-updated&quot;</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>    <span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">execute_transaction</span><span class="p">(</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>        <span class="p">[</span><span class="n">insert_order</span><span class="p">,</span> <span class="n">update_inventory</span><span class="p">]</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>    <span class="p">)</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="k">return</span> <span class="n">results</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>  <span class="c1"># created order document; results[1] == &quot;inventory-updated&quot;</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a><span class="c1"># 4. FastAPI wiring.</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="nd">@asynccontextmanager</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">:</span> <span class="n">FastAPI</span><span class="p">):</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span> <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;shop&quot;</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="p">):</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>
 <a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;shop&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>    <span class="p">):</span>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>        <span class="k">yield</span>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="n">app</span><span class="o">.</span><span class="n">lifespan</span> <span class="o">=</span> <span class="n">lifespan</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/orders/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">):</span>
-<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>    <span class="n">created</span> <span class="o">=</span> <span class="k">await</span> <span class="n">create_order_with_inventory</span><span class="p">(</span><span class="n">order</span><span class="p">)</span>
-<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>    <span class="k">if</span> <span class="n">created</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
-<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Transaction failed&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a>    <span class="k">return</span> <span class="n">created</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a><span class="n">app</span><span class="o">.</span><span class="n">lifespan</span> <span class="o">=</span> <span class="n">lifespan</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/orders/&quot;</span><span class="p">,</span> <span class="n">response_model</span><span class="o">=</span><span class="n">Order</span><span class="p">)</span>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_order</span><span class="p">(</span><span class="n">order</span><span class="p">:</span> <span class="n">Order</span><span class="p">):</span>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>    <span class="n">created</span> <span class="o">=</span> <span class="k">await</span> <span class="n">create_order_with_inventory</span><span class="p">(</span><span class="n">order</span><span class="p">,</span> <span class="n">OrderRepo</span><span class="p">(),</span> <span class="n">InventoryRepo</span><span class="p">())</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>    <span class="k">if</span> <span class="n">created</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Transaction failed&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>    <span class="k">return</span> <span class="n">created</span>
 </code></pre></div>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li><strong>Return values:</strong> Each callable can return whatever you need (inserted document, stats, etc.). The helper collects them in order.</li>
-<li><strong>Error handling:</strong> Raising any exception inside a callable will abort the transaction automatically.</li>
-<li><strong>Read‑only ops:</strong> You can also run queries inside the transaction – just pass <code>session=session</code> to the <code>find_one</code>/<code>find</code> calls.</li>
-<li><strong>Testing:</strong> In unit tests you can mock <code>TransactionManager.start_session</code> to ensure the helpers are called.</li>
+<li><strong>Return values:</strong> each callable can return whatever you need; results are collected in the same order.</li>
+<li><strong>Errors:</strong> raise inside any callable → the whole transaction aborts (session rolls back) and the exception propagates.</li>
+<li><strong>Reads inside a transaction:</strong> pass <code>session=session</code> to <code>find_one</code>/<code>find</code> too.</li>
+<li><strong>Testing (no Mongo):</strong> <code>monkeypatch</code> a fake client on <code>mongo_ops.transactions.MongoConnectionManager.get_client</code> and stub <code>start_session</code> — see <code>tests/test_transactions.py</code>.</li>
+<li>Repo <strong>models</strong> still carry <code>created_at</code>/<code>updated_at</code>; for raw collection inserts inside the transaction you set them manually (as shown).</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../03_transactions/">03 – Transactions</a> · <a href="../14_testing_guide/">14 – Testing guide</a> · <a href="../../06_error_handling/">Error Handling</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/13_index_creation/index.html b/mongo-ops/03_use_cases/13_index_creation/index.html
index 9f58abc..1fa3b8a 100644
--- a/mongo-ops/03_use_cases/13_index_creation/index.html
+++ b/mongo-ops/03_use_cases/13_index_creation/index.html
@@ -74,7 +74,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#use-case-13-declaring-indexes-singlefield-composite-unique" class="md-skip">
+        <a href="#use-case-13-declaring-indexes-single-field-composite-unique" class="md-skip">
           Skip to content
         </a>
       
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -851,7 +851,7 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
@@ -873,6 +873,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1026,11 +1035,10 @@
 
 
 
-<h1 id="use-case-13-declaring-indexes-singlefield-composite-unique">Use Case 13: Declaring Indexes (Single‑field, Composite, Unique)</h1>
-<p><strong>Scenario:</strong>
-You want to ensure your collection has the right indexes for fast queries and data integrity. This doc shows how to register models with different index configurations using <code>ModelRegistry.register</code> and have them created automatically during startup.</p>
+<h1 id="use-case-13-declaring-indexes-single-field-composite-unique">Use Case 13: Declaring Indexes (Single-Field, Composite, Unique)</h1>
+<p><strong>Scenario:</strong> Ensure each collection has the right indexes for fast queries and data integrity — declared in one place and created at startup.</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1040,87 +1048,93 @@ You want to ensure your collection has the right indexes for fast queries and da
 </thead>
 <tbody>
 <tr>
-<td><code>ModelRegistry.register</code> (indexes argument)</td>
-<td>Accepts a list of index specifications. Each spec can be a tuple <code>(field, direction)</code> or a full dict with <code>keys</code> and optional options (e.g., <code>unique</code>).</td>
+<td><code>ModelRegistry.register(indexes=...)</code></td>
+<td>Each spec is passed <strong>as-is</strong> to pymongo <code>create_index</code>. Supported forms: tuple <code>("field", direction)</code>, compound list <code>[("a", 1), ("b", -1)]</code>, or a dict with <code>keys</code> + <code>options</code>.</td>
 </tr>
 <tr>
 <td><code>ModelRegistry.initialize_all</code></td>
-<td>Scans all registered collections and creates the defined indexes on application start‑up.</td>
+<td>Creates every registered index during startup (idempotent — <code>create_index</code> skips existing indexes).</td>
 </tr>
 </tbody>
 </table>
 <hr />
 <h2 id="example">🚀 Example</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">BaseDocument</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pymongo</span><span class="w"> </span><span class="kn">import</span> <span class="n">ASCENDING</span><span class="p">,</span> <span class="n">DESCENDING</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="c1"># 1️⃣ Simple single‑field index (e.g., email lookup)</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pymongo</span><span class="w"> </span><span class="kn">import</span> <span class="n">ASCENDING</span><span class="p">,</span> <span class="n">DESCENDING</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">ModelRegistry</span><span class="p">,</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
 <a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
 <a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">)],</span>  <span class="c1"># creates an index on &quot;email&quot;</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="p">)</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPost</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">created_at</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
 <a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="c1"># 2️⃣ Composite index (e.g., queries filtering by user and creation date)</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="k">class</span><span class="w"> </span><span class="nc">BlogPost</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="n">created_at</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="n">model</span><span class="o">=</span><span class="n">BlogPost</span><span class="p">,</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[[(</span><span class="s2">&quot;author_id&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="n">DESCENDING</span><span class="p">)]],</span>  <span class="c1"># compound index</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="p">)</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="c1"># 3️⃣ Unique index (e.g., enforce unique usernames)</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>        <span class="p">{</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>            <span class="s2">&quot;keys&quot;</span><span class="p">:</span> <span class="p">[(</span><span class="s2">&quot;username&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">)],</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>            <span class="s2">&quot;options&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;unique&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;uq_username&quot;</span><span class="p">},</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="p">}</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="p">],</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a><span class="p">)</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a><span class="c1"># 4️⃣ Initialise all indexes during FastAPI startup</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a><span class="kn">from</span><span class="w"> </span><span class="nn">contextlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">asynccontextmanager</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="k">class</span><span class="w"> </span><span class="nc">Passenger</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">seat</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="c1"># 1️⃣ Single-field index — email lookups.</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;users&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>    <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">)],</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="p">)</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="c1"># 2️⃣ Composite index — queries filtering by author + creation date.</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="n">model</span><span class="o">=</span><span class="n">BlogPost</span><span class="p">,</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[[(</span><span class="s2">&quot;author_id&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">),</span> <span class="p">(</span><span class="s2">&quot;created_at&quot;</span><span class="p">,</span> <span class="n">DESCENDING</span><span class="p">)]],</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a><span class="p">)</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a><span class="c1"># 3️⃣ Unique index with a custom name — enforce unique emails.</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;passengers&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="n">model</span><span class="o">=</span><span class="n">Passenger</span><span class="p">,</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="n">indexes</span><span class="o">=</span><span class="p">[</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="p">{</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>            <span class="s2">&quot;keys&quot;</span><span class="p">:</span> <span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="n">ASCENDING</span><span class="p">)],</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="s2">&quot;options&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;unique&quot;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;uq_passenger_email&quot;</span><span class="p">},</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="p">}</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>    <span class="p">],</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a><span class="p">)</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a><span class="c1"># 4️⃣ Everything is created on startup.</span>
 <a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a><span class="nd">@asynccontextmanager</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">app</span><span class="p">):</span>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">lifespan</span><span class="p">(</span><span class="n">_app</span><span class="p">):</span>
 <a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>    <span class="k">async</span> <span class="k">with</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">lifespan</span><span class="p">(</span>
 <a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
 <a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;mydb&quot;</span><span class="p">,</span>
 <a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>    <span class="p">):</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="c1"># This will create every index declared above (if it does not already exist)</span>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="k">yield</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>        <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">()</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>        <span class="k">yield</span>
 </code></pre></div>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li><strong>Idempotence:</strong> <code>initialize_all</code> uses <code>create_index</code>, which is safe to run multiple times – MongoDB will skip creation if the index already exists.</li>
-<li><strong>Index options:</strong> You can also set <code>expireAfterSeconds</code> for TTL indexes, <code>sparse</code> for sparse indexes, etc., by adding them to the <code>options</code> dict.</li>
-<li><strong>Verification:</strong> After the app starts, you can verify indexes with the Mongo shell:
-  <div class="language-js highlight"><span class="filename">JavaScript</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nx">db</span><span class="p">.</span><span class="o">&lt;</span><span class="nx">collection</span><span class="o">&gt;</span><span class="p">.</span><span class="nx">getIndexes</span><span class="p">()</span>
-</code></pre></div></li>
+<li>Every spec passes through to <code>collection.create_index(spec)</code> — so MongoDB options like <code>unique</code>, <code>sparse</code>, and <code>expireAfterSeconds</code> (TTL) belong in the <code>options</code> dict.</li>
+<li>Idempotent by construction: <code>create_index</code> is a no-op when a same-shape index already exists.</li>
+<li>Verify with the Mongo shell:</li>
+</ul>
+<div class="language-js highlight"><span class="filename">JavaScript</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="nx">db</span><span class="p">.</span><span class="o">&lt;</span><span class="nx">collection</span><span class="o">&gt;</span><span class="p">.</span><span class="nx">getIndexes</span><span class="p">()</span>
+</code></pre></div>
+<ul>
+<li>A <strong>unique</strong> index on an already-duplicated field will fail with <code>DuplicateKeyError</code> on startup — clean the data first.</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../01_basic_crud/">01 – Basic CRUD</a> · <a href="../06_multi_model/">06 – Multi-model</a> · <a href="../../02_components/">Components: ModelRegistry</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/03_use_cases/14_testing_guide/index.html b/mongo-ops/03_use_cases/14_testing_guide/index.html
index 29ab01d..ab7bf77 100644
--- a/mongo-ops/03_use_cases/14_testing_guide/index.html
+++ b/mongo-ops/03_use_cases/14_testing_guide/index.html
@@ -74,7 +74,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#use-case-14-testing-guide-mocking-motor-population-engine" class="md-skip">
+        <a href="#use-case-14-testing-guide-mocking-motor-cache-registry-transactions" class="md-skip">
           Skip to content
         </a>
       
@@ -457,7 +457,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -874,16 +874,16 @@
         <li class="md-nav__item">
   <a href="#whats-new" class="md-nav__link">
     <span class="md-ellipsis">
-      📦 What’s New?
+      📦 What's New?
     </span>
   </a>
   
 </li>
       
         <li class="md-nav__item">
-  <a href="#example-test-boilerplate" class="md-nav__link">
+  <a href="#example-boilerplate" class="md-nav__link">
     <span class="md-ellipsis">
-      🚀 Example Test Boilerplate
+      🚀 Example Boilerplate
     </span>
   </a>
   
@@ -896,6 +896,15 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
+  
 </li>
       
     </ul>
@@ -1026,11 +1035,10 @@
 
 
 
-<h1 id="use-case-14-testing-guide-mocking-motor-population-engine">Use Case 14: Testing Guide – Mocking Motor &amp; Population Engine</h1>
-<p><strong>Scenario:</strong>
-You want to write unit tests for repositories that use async Motor collections and the <code>PopulationEngine</code> without connecting to a real MongoDB instance.</p>
+<h1 id="use-case-14-testing-guide-mocking-motor-cache-registry-transactions">Use Case 14: Testing Guide — Mocking Motor, Cache, Registry &amp; Transactions</h1>
+<p><strong>Scenario:</strong> Write unit tests that never touch a real MongoDB — mock the collection, the cache backend, and the client, exactly like the library's own test suite (<code>tests/</code>).</p>
 <hr />
-<h2 id="whats-new">📦 What’s New?</h2>
+<h2 id="whats-new">📦 What's New?</h2>
 <table>
 <thead>
 <tr>
@@ -1040,132 +1048,204 @@ You want to write unit tests for repositories that use async Motor collections a
 </thead>
 <tbody>
 <tr>
-<td><code>AsyncMock</code> for collections</td>
-<td>Allows you to stub <code>find_one</code>, <code>insert_one</code>, etc., and control returned data.</td>
+<td><code>AsyncMock</code> collections</td>
+<td>Stub <code>find_one</code>, <code>insert_one</code>, <code>find_one_and_update</code>, cursor chains.</td>
 </tr>
 <tr>
 <td>Patching <code>MongoConnectionManager.get_database</code></td>
-<td>Redirects repository initialization to a mock collection.</td>
+<td>Gives repositories a mock collection without a live connection.</td>
 </tr>
 <tr>
-<td>Mocking <code>PopulationEngine</code></td>
-<td>Replace the real engine with a lightweight stub that returns pre‑crafted objects.</td>
+<td><code>monkeypatch</code> on <code>get_client</code></td>
+<td>Fakes sessions for <code>TransactionManager</code> tests.</td>
 </tr>
 <tr>
-<td>Example test files</td>
-<td><code>tests/test_populating_repository.py</code> and <code>tests/test_transactions.py</code> are used as reference implementations.</td>
+<td>Reference tests</td>
+<td><code>tests/test_populating_repository.py</code>, <code>tests/test_cache.py</code>, <code>tests/test_registry.py</code>, <code>tests/test_transactions.py</code>.</td>
 </tr>
 </tbody>
 </table>
 <hr />
-<h2 id="example-test-boilerplate">🚀 Example Test Boilerplate</h2>
+<h2 id="example-boilerplate">🚀 Example Boilerplate</h2>
 <div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">import</span><span class="w"> </span><span class="nn">pytest</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">unittest.mock</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncMock</span><span class="p">,</span> <span class="n">patch</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.repository</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulatingRepository</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># 1️⃣ Define simple models (same as in the library tests)</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">class</span><span class="w"> </span><span class="nc">Profile</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">avatar_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>    <span class="n">profile_id</span><span class="p">:</span> <span class="n">ObjectId</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="c1"># 2️⃣ Fixture – mock Motor collection</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="k">def</span><span class="w"> </span><span class="nf">mock_collection</span><span class="p">():</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>    <span class="k">return</span> <span class="n">AsyncMock</span><span class="p">()</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="c1"># 3️⃣ Fixture – mock PopulationEngine (optional)</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="k">def</span><span class="w"> </span><span class="nf">engine</span><span class="p">():</span>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="c1"># Provide a real engine but replace the repo for &quot;profiles&quot; with a mock</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="n">profile_repo</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="k">return</span> <span class="n">PopulationEngine</span><span class="p">({</span><span class="s2">&quot;profiles&quot;</span><span class="p">:</span> <span class="n">profile_repo</span><span class="p">})</span>
-<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a><span class="c1"># 4️⃣ Fixture – repository under test</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="k">def</span><span class="w"> </span><span class="nf">repo</span><span class="p">(</span><span class="n">mock_collection</span><span class="p">,</span> <span class="n">engine</span><span class="p">):</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s2">&quot;mongo_ops.repository.MongoConnectionManager.get_database&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_db</span><span class="p">:</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="n">mock_db</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="fm">__getitem__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">mock_collection</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="n">repo</span> <span class="o">=</span> <span class="n">PopulatingRepository</span><span class="p">(</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="s2">&quot;users&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>            <span class="n">User</span><span class="p">,</span>
-<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
-<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span>
-<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>                <span class="n">PopulateRule</span><span class="p">(</span>
-<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>                    <span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>                    <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>                    <span class="n">ref_field</span><span class="o">=</span><span class="s2">&quot;profile_id&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>                <span class="p">)</span>
-<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>            <span class="p">],</span>
-<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>        <span class="p">)</span>
-<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>        <span class="n">repo</span><span class="o">.</span><span class="n">collection</span> <span class="o">=</span> <span class="n">mock_collection</span>
-<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a>        <span class="k">return</span> <span class="n">repo</span>
-<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>
-<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a><span class="c1"># 5️⃣ Test – `get_by_id` populates the related document</span>
-<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
-<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_get_by_id_populates</span><span class="p">(</span><span class="n">repo</span><span class="p">,</span> <span class="n">mock_collection</span><span class="p">,</span> <span class="n">engine</span><span class="p">):</span>
-<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>    <span class="c1"># Arrange – user document returned from the DB</span>
-<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>    <span class="n">uid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">()</span>
-<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="n">pid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">()</span>
-<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>    <span class="n">mock_collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">{</span>
-<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>        <span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">uid</span><span class="p">,</span>
-<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>        <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Alice&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>        <span class="s2">&quot;profile_id&quot;</span><span class="p">:</span> <span class="n">pid</span><span class="p">,</span>
-<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>        <span class="s2">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>        <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>    <span class="p">}</span>
-<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>    <span class="c1"># Mock the profile repo to return a concrete Profile instance</span>
-<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>    <span class="n">engine</span><span class="o">.</span><span class="n">_repos</span><span class="p">[</span><span class="s2">&quot;profiles&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">get_by_id</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">Profile</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">pid</span><span class="p">,</span> <span class="n">avatar_url</span><span class="o">=</span><span class="s2">&quot;pic.png&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a>
-<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a>    <span class="c1"># Act</span>
-<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a>    <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">uid</span><span class="p">)</span>
-<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a>
-<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a>    <span class="c1"># Assert</span>
-<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="k">assert</span> <span class="n">result</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
-<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>    <span class="k">assert</span> <span class="n">result</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s2">&quot;Alice&quot;</span>
-<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>    <span class="k">assert</span> <span class="n">result</span><span class="o">.</span><span class="n">profile</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
-<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>    <span class="k">assert</span> <span class="n">result</span><span class="o">.</span><span class="n">profile</span><span class="o">.</span><span class="n">avatar_url</span> <span class="o">==</span> <span class="s2">&quot;pic.png&quot;</span>
-<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a>
-<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a><span class="c1"># 6️⃣ Test – transaction helper uses the real `TransactionManager`</span>
-<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a><span class="c1"># ----------------------------------------------------------------------</span>
-<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.transactions</span><span class="w"> </span><span class="kn">import</span> <span class="n">TransactionManager</span>
-<a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>
-<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
-<a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_execute_transaction</span><span class="p">(</span><span class="n">monkeypatch</span><span class="p">):</span>
-<a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a>    <span class="c1"># Fake a Motor client session that records calls</span>
-<a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">fake_op</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
-<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>        <span class="k">return</span> <span class="s2">&quot;ok&quot;</span>
-<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a>    <span class="c1"># Execute with the helper – it should return a list with the result</span>
-<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a>    <span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">execute_transaction</span><span class="p">([</span><span class="n">fake_op</span><span class="p">])</span>
-<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a>    <span class="k">assert</span> <span class="n">results</span> <span class="o">==</span> <span class="p">[</span><span class="s2">&quot;ok&quot;</span><span class="p">]</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">unittest.mock</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncMock</span><span class="p">,</span> <span class="n">MagicMock</span><span class="p">,</span> <span class="n">patch</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">CacheConfig</span><span class="p">,</span> <span class="n">InMemoryCacheBackend</span><span class="p">,</span> <span class="n">CachedBaseRepository</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.registry</span><span class="w"> </span><span class="kn">import</span> <span class="n">ModelRegistry</span>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.populate</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulateRule</span><span class="p">,</span> <span class="n">PopulationEngine</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.repository</span><span class="w"> </span><span class="kn">import</span> <span class="n">PopulatingRepository</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a><span class="c1"># 1. Models (same shape as the library tests)</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="k">class</span><span class="w"> </span><span class="nc">Profile</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="n">avatar_url</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>    <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">profile</span><span class="p">:</span> <span class="n">Profile</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># ObjectId in DB, Profile in memory</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a><span class="c1"># 2. Fixtures</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a><span class="k">def</span><span class="w"> </span><span class="nf">mock_collection</span><span class="p">():</span>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>    <span class="k">return</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="k">def</span><span class="w"> </span><span class="nf">engine</span><span class="p">():</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">profile_repo</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="k">return</span> <span class="n">PopulationEngine</span><span class="p">({</span><span class="s2">&quot;profiles&quot;</span><span class="p">:</span> <span class="n">profile_repo</span><span class="p">})</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="k">def</span><span class="w"> </span><span class="nf">repo</span><span class="p">(</span><span class="n">mock_collection</span><span class="p">,</span> <span class="n">engine</span><span class="p">):</span>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>    <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s2">&quot;mongo_ops.repository.MongoConnectionManager.get_database&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_db</span><span class="p">:</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>        <span class="n">mock_db</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="fm">__getitem__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>        <span class="n">r</span> <span class="o">=</span> <span class="n">PopulatingRepository</span><span class="p">(</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>            <span class="s2">&quot;users&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>            <span class="n">User</span><span class="p">,</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>            <span class="n">population_engine</span><span class="o">=</span><span class="n">engine</span><span class="p">,</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>            <span class="n">populate_rules</span><span class="o">=</span><span class="p">[</span><span class="n">PopulateRule</span><span class="p">(</span><span class="n">field_name</span><span class="o">=</span><span class="s2">&quot;profile&quot;</span><span class="p">,</span> <span class="n">collection_name</span><span class="o">=</span><span class="s2">&quot;profiles&quot;</span><span class="p">)],</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="p">)</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>        <span class="n">r</span><span class="o">.</span><span class="n">collection</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="k">return</span> <span class="n">r</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a><span class="c1"># 3. Population — get_by_id resolves the reference</span>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-56" name="__codelineno-0-56" href="#__codelineno-0-56"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_get_by_id_populates</span><span class="p">(</span><span class="n">repo</span><span class="p">,</span> <span class="n">mock_collection</span><span class="p">,</span> <span class="n">engine</span><span class="p">):</span>
+<a id="__codelineno-0-57" name="__codelineno-0-57" href="#__codelineno-0-57"></a>    <span class="n">uid</span><span class="p">,</span> <span class="n">pid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">(),</span> <span class="n">ObjectId</span><span class="p">()</span>
+<a id="__codelineno-0-58" name="__codelineno-0-58" href="#__codelineno-0-58"></a>    <span class="n">mock_collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-0-59" name="__codelineno-0-59" href="#__codelineno-0-59"></a>        <span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">uid</span><span class="p">,</span>
+<a id="__codelineno-0-60" name="__codelineno-0-60" href="#__codelineno-0-60"></a>        <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;Alice&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-61" name="__codelineno-0-61" href="#__codelineno-0-61"></a>        <span class="s2">&quot;profile&quot;</span><span class="p">:</span> <span class="n">pid</span><span class="p">,</span>                                   <span class="c1"># ObjectId stored in DB</span>
+<a id="__codelineno-0-62" name="__codelineno-0-62" href="#__codelineno-0-62"></a>        <span class="s2">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-63" name="__codelineno-0-63" href="#__codelineno-0-63"></a>        <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-64" name="__codelineno-0-64" href="#__codelineno-0-64"></a>    <span class="p">}</span>
+<a id="__codelineno-0-65" name="__codelineno-0-65" href="#__codelineno-0-65"></a>    <span class="n">engine</span><span class="o">.</span><span class="n">_repos</span><span class="p">[</span><span class="s2">&quot;profiles&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">get_by_id</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">Profile</span><span class="p">(</span><span class="nb">id</span><span class="o">=</span><span class="n">pid</span><span class="p">,</span> <span class="n">avatar_url</span><span class="o">=</span><span class="s2">&quot;pic.png&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-66" name="__codelineno-0-66" href="#__codelineno-0-66"></a>
+<a id="__codelineno-0-67" name="__codelineno-0-67" href="#__codelineno-0-67"></a>    <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">uid</span><span class="p">)</span>
+<a id="__codelineno-0-68" name="__codelineno-0-68" href="#__codelineno-0-68"></a>
+<a id="__codelineno-0-69" name="__codelineno-0-69" href="#__codelineno-0-69"></a>    <span class="k">assert</span> <span class="n">result</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+<a id="__codelineno-0-70" name="__codelineno-0-70" href="#__codelineno-0-70"></a>    <span class="k">assert</span> <span class="n">result</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s2">&quot;Alice&quot;</span>
+<a id="__codelineno-0-71" name="__codelineno-0-71" href="#__codelineno-0-71"></a>    <span class="k">assert</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">profile</span><span class="p">,</span> <span class="n">Profile</span><span class="p">)</span>
+<a id="__codelineno-0-72" name="__codelineno-0-72" href="#__codelineno-0-72"></a>    <span class="k">assert</span> <span class="n">result</span><span class="o">.</span><span class="n">profile</span><span class="o">.</span><span class="n">avatar_url</span> <span class="o">==</span> <span class="s2">&quot;pic.png&quot;</span>
+<a id="__codelineno-0-73" name="__codelineno-0-73" href="#__codelineno-0-73"></a>
+<a id="__codelineno-0-74" name="__codelineno-0-74" href="#__codelineno-0-74"></a>
+<a id="__codelineno-0-75" name="__codelineno-0-75" href="#__codelineno-0-75"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-76" name="__codelineno-0-76" href="#__codelineno-0-76"></a><span class="c1"># 4. Patch FK guard</span>
+<a id="__codelineno-0-77" name="__codelineno-0-77" href="#__codelineno-0-77"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-78" name="__codelineno-0-78" href="#__codelineno-0-78"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-79" name="__codelineno-0-79" href="#__codelineno-0-79"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_patch_rejects_fk_field</span><span class="p">(</span><span class="n">repo</span><span class="p">):</span>
+<a id="__codelineno-0-80" name="__codelineno-0-80" href="#__codelineno-0-80"></a>    <span class="k">with</span> <span class="n">pytest</span><span class="o">.</span><span class="n">raises</span><span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="n">match</span><span class="o">=</span><span class="s2">&quot;Cannot patch FK fields&quot;</span><span class="p">):</span>
+<a id="__codelineno-0-81" name="__codelineno-0-81" href="#__codelineno-0-81"></a>        <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">patch</span><span class="p">(</span><span class="n">ObjectId</span><span class="p">(),</span> <span class="p">{</span><span class="s2">&quot;profile&quot;</span><span class="p">:</span> <span class="n">ObjectId</span><span class="p">()})</span>
+<a id="__codelineno-0-82" name="__codelineno-0-82" href="#__codelineno-0-82"></a>
+<a id="__codelineno-0-83" name="__codelineno-0-83" href="#__codelineno-0-83"></a>
+<a id="__codelineno-0-84" name="__codelineno-0-84" href="#__codelineno-0-84"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-85" name="__codelineno-0-85" href="#__codelineno-0-85"></a><span class="c1"># 5. Registry — index specs pass through to create_index</span>
+<a id="__codelineno-0-86" name="__codelineno-0-86" href="#__codelineno-0-86"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-87" name="__codelineno-0-87" href="#__codelineno-0-87"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-88" name="__codelineno-0-88" href="#__codelineno-0-88"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_initialize_all_creates_indexes</span><span class="p">():</span>
+<a id="__codelineno-0-89" name="__codelineno-0-89" href="#__codelineno-0-89"></a>    <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">indexes</span><span class="o">=</span><span class="p">[(</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">)])</span>
+<a id="__codelineno-0-90" name="__codelineno-0-90" href="#__codelineno-0-90"></a>
+<a id="__codelineno-0-91" name="__codelineno-0-91" href="#__codelineno-0-91"></a>    <span class="n">fake_collection</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-92" name="__codelineno-0-92" href="#__codelineno-0-92"></a>    <span class="k">await</span> <span class="n">ModelRegistry</span><span class="o">.</span><span class="n">initialize_all</span><span class="p">(</span><span class="n">db</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;users&quot;</span><span class="p">:</span> <span class="n">fake_collection</span><span class="p">})</span>
+<a id="__codelineno-0-93" name="__codelineno-0-93" href="#__codelineno-0-93"></a>
+<a id="__codelineno-0-94" name="__codelineno-0-94" href="#__codelineno-0-94"></a>    <span class="n">fake_collection</span><span class="o">.</span><span class="n">create_index</span><span class="o">.</span><span class="n">assert_awaited_once_with</span><span class="p">((</span><span class="s2">&quot;email&quot;</span><span class="p">,</span> <span class="mi">1</span><span class="p">))</span>
+<a id="__codelineno-0-95" name="__codelineno-0-95" href="#__codelineno-0-95"></a>
+<a id="__codelineno-0-96" name="__codelineno-0-96" href="#__codelineno-0-96"></a>
+<a id="__codelineno-0-97" name="__codelineno-0-97" href="#__codelineno-0-97"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-98" name="__codelineno-0-98" href="#__codelineno-0-98"></a><span class="c1"># 6. Cached repository — cache-first reads + invalidation</span>
+<a id="__codelineno-0-99" name="__codelineno-0-99" href="#__codelineno-0-99"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-100" name="__codelineno-0-100" href="#__codelineno-0-100"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-101" name="__codelineno-0-101" href="#__codelineno-0-101"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_cached_get_by_id_populates_cache</span><span class="p">():</span>
+<a id="__codelineno-0-102" name="__codelineno-0-102" href="#__codelineno-0-102"></a>    <span class="n">backend</span> <span class="o">=</span> <span class="n">InMemoryCacheBackend</span><span class="p">(</span>
+<a id="__codelineno-0-103" name="__codelineno-0-103" href="#__codelineno-0-103"></a>        <span class="n">max_entries</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span> <span class="n">default_ttl</span><span class="o">=</span><span class="mi">300</span><span class="p">,</span> <span class="n">cleanup_interval</span><span class="o">=</span><span class="mi">9999</span>
+<a id="__codelineno-0-104" name="__codelineno-0-104" href="#__codelineno-0-104"></a>    <span class="p">)</span>
+<a id="__codelineno-0-105" name="__codelineno-0-105" href="#__codelineno-0-105"></a>    <span class="k">await</span> <span class="n">backend</span><span class="o">.</span><span class="n">initialize</span><span class="p">()</span>
+<a id="__codelineno-0-106" name="__codelineno-0-106" href="#__codelineno-0-106"></a>    <span class="k">try</span><span class="p">:</span>
+<a id="__codelineno-0-107" name="__codelineno-0-107" href="#__codelineno-0-107"></a>        <span class="k">with</span> <span class="n">patch</span><span class="p">(</span><span class="s2">&quot;mongo_ops.repository.MongoConnectionManager.get_database&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_db</span><span class="p">:</span>
+<a id="__codelineno-0-108" name="__codelineno-0-108" href="#__codelineno-0-108"></a>            <span class="n">mock_collection</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-109" name="__codelineno-0-109" href="#__codelineno-0-109"></a>            <span class="n">mock_db</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="fm">__getitem__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-110" name="__codelineno-0-110" href="#__codelineno-0-110"></a>            <span class="n">repo</span> <span class="o">=</span> <span class="n">CachedBaseRepository</span><span class="p">(</span>
+<a id="__codelineno-0-111" name="__codelineno-0-111" href="#__codelineno-0-111"></a>                <span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">,</span> <span class="n">backend</span><span class="p">,</span> <span class="n">CacheConfig</span><span class="p">(</span><span class="n">enabled</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+<a id="__codelineno-0-112" name="__codelineno-0-112" href="#__codelineno-0-112"></a>            <span class="p">)</span>
+<a id="__codelineno-0-113" name="__codelineno-0-113" href="#__codelineno-0-113"></a>            <span class="n">repo</span><span class="o">.</span><span class="n">collection</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-114" name="__codelineno-0-114" href="#__codelineno-0-114"></a>
+<a id="__codelineno-0-115" name="__codelineno-0-115" href="#__codelineno-0-115"></a>            <span class="n">oid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">()</span>
+<a id="__codelineno-0-116" name="__codelineno-0-116" href="#__codelineno-0-116"></a>            <span class="n">mock_collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-0-117" name="__codelineno-0-117" href="#__codelineno-0-117"></a>                <span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">oid</span><span class="p">,</span>
+<a id="__codelineno-0-118" name="__codelineno-0-118" href="#__codelineno-0-118"></a>                <span class="s2">&quot;name&quot;</span><span class="p">:</span> <span class="s2">&quot;cached&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-119" name="__codelineno-0-119" href="#__codelineno-0-119"></a>                <span class="s2">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-120" name="__codelineno-0-120" href="#__codelineno-0-120"></a>                <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-121" name="__codelineno-0-121" href="#__codelineno-0-121"></a>            <span class="p">}</span>
+<a id="__codelineno-0-122" name="__codelineno-0-122" href="#__codelineno-0-122"></a>
+<a id="__codelineno-0-123" name="__codelineno-0-123" href="#__codelineno-0-123"></a>            <span class="n">first</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">oid</span><span class="p">)</span>
+<a id="__codelineno-0-124" name="__codelineno-0-124" href="#__codelineno-0-124"></a>            <span class="k">assert</span> <span class="n">first</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+<a id="__codelineno-0-125" name="__codelineno-0-125" href="#__codelineno-0-125"></a>
+<a id="__codelineno-0-126" name="__codelineno-0-126" href="#__codelineno-0-126"></a>            <span class="n">mock_collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="kc">None</span>  <span class="c1"># DB now &quot;empty&quot;</span>
+<a id="__codelineno-0-127" name="__codelineno-0-127" href="#__codelineno-0-127"></a>            <span class="n">second</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">oid</span><span class="p">)</span>            <span class="c1"># served from cache</span>
+<a id="__codelineno-0-128" name="__codelineno-0-128" href="#__codelineno-0-128"></a>
+<a id="__codelineno-0-129" name="__codelineno-0-129" href="#__codelineno-0-129"></a>            <span class="k">assert</span> <span class="n">second</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+<a id="__codelineno-0-130" name="__codelineno-0-130" href="#__codelineno-0-130"></a>            <span class="k">assert</span> <span class="n">second</span><span class="o">.</span><span class="n">name</span> <span class="o">==</span> <span class="s2">&quot;cached&quot;</span>
+<a id="__codelineno-0-131" name="__codelineno-0-131" href="#__codelineno-0-131"></a>            <span class="n">mock_collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">assert_awaited_once</span><span class="p">()</span>  <span class="c1"># only one DB read</span>
+<a id="__codelineno-0-132" name="__codelineno-0-132" href="#__codelineno-0-132"></a>    <span class="k">finally</span><span class="p">:</span>
+<a id="__codelineno-0-133" name="__codelineno-0-133" href="#__codelineno-0-133"></a>        <span class="k">await</span> <span class="n">backend</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
+<a id="__codelineno-0-134" name="__codelineno-0-134" href="#__codelineno-0-134"></a>
+<a id="__codelineno-0-135" name="__codelineno-0-135" href="#__codelineno-0-135"></a>
+<a id="__codelineno-0-136" name="__codelineno-0-136" href="#__codelineno-0-136"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-137" name="__codelineno-0-137" href="#__codelineno-0-137"></a><span class="c1"># 7. Transactions — fake the client&#39;s start_session</span>
+<a id="__codelineno-0-138" name="__codelineno-0-138" href="#__codelineno-0-138"></a><span class="c1"># ----------------------------------------------------------------------</span>
+<a id="__codelineno-0-139" name="__codelineno-0-139" href="#__codelineno-0-139"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.transactions</span><span class="w"> </span><span class="kn">import</span> <span class="n">TransactionManager</span>
+<a id="__codelineno-0-140" name="__codelineno-0-140" href="#__codelineno-0-140"></a>
+<a id="__codelineno-0-141" name="__codelineno-0-141" href="#__codelineno-0-141"></a>
+<a id="__codelineno-0-142" name="__codelineno-0-142" href="#__codelineno-0-142"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-143" name="__codelineno-0-143" href="#__codelineno-0-143"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_execute_transaction</span><span class="p">(</span><span class="n">monkeypatch</span><span class="p">):</span>
+<a id="__codelineno-0-144" name="__codelineno-0-144" href="#__codelineno-0-144"></a>    <span class="n">session_ctx</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-145" name="__codelineno-0-145" href="#__codelineno-0-145"></a>    <span class="n">session_ctx</span><span class="o">.</span><span class="fm">__aenter__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-146" name="__codelineno-0-146" href="#__codelineno-0-146"></a>    <span class="n">session_ctx</span><span class="o">.</span><span class="fm">__aexit__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="kc">None</span>
+<a id="__codelineno-0-147" name="__codelineno-0-147" href="#__codelineno-0-147"></a>
+<a id="__codelineno-0-148" name="__codelineno-0-148" href="#__codelineno-0-148"></a>    <span class="n">client</span> <span class="o">=</span> <span class="n">MagicMock</span><span class="p">()</span>
+<a id="__codelineno-0-149" name="__codelineno-0-149" href="#__codelineno-0-149"></a>    <span class="n">client</span><span class="o">.</span><span class="n">start_session</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">(</span><span class="n">return_value</span><span class="o">=</span><span class="n">session_ctx</span><span class="p">)</span>
+<a id="__codelineno-0-150" name="__codelineno-0-150" href="#__codelineno-0-150"></a>
+<a id="__codelineno-0-151" name="__codelineno-0-151" href="#__codelineno-0-151"></a>    <span class="c1"># NOTE: start_transaction must return a context manager, not a coroutine.</span>
+<a id="__codelineno-0-152" name="__codelineno-0-152" href="#__codelineno-0-152"></a>    <span class="n">async_session</span> <span class="o">=</span> <span class="n">session_ctx</span><span class="o">.</span><span class="fm">__aenter__</span><span class="o">.</span><span class="n">return_value</span>
+<a id="__codelineno-0-153" name="__codelineno-0-153" href="#__codelineno-0-153"></a>    <span class="n">async_session</span><span class="o">.</span><span class="n">start_transaction</span> <span class="o">=</span> <span class="k">lambda</span> <span class="o">**</span><span class="n">_</span><span class="p">:</span> <span class="n">session_ctx</span>
+<a id="__codelineno-0-154" name="__codelineno-0-154" href="#__codelineno-0-154"></a>
+<a id="__codelineno-0-155" name="__codelineno-0-155" href="#__codelineno-0-155"></a>    <span class="n">monkeypatch</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span>
+<a id="__codelineno-0-156" name="__codelineno-0-156" href="#__codelineno-0-156"></a>        <span class="s2">&quot;mongo_ops.transactions.MongoConnectionManager.get_client&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-157" name="__codelineno-0-157" href="#__codelineno-0-157"></a>        <span class="k">lambda</span><span class="p">:</span> <span class="n">client</span><span class="p">,</span>
+<a id="__codelineno-0-158" name="__codelineno-0-158" href="#__codelineno-0-158"></a>    <span class="p">)</span>
+<a id="__codelineno-0-159" name="__codelineno-0-159" href="#__codelineno-0-159"></a>
+<a id="__codelineno-0-160" name="__codelineno-0-160" href="#__codelineno-0-160"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">fake_op</span><span class="p">(</span><span class="n">session</span><span class="p">):</span>
+<a id="__codelineno-0-161" name="__codelineno-0-161" href="#__codelineno-0-161"></a>        <span class="k">return</span> <span class="s2">&quot;ok&quot;</span>
+<a id="__codelineno-0-162" name="__codelineno-0-162" href="#__codelineno-0-162"></a>
+<a id="__codelineno-0-163" name="__codelineno-0-163" href="#__codelineno-0-163"></a>    <span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">execute_transaction</span><span class="p">([</span><span class="n">fake_op</span><span class="p">])</span>
+<a id="__codelineno-0-164" name="__codelineno-0-164" href="#__codelineno-0-164"></a>    <span class="k">assert</span> <span class="n">results</span> <span class="o">==</span> <span class="p">[</span><span class="s2">&quot;ok&quot;</span><span class="p">]</span>
 </code></pre></div>
 <hr />
 <h2 id="tips">💡 Tips</h2>
 <ul>
-<li><strong>Never hit the network:</strong> All DB calls are mocked, so tests run instantly.</li>
-<li><strong>Reuse fixtures:</strong> Keep the <code>mock_collection</code> and <code>engine</code> fixtures in a <code>conftest.py</code> file for other repo tests.</li>
-<li><strong>Coverage:</strong> The same pattern works for <code>CachedBaseRepository</code> – just mock <code>cache_backend</code> methods (<code>get</code>, <code>set</code>, <code>delete</code>).</li>
-<li><strong>AsyncTestCase:</strong> If you prefer <code>unittest</code> style, use <code>IsolatedAsyncioTestCase</code> from Python 3.8+.</li>
+<li>pytest-asyncio is already configured in <code>pyproject.toml</code> (<code>asyncio_mode = "auto"</code>), so <code>@pytest.mark.asyncio</code> tests work out of the box. Run with <code>pytest</code> (coverage reports are enabled there too).</li>
+<li><strong>Never hit the network.</strong> Keep the patches in fixtures (or a <code>conftest.py</code>) and reuse them.</li>
+<li>Mock <code>cursor</code> chains with <code>MagicMock()</code> + <code>.to_list = AsyncMock(...)</code>, exactly like <code>tests/test_repository.py</code>.</li>
+<li>For an optional integration check (real Mongo), use <code>MongoConnectionManager.lifespan</code> against a local replica set and drop the test database in teardown — keep it separate from the unit suite.</li>
+<li>The pattern works symmetrically for Redis: mock the <code>RedisCacheBackend</code> methods (<code>get</code>, <code>set</code>, <code>delete</code>) — no Redis process required.</li>
 </ul>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../08_population/">08 – Population</a> · <a href="../07_caching/">07 – Caching</a> · <a href="../12_transaction_helper/">12 – Transaction helper</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/04_best_practices/index.html b/mongo-ops/04_best_practices/index.html
index 425b578..c0a2308 100644
--- a/mongo-ops/04_best_practices/index.html
+++ b/mongo-ops/04_best_practices/index.html
@@ -454,7 +454,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -860,6 +860,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -892,6 +894,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -900,9 +904,54 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#best-practices" class="md-nav__link">
+  <a href="#layering" class="md-nav__link">
     <span class="md-ellipsis">
-      Best Practices
+      🏗️ Layering
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#lifecycle" class="md-nav__link">
+    <span class="md-ellipsis">
+      🔄 Lifecycle
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#data-performance" class="md-nav__link">
+    <span class="md-ellipsis">
+      🗄️ Data &amp; Performance
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#transactions-errors" class="md-nav__link">
+    <span class="md-ellipsis">
+      🔁 Transactions &amp; Errors
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#testing" class="md-nav__link">
+    <span class="md-ellipsis">
+      🧪 Testing
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -998,20 +1047,46 @@
 
 
 
-  <h1>Best Practices</h1>
-
-<h2 id="best-practices">Best Practices</h2>
+<h1 id="best-practices">Best Practices</h1>
+<p>Team-wide conventions for building fast, testable MongoDB services with <code>mongo-ops</code>.</p>
+<hr />
+<h2 id="layering">🏗️ Layering</h2>
 <ol>
-<li><strong>Always use ModelRegistry.register()</strong> before initializing the database connection</li>
-<li><strong>Use lifespan context manager</strong> for proper connection lifecycle</li>
-<li><strong>Inherit from BaseDocument</strong> for all models to get auto-timestamps</li>
-<li><strong>Create custom repository classes</strong> for business logic instead of mixing it with models</li>
-<li><strong>Use transactions</strong> for operations that modify multiple documents</li>
-<li><strong>Add indexes</strong> during model registration for frequently queried fields</li>
-<li><strong>Implement pagination</strong> for list endpoints to avoid performance issues</li>
-<li><strong>Use type hints</strong> for better IDE support and type checking</li>
+<li><strong>One repository per collection.</strong> Encapsulate every query the domain needs behind repository methods; keep Mongo details (<code>$regex</code>, <code>$inc</code>, projections) inside the repository.</li>
+<li><strong>Keep models thin.</strong> <code>BaseDocument</code> for the shape; use Pydantic <code>Field</code> constraints for validation; never put business rules in the model.</li>
+<li><strong>Use services for cross-repository logic.</strong> A <code>Service</code> composes multiple repositories (and <code>TransactionManager</code>) — routes stay thin.</li>
+<li><strong>Expose <code>get_many(filter=..., skip=..., limit=..., sort=...)</code></strong> instead of raw <code>find</code> for list endpoints — you get controlled pagination for free.</li>
+</ol>
+<h2 id="lifecycle">🔄 Lifecycle</h2>
+<ol>
+<li><strong>Connect once, in the lifespan.</strong> <code>MongoConnectionManager.lifespan(...)</code> (or explicit <code>connect</code>/<code>disconnect</code>) — never lazily per request.</li>
+<li><strong>Construct repositories after <code>connect()</code>.</strong> Module-level <code>Repo()</code> before connection raises <code>RuntimeError("Database not connected...")</code>. Use dependencies or construct inside the lifespan/request.</li>
+<li><strong>Order the cache lifecycle strictly:</strong> <code>set_cache_backend(backend)</code> → <code>initialize_cache()</code> (after connect, before use) → <code>shutdown_cache()</code> on exit.</li>
+<li><strong>Register all models up front</strong> via <code>ModelRegistry.register(...)</code> and let <code>initialize_all()</code> create indexes once at startup (idempotent).</li>
+</ol>
+<h2 id="data-performance">🗄️ Data &amp; Performance</h2>
+<ol>
+<li><strong>Declare indexes for every hot query.</strong> Single-field, composite, and optioned (unique/TTL) specs all work via <code>ModelRegistry.register</code> — see <a href="../03_use_cases/13_index_creation/">use case 13</a>.</li>
+<li><strong>Cache only hot, low-write <code>_id</code> reads.</strong> Use <code>CachedBaseRepository</code> for lookups-by-id; invalidate (<code>update</code>/<code>delete</code> handle it) and pick a sensible <code>default_ttl</code>.</li>
+<li><strong>Populate at the repository boundary.</strong> <code>PopulatingRepository</code> resolves refs on read and depopulates on write; do not hand-roll joins in endpoints.</li>
+<li><strong>Respect the populate invariants:</strong> rules name the field that <em>holds</em> the reference and that <em>is replaced</em>; <code>patch()</code> cannot touch FK fields — use <code>update()</code>.</li>
+</ol>
+<h2 id="transactions-errors">🔁 Transactions &amp; Errors</h2>
+<ol>
+<li><strong>Use transactions for multi-document writes.</strong> <code>TransactionManager.start_session</code> (inline) or <code>execute_transaction</code> (list of ops) — and pass <code>session=</code> to <strong>every</strong> collection call inside.</li>
+<li><strong>Handle the library's real exceptions</strong> at the edges: <code>DuplicateKeyError</code> → 409, <code>InvalidId</code> → 400, <code>CircularReferenceError</code> → 409, <code>ValueError</code> guides → 400/422 (see <a href="../06_error_handling/">Error Handling</a>).</li>
+</ol>
+<h2 id="testing">🧪 Testing</h2>
+<ol>
+<li><strong>Default to mock-based unit tests.</strong> Patch <code>MongoConnectionManager.get_database</code>, use <code>AsyncMock</code> collections and cursor chains — the whole suite runs without MongoDB (<a href="../03_use_cases/14_testing_guide/">use case 14</a>).</li>
+<li><strong>Mirror the library tests.</strong> <code>tests/test_{repository,populating_repository,cache,registry,transactions}.py</code> are canonical examples of every pattern above.</li>
+<li><strong>Use type hints end-to-end</strong> — mypy-gated CI (see pyproject) catches drift early.</li>
 </ol>
 <hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../01_overview/">Overview</a> · <a href="../02_components/">Core Components</a> · <a href="../#documentation-structure">Use Cases</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/05_patterns/index.html b/mongo-ops/05_patterns/index.html
index ce25e1d..ba159b5 100644
--- a/mongo-ops/05_patterns/index.html
+++ b/mongo-ops/05_patterns/index.html
@@ -454,7 +454,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -882,6 +882,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -914,6 +916,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -922,16 +926,6 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#common-patterns" class="md-nav__link">
-    <span class="md-ellipsis">
-      Common Patterns
-    </span>
-  </a>
-  
-    <nav class="md-nav" aria-label="Common Patterns">
-      <ul class="md-nav__list">
-        
-          <li class="md-nav__item">
   <a href="#pattern-1-service-layer-with-repository" class="md-nav__link">
     <span class="md-ellipsis">
       Pattern 1: Service Layer with Repository
@@ -939,8 +933,8 @@
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
+      
+        <li class="md-nav__item">
   <a href="#pattern-2-aggregation-pipeline" class="md-nav__link">
     <span class="md-ellipsis">
       Pattern 2: Aggregation Pipeline
@@ -948,8 +942,8 @@
   </a>
   
 </li>
-        
-          <li class="md-nav__item">
+      
+        <li class="md-nav__item">
   <a href="#pattern-3-bulk-operations" class="md-nav__link">
     <span class="md-ellipsis">
       Pattern 3: Bulk Operations
@@ -957,9 +951,22 @@
   </a>
   
 </li>
-        
-      </ul>
-    </nav>
+      
+        <li class="md-nav__item">
+  <a href="#pattern-4-transactional-multi-step-write" class="md-nav__link">
+    <span class="md-ellipsis">
+      Pattern 4: Transactional Multi-Step Write
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
+    </span>
+  </a>
   
 </li>
       
@@ -1031,47 +1038,103 @@
 
 
 
-  <h1>Common Patterns</h1>
-
-<h2 id="common-patterns">Common Patterns</h2>
-<h3 id="pattern-1-service-layer-with-repository">Pattern 1: Service Layer with Repository</h3>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserService</span><span class="p">:</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">user_repo</span><span class="p">:</span> <span class="n">UserRepository</span><span class="p">):</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span> <span class="o">=</span> <span class="n">user_repo</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">register_user</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">User</span><span class="p">:</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>        <span class="c1"># Check if user exists</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>        <span class="n">existing</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="n">email</span><span class="p">})</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>        <span class="k">if</span> <span class="n">existing</span><span class="p">:</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Email already exists&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>        <span class="c1"># Create user</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>        <span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="n">username</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="n">email</span><span class="p">)</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
+<h1 id="common-patterns">Common Patterns</h1>
+<p>Reusable code shapes built on <code>BaseRepository</code> and friends.</p>
+<hr />
+<h2 id="pattern-1-service-layer-with-repository">Pattern 1: Service Layer with Repository</h2>
+<p>Keep orchestration out of routes. A service composes one or more repositories and owns the domain rules.</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">BaseDocument</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">find_by_email</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">User</span> <span class="o">|</span> <span class="kc">None</span><span class="p">:</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>        <span class="n">doc</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="n">email</span><span class="p">})</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">model</span><span class="p">(</span><span class="o">**</span><span class="n">doc</span><span class="p">)</span> <span class="k">if</span> <span class="n">doc</span> <span class="k">else</span> <span class="kc">None</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserService</span><span class="p">:</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">user_repo</span><span class="p">:</span> <span class="n">UserRepository</span><span class="p">):</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>        <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span> <span class="o">=</span> <span class="n">user_repo</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">register_user</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">username</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">email</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">User</span><span class="p">:</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="k">if</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span><span class="o">.</span><span class="n">find_by_email</span><span class="p">(</span><span class="n">email</span><span class="p">):</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;Email already exists&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>        <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">user_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">User</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="n">username</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="n">email</span><span class="p">))</span>
 </code></pre></div>
-<h3 id="pattern-2-aggregation-pipeline">Pattern 2: Aggregation Pipeline</h3>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user_stats</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">:</span>
-<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>    <span class="n">pipeline</span> <span class="o">=</span> <span class="p">[</span>
-<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>        <span class="p">{</span><span class="s2">&quot;$match&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;author_id&quot;</span><span class="p">:</span> <span class="n">user_id</span><span class="p">}},</span>
-<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a>        <span class="p">{</span><span class="s2">&quot;$group&quot;</span><span class="p">:</span> <span class="p">{</span>
-<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>            <span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
-<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>            <span class="s2">&quot;total_posts&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$sum&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span>
-<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>            <span class="s2">&quot;total_likes&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$sum&quot;</span><span class="p">:</span> <span class="s2">&quot;$likes&quot;</span><span class="p">}</span>
-<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>        <span class="p">}}</span>
-<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a>    <span class="p">]</span>
-<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a>    <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">post_repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">pipeline</span><span class="p">)</span><span class="o">.</span><span class="n">to_list</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
-<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>    <span class="k">return</span> <span class="n">result</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">if</span> <span class="n">result</span> <span class="k">else</span> <span class="p">{</span><span class="s2">&quot;total_posts&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s2">&quot;total_likes&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">}</span>
-</code></pre></div>
-<h3 id="pattern-3-bulk-operations">Pattern 3: Bulk Operations</h3>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">bulk_update_status</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ids</span><span class="p">:</span> <span class="n">List</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">status</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
-<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>    <span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
-<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>    <span class="n">object_ids</span> <span class="o">=</span> <span class="p">[</span><span class="n">ObjectId</span><span class="p">(</span><span class="nb">id</span><span class="p">)</span> <span class="k">for</span> <span class="nb">id</span> <span class="ow">in</span> <span class="n">ids</span><span class="p">]</span>
-<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a>    <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_many</span><span class="p">(</span>
-<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a>        <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$in&quot;</span><span class="p">:</span> <span class="n">object_ids</span><span class="p">}},</span>
-<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>        <span class="p">{</span><span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;status&quot;</span><span class="p">:</span> <span class="n">status</span><span class="p">,</span> <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()}}</span>
-<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a>    <span class="p">)</span>
+<blockquote>
+<p>Register a unique index on <code>email</code> via <code>ModelRegistry</code> so the race is also caught by <code>DuplicateKeyError</code> — see <a href="../03_use_cases/13_index_creation/">use case 13</a>.</p>
+</blockquote>
+<hr />
+<h2 id="pattern-2-aggregation-pipeline">Pattern 2: Aggregation Pipeline</h2>
+<p>Aggregations hit the raw Motor collection — wrap them in a repository method so callers stay at the domain level.</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">BaseDocument</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>
+<a id="__codelineno-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
+<a id="__codelineno-1-4" name="__codelineno-1-4" href="#__codelineno-1-4"></a><span class="k">class</span><span class="w"> </span><span class="nc">Post</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-1-5" name="__codelineno-1-5" href="#__codelineno-1-5"></a>    <span class="n">author_id</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-1-6" name="__codelineno-1-6" href="#__codelineno-1-6"></a>    <span class="n">title</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-1-7" name="__codelineno-1-7" href="#__codelineno-1-7"></a>    <span class="n">likes</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">0</span>
+<a id="__codelineno-1-8" name="__codelineno-1-8" href="#__codelineno-1-8"></a>
+<a id="__codelineno-1-9" name="__codelineno-1-9" href="#__codelineno-1-9"></a>
+<a id="__codelineno-1-10" name="__codelineno-1-10" href="#__codelineno-1-10"></a><span class="k">class</span><span class="w"> </span><span class="nc">PostRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Post</span><span class="p">]):</span>
+<a id="__codelineno-1-11" name="__codelineno-1-11" href="#__codelineno-1-11"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-1-12" name="__codelineno-1-12" href="#__codelineno-1-12"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;posts&quot;</span><span class="p">,</span> <span class="n">Post</span><span class="p">)</span>
+<a id="__codelineno-1-13" name="__codelineno-1-13" href="#__codelineno-1-13"></a>
+<a id="__codelineno-1-14" name="__codelineno-1-14" href="#__codelineno-1-14"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user_stats</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">dict</span><span class="p">:</span>
+<a id="__codelineno-1-15" name="__codelineno-1-15" href="#__codelineno-1-15"></a>        <span class="n">pipeline</span> <span class="o">=</span> <span class="p">[</span>
+<a id="__codelineno-1-16" name="__codelineno-1-16" href="#__codelineno-1-16"></a>            <span class="p">{</span><span class="s2">&quot;$match&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;author_id&quot;</span><span class="p">:</span> <span class="n">user_id</span><span class="p">}},</span>
+<a id="__codelineno-1-17" name="__codelineno-1-17" href="#__codelineno-1-17"></a>            <span class="p">{</span><span class="s2">&quot;$group&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span> <span class="s2">&quot;total_posts&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$sum&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="s2">&quot;total_likes&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$sum&quot;</span><span class="p">:</span> <span class="s2">&quot;$likes&quot;</span><span class="p">}}},</span>
+<a id="__codelineno-1-18" name="__codelineno-1-18" href="#__codelineno-1-18"></a>        <span class="p">]</span>
+<a id="__codelineno-1-19" name="__codelineno-1-19" href="#__codelineno-1-19"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">aggregate</span><span class="p">(</span><span class="n">pipeline</span><span class="p">)</span><span class="o">.</span><span class="n">to_list</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+<a id="__codelineno-1-20" name="__codelineno-1-20" href="#__codelineno-1-20"></a>        <span class="k">return</span> <span class="n">result</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="k">if</span> <span class="n">result</span> <span class="k">else</span> <span class="p">{</span><span class="s2">&quot;total_posts&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span> <span class="s2">&quot;total_likes&quot;</span><span class="p">:</span> <span class="mi">0</span><span class="p">}</span>
 </code></pre></div>
 <hr />
+<h2 id="pattern-3-bulk-operations">Pattern 3: Bulk Operations</h2>
+<p>Multi-document mutation in one call — again wrapped at the repository boundary.</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span>
+<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
+<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseRepository</span><span class="p">,</span> <span class="n">BaseDocument</span>
+<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a>
+<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a>
+<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="k">class</span><span class="w"> </span><span class="nc">Task</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a>    <span class="n">status</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;pending&quot;</span>
+<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a>
+<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a>
+<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="k">class</span><span class="w"> </span><span class="nc">TaskRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">Task</span><span class="p">]):</span>
+<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;tasks&quot;</span><span class="p">,</span> <span class="n">Task</span><span class="p">)</span>
+<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>
+<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a>    <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">bulk_update_status</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ids</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">],</span> <span class="n">status</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
+<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a>        <span class="n">object_ids</span> <span class="o">=</span> <span class="p">[</span><span class="n">ObjectId</span><span class="p">(</span><span class="n">i</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">ids</span><span class="p">]</span>
+<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a>        <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">update_many</span><span class="p">(</span>
+<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a>            <span class="p">{</span><span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;$in&quot;</span><span class="p">:</span> <span class="n">object_ids</span><span class="p">}},</span>
+<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a>            <span class="p">{</span><span class="s2">&quot;$set&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;status&quot;</span><span class="p">:</span> <span class="n">status</span><span class="p">,</span> <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="n">datetime</span><span class="o">.</span><span class="n">utcnow</span><span class="p">()}},</span>
+<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a>        <span class="p">)</span>
+<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a>        <span class="k">return</span> <span class="n">result</span><span class="o">.</span><span class="n">modified_count</span>
+</code></pre></div>
+<blockquote>
+<p>Bulk/aggregation methods bypass the caching and population layers — keep them deliberate and documented.</p>
+</blockquote>
+<hr />
+<h2 id="pattern-4-transactional-multi-step-write">Pattern 4: Transactional Multi-Step Write</h2>
+<p>Cross-collection atomicity with <code>execute_transaction</code> — see <a href="../03_use_cases/12_transaction_helper/">use case 12</a> for the full code.</p>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="n">results</span> <span class="o">=</span> <span class="k">await</span> <span class="n">TransactionManager</span><span class="o">.</span><span class="n">execute_transaction</span><span class="p">([</span><span class="n">op1</span><span class="p">,</span> <span class="n">op2</span><span class="p">,</span> <span class="n">op3</span><span class="p">])</span>
+<a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a><span class="c1"># op1/op2/op3 each receive the shared session; one failure rolls back all.</span>
+</code></pre></div>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../03_use_cases/02_custom_repo/">02 – Custom repository</a> · <a href="../03_use_cases/03_transactions/">03 – Transactions</a> · <a href="../04_best_practices/">Best Practices</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/06_error_handling/index.html b/mongo-ops/06_error_handling/index.html
index fc234be..2c8622c 100644
--- a/mongo-ops/06_error_handling/index.html
+++ b/mongo-ops/06_error_handling/index.html
@@ -454,7 +454,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -904,6 +904,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -936,6 +938,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -944,9 +948,36 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#error-handling" class="md-nav__link">
+  <a href="#library-raised-exceptions" class="md-nav__link">
     <span class="md-ellipsis">
-      Error Handling
+      📋 Library-Raised Exceptions
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#fastapi-mapping-example" class="md-nav__link">
+    <span class="md-ellipsis">
+      🚀 FastAPI Mapping Example
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#tips" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Tips
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -998,33 +1029,145 @@
 
 
 
-  <h1>Error Handling</h1>
-
-<h2 id="error-handling">Error Handling</h2>
-<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">HTTPException</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pymongo.errors</span><span class="w"> </span><span class="kn">import</span> <span class="n">DuplicateKeyError</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson.errors</span><span class="w"> </span><span class="kn">import</span> <span class="n">InvalidId</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">):</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>    <span class="k">try</span><span class="p">:</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">user_repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>    <span class="k">except</span> <span class="n">DuplicateKeyError</span><span class="p">:</span>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">409</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User already exists&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">500</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">))</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">):</span>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>    <span class="k">try</span><span class="p">:</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>        <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">user_repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>        <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>            <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>        <span class="k">return</span> <span class="n">user</span>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="k">except</span> <span class="n">InvalidId</span><span class="p">:</span>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Invalid user ID format&quot;</span><span class="p">)</span>
-</code></pre></div>
+<h1 id="error-handling">Error Handling</h1>
+<p>What can raise, what it means, and how to map it in a FastAPI app.</p>
 <hr />
+<h2 id="library-raised-exceptions">📋 Library-Raised Exceptions</h2>
+<table>
+<thead>
+<tr>
+<th>Exception</th>
+<th>Source</th>
+<th>Meaning / fix</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>RuntimeError("Database not connected. Call connect() first.")</code></td>
+<td><code>get_database()</code> / <code>get_client()</code> and any repository constructed first</td>
+<td><code>MongoConnectionManager.connect()</code> hasn't run — wire the lifespan.</td>
+</tr>
+<tr>
+<td><code>RuntimeError("No cache backend registered. Call set_cache_backend() first.")</code></td>
+<td><code>ModelRegistry.initialize_cache()</code></td>
+<td>Call <code>set_cache_backend(backend)</code> before <code>initialize_cache()</code>.</td>
+</tr>
+<tr>
+<td><code>KeyError("Model for collection '...' not registered")</code></td>
+<td><code>ModelRegistry.get_model()</code></td>
+<td>Collection was never <code>register</code>ed (or typo).</td>
+</tr>
+<tr>
+<td><code>ValueError("Cannot patch FK fields via patch(): ...")</code></td>
+<td><code>PopulatingRepository.patch()</code></td>
+<td><code>patch</code> must not touch populated ref fields — use <code>update()</code> with a model.</td>
+</tr>
+<tr>
+<td><code>ValueError("...contains embedded dict(s) — run repair script")</code></td>
+<td><code>_populate</code> on read</td>
+<td>A FK field holds an embedded document instead of an <code>ObjectId</code> — migrate the data.</td>
+</tr>
+<tr>
+<td><code>ValueError("...contains ObjectId — was populate skipped?")</code></td>
+<td><code>_depopulate</code> on write</td>
+<td>A populate-ruled field is still an <code>ObjectId</code> at depopulate time — the read must have populated it first.</td>
+</tr>
+<tr>
+<td><code>CircularReferenceError(collection, doc_id, path)</code></td>
+<td><code>PopulationEngine.populate</code></td>
+<td>A <code>(Class, id)</code> pair was revisited — raise <code>max_depth</code> or fix the graph.</td>
+</tr>
+<tr>
+<td><code>ImportError("redis package required ... mongo-ops[redis]")</code></td>
+<td><code>CacheConfig</code> / <code>RedisCacheBackend</code></td>
+<td>Missing <code>redis</code> extra.</td>
+</tr>
+<tr>
+<td><code>ValueError("redis_client required when backend='redis'")</code></td>
+<td><code>CacheConfig</code></td>
+<td><code>backend="redis"</code> without a client.</td>
+</tr>
+<tr>
+<td>Pymongo <code>DuplicateKeyError</code></td>
+<td>any insert/update</td>
+<td>Unique index violation (e.g., duplicate email).</td>
+</tr>
+<tr>
+<td><code>bson.errors.InvalidId</code></td>
+<td><code>ObjectId(...)</code> on a bad string</td>
+<td>Wrapped by <code>PyObjectId</code> model validation on API inputs.</td>
+</tr>
+</tbody>
+</table>
+<blockquote>
+<p><code>KeyError</code> for <code>ModelRegistry.get_model</code> and the <code>RuntimeError</code>/<code>ValueError</code> guards are <strong>by design</strong> — they fail loudly at startup or first call instead of misbehaving silently.</p>
+</blockquote>
+<hr />
+<h2 id="fastapi-mapping-example">🚀 FastAPI Mapping Example</h2>
+<div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi</span><span class="w"> </span><span class="kn">import</span> <span class="n">FastAPI</span><span class="p">,</span> <span class="n">HTTPException</span><span class="p">,</span> <span class="n">Request</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi.responses</span><span class="w"> </span><span class="kn">import</span> <span class="n">JSONResponse</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson.errors</span><span class="w"> </span><span class="kn">import</span> <span class="n">InvalidId</span>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pymongo.errors</span><span class="w"> </span><span class="kn">import</span> <span class="n">DuplicateKeyError</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.cache</span><span class="w"> </span><span class="kn">import</span> <span class="n">CircularReferenceError</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="n">app</span> <span class="o">=</span> <span class="n">FastAPI</span><span class="p">()</span>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="nd">@app</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="n">DuplicateKeyError</span><span class="p">)</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">duplicate_key_handler</span><span class="p">(</span><span class="n">_</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">__</span><span class="p">:</span> <span class="n">DuplicateKeyError</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">JSONResponse</span><span class="p">:</span>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="k">return</span> <span class="n">JSONResponse</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">409</span><span class="p">,</span> <span class="n">content</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="s2">&quot;Resource already exists&quot;</span><span class="p">})</span>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="nd">@app</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="n">InvalidId</span><span class="p">)</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">invalid_id_handler</span><span class="p">(</span><span class="n">_</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">__</span><span class="p">:</span> <span class="n">InvalidId</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">JSONResponse</span><span class="p">:</span>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="k">return</span> <span class="n">JSONResponse</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">content</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="s2">&quot;Invalid ID format&quot;</span><span class="p">})</span>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a><span class="nd">@app</span><span class="o">.</span><span class="n">exception_handler</span><span class="p">(</span><span class="n">CircularReferenceError</span><span class="p">)</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">circular_ref_handler</span><span class="p">(</span><span class="n">_</span><span class="p">:</span> <span class="n">Request</span><span class="p">,</span> <span class="n">exc</span><span class="p">:</span> <span class="n">CircularReferenceError</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">JSONResponse</span><span class="p">:</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>    <span class="k">return</span> <span class="n">JSONResponse</span><span class="p">(</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>        <span class="n">status_code</span><span class="o">=</span><span class="mi">409</span><span class="p">,</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>        <span class="n">content</span><span class="o">=</span><span class="p">{</span><span class="s2">&quot;detail&quot;</span><span class="p">:</span> <span class="sa">f</span><span class="s2">&quot;Circular reference detected: </span><span class="si">{</span><span class="n">exc</span><span class="o">.</span><span class="n">path</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">},</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>    <span class="p">)</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="c1"># Or handle inline for route-specific responses:</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="nd">@app</span><span class="o">.</span><span class="n">post</span><span class="p">(</span><span class="s2">&quot;/users/&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">create_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="k">try</span><span class="p">:</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>        <span class="k">return</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">user</span><span class="p">)</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="k">except</span> <span class="n">DuplicateKeyError</span><span class="p">:</span>
+<a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">409</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User already exists&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">500</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="nb">str</span><span class="p">(</span><span class="n">exc</span><span class="p">))</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="nd">@app</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">repo</span><span class="o">=</span><span class="n">Depends</span><span class="p">(</span><span class="n">get_user_repository</span><span class="p">)):</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="k">try</span><span class="p">:</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>        <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="n">user_id</span><span class="p">)</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">except</span> <span class="n">InvalidId</span><span class="p">:</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">400</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;Invalid user ID&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>    <span class="k">if</span> <span class="ow">not</span> <span class="n">user</span><span class="p">:</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="k">raise</span> <span class="n">HTTPException</span><span class="p">(</span><span class="n">status_code</span><span class="o">=</span><span class="mi">404</span><span class="p">,</span> <span class="n">detail</span><span class="o">=</span><span class="s2">&quot;User not found&quot;</span><span class="p">)</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>    <span class="k">return</span> <span class="n">user</span>
+</code></pre></div>
+<blockquote>
+<p>Prefer exception <strong>handlers</strong> for the library-level exceptions (409/400 above) and per-endpoint <code>try/except</code> for domain decisions (404).</p>
+</blockquote>
+<hr />
+<h2 id="tips">💡 Tips</h2>
+<ul>
+<li>The <code>ValueError</code> populate guards are your friends: they surface data-shape drift (embedded docs, skipped population) at the exact call site.</li>
+<li>In dev, log the <code>CircularReferenceError.path</code> — it prints the visited <code>Class:id</code> chain.</li>
+<li>Never swallow <code>RuntimeError</code>s at startup; let the app fail to load so the misconfiguration is obvious.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../03_use_cases/03_transactions/">03 – Transactions</a> · <a href="../03_use_cases/08_population/">08 – Population</a> · <a href="../03_use_cases/11_cache_lifecycle/">11 – Cache lifecycle</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/07_testing_example/index.html b/mongo-ops/07_testing_example/index.html
index 01e149e..8293c08 100644
--- a/mongo-ops/07_testing_example/index.html
+++ b/mongo-ops/07_testing_example/index.html
@@ -452,7 +452,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -924,6 +924,8 @@
       <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
       
       
+        
+      
       
         <label class="md-nav__link md-nav__link--active" for="__toc">
           
@@ -956,6 +958,8 @@
   
   
   
+    
+  
   
     <label class="md-nav__title" for="__toc">
       <span class="md-nav__icon md-icon"></span>
@@ -964,9 +968,27 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#testing-example" class="md-nav__link">
+  <a href="#mock-based-quickstart" class="md-nav__link">
     <span class="md-ellipsis">
-      Testing Example
+      🚀 Mock-Based Quickstart
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#notes" class="md-nav__link">
+    <span class="md-ellipsis">
+      💡 Notes
+    </span>
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#related" class="md-nav__link">
+    <span class="md-ellipsis">
+      Related
     </span>
   </a>
   
@@ -996,55 +1018,79 @@
 
 
 
-  <h1>Testing Example</h1>
-
-<h2 id="testing-example">Testing Example</h2>
+<h1 id="testing-example">Testing Example</h1>
+<p>A zero-MongoDB unit-test quickstart. The full guide is <a href="../03_use_cases/14_testing_guide/">use case 14</a>.</p>
+<hr />
+<h2 id="mock-based-quickstart">🚀 Mock-Based Quickstart</h2>
+<p>Patch the connection manager and stub the collection — no network, no docker.</p>
 <div class="language-python highlight"><span class="filename">Python</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="kn">import</span><span class="w"> </span><span class="nn">pytest</span>
-<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
-<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>    <span class="n">MongoConnectionManager</span><span class="p">,</span>
-<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a>    <span class="n">BaseDocument</span><span class="p">,</span>
-<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a>    <span class="n">BaseRepository</span><span class="p">,</span>
-<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="p">)</span>
-<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pydantic</span><span class="w"> </span><span class="kn">import</span> <span class="n">Field</span>
-<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a><span class="kn">from</span><span class="w"> </span><span class="nn">typing</span><span class="w"> </span><span class="kn">import</span> <span class="n">Optional</span>
-<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a>
-<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a><span class="c1"># Define Model</span>
-<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
-<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">,</span> <span class="n">min_length</span><span class="o">=</span><span class="mi">3</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">50</span><span class="p">)</span>
-<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="n">Field</span><span class="p">(</span><span class="o">...</span><span class="p">)</span>
-<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a>    <span class="n">is_active</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">True</span>
-<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>
-<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a><span class="c1"># Create Repository</span>
-<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
-<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
-<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
-<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a>
-<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>
-<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
-<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">db</span><span class="p">():</span>
-<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>    <span class="k">await</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span>
-<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>        <span class="n">uri</span><span class="o">=</span><span class="s2">&quot;mongodb://localhost:27017&quot;</span><span class="p">,</span>
-<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="n">db_name</span><span class="o">=</span><span class="s2">&quot;test_db&quot;</span>
-<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>    <span class="p">)</span>
-<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>    <span class="k">yield</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">get_database</span><span class="p">()</span>
-<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a>    <span class="k">await</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">get_client</span><span class="p">()</span><span class="o">.</span><span class="n">drop_database</span><span class="p">(</span><span class="s2">&quot;test_db&quot;</span><span class="p">)</span>
-<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a>    <span class="k">await</span> <span class="n">MongoConnectionManager</span><span class="o">.</span><span class="n">disconnect</span><span class="p">()</span>
-<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>
-<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
-<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_create_user</span><span class="p">(</span><span class="n">db</span><span class="p">):</span>
-<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>    <span class="n">repo</span> <span class="o">=</span> <span class="n">UserRepository</span><span class="p">()</span>
+<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">unittest.mock</span><span class="w"> </span><span class="kn">import</span> <span class="n">AsyncMock</span><span class="p">,</span> <span class="n">patch</span>
+<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a>
+<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">bson</span><span class="w"> </span><span class="kn">import</span> <span class="n">ObjectId</span>
+<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops</span><span class="w"> </span><span class="kn">import</span> <span class="n">BaseDocument</span><span class="p">,</span> <span class="n">BaseRepository</span>
+<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mongo_ops.repository</span><span class="w"> </span><span class="kn">import</span> <span class="n">MongoConnectionManager</span>
+<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a>
+<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a>
+<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a><span class="k">class</span><span class="w"> </span><span class="nc">User</span><span class="p">(</span><span class="n">BaseDocument</span><span class="p">):</span>
+<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a>    <span class="n">username</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a>    <span class="n">email</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+<a id="__codelineno-0-12" name="__codelineno-0-12" href="#__codelineno-0-12"></a>
+<a id="__codelineno-0-13" name="__codelineno-0-13" href="#__codelineno-0-13"></a>
+<a id="__codelineno-0-14" name="__codelineno-0-14" href="#__codelineno-0-14"></a><span class="k">class</span><span class="w"> </span><span class="nc">UserRepository</span><span class="p">(</span><span class="n">BaseRepository</span><span class="p">[</span><span class="n">User</span><span class="p">]):</span>
+<a id="__codelineno-0-15" name="__codelineno-0-15" href="#__codelineno-0-15"></a>    <span class="k">def</span><span class="w"> </span><span class="fm">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+<a id="__codelineno-0-16" name="__codelineno-0-16" href="#__codelineno-0-16"></a>        <span class="nb">super</span><span class="p">()</span><span class="o">.</span><span class="fm">__init__</span><span class="p">(</span><span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="n">User</span><span class="p">)</span>
+<a id="__codelineno-0-17" name="__codelineno-0-17" href="#__codelineno-0-17"></a>
+<a id="__codelineno-0-18" name="__codelineno-0-18" href="#__codelineno-0-18"></a>
+<a id="__codelineno-0-19" name="__codelineno-0-19" href="#__codelineno-0-19"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">fixture</span>
+<a id="__codelineno-0-20" name="__codelineno-0-20" href="#__codelineno-0-20"></a><span class="k">def</span><span class="w"> </span><span class="nf">repo</span><span class="p">():</span>
+<a id="__codelineno-0-21" name="__codelineno-0-21" href="#__codelineno-0-21"></a>    <span class="n">mock_collection</span> <span class="o">=</span> <span class="n">AsyncMock</span><span class="p">()</span>
+<a id="__codelineno-0-22" name="__codelineno-0-22" href="#__codelineno-0-22"></a>    <span class="k">with</span> <span class="n">patch</span><span class="o">.</span><span class="n">object</span><span class="p">(</span><span class="n">MongoConnectionManager</span><span class="p">,</span> <span class="s2">&quot;get_database&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">mock_db</span><span class="p">:</span>
+<a id="__codelineno-0-23" name="__codelineno-0-23" href="#__codelineno-0-23"></a>        <span class="n">mock_db</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="fm">__getitem__</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-24" name="__codelineno-0-24" href="#__codelineno-0-24"></a>        <span class="n">r</span> <span class="o">=</span> <span class="n">UserRepository</span><span class="p">()</span>
+<a id="__codelineno-0-25" name="__codelineno-0-25" href="#__codelineno-0-25"></a>        <span class="n">r</span><span class="o">.</span><span class="n">collection</span> <span class="o">=</span> <span class="n">mock_collection</span>
+<a id="__codelineno-0-26" name="__codelineno-0-26" href="#__codelineno-0-26"></a>        <span class="k">return</span> <span class="n">r</span>
+<a id="__codelineno-0-27" name="__codelineno-0-27" href="#__codelineno-0-27"></a>
+<a id="__codelineno-0-28" name="__codelineno-0-28" href="#__codelineno-0-28"></a>
+<a id="__codelineno-0-29" name="__codelineno-0-29" href="#__codelineno-0-29"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-30" name="__codelineno-0-30" href="#__codelineno-0-30"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_create_user</span><span class="p">(</span><span class="n">repo</span><span class="p">):</span>
+<a id="__codelineno-0-31" name="__codelineno-0-31" href="#__codelineno-0-31"></a>    <span class="n">mock_collection</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">collection</span>
+<a id="__codelineno-0-32" name="__codelineno-0-32" href="#__codelineno-0-32"></a>    <span class="n">oid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">()</span>
+<a id="__codelineno-0-33" name="__codelineno-0-33" href="#__codelineno-0-33"></a>    <span class="n">mock_collection</span><span class="o">.</span><span class="n">insert_one</span><span class="o">.</span><span class="n">return_value</span><span class="o">.</span><span class="n">inserted_id</span> <span class="o">=</span> <span class="n">oid</span>
+<a id="__codelineno-0-34" name="__codelineno-0-34" href="#__codelineno-0-34"></a>
 <a id="__codelineno-0-35" name="__codelineno-0-35" href="#__codelineno-0-35"></a>    <span class="n">user</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">User</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s2">&quot;test&quot;</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="s2">&quot;test@example.com&quot;</span><span class="p">))</span>
-<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>    <span class="k">assert</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
-<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">assert</span> <span class="n">user</span><span class="o">.</span><span class="n">username</span> <span class="o">==</span> <span class="s2">&quot;test&quot;</span>
-<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>
-<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
-<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_get_by_id</span><span class="p">(</span><span class="n">db</span><span class="p">):</span>
-<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a>    <span class="n">repo</span> <span class="o">=</span> <span class="n">UserRepository</span><span class="p">()</span>
-<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a>    <span class="n">created</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">User</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="s2">&quot;test&quot;</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="s2">&quot;test@example.com&quot;</span><span class="p">))</span>
-<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>    <span class="n">fetched</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">created</span><span class="o">.</span><span class="n">id</span><span class="p">))</span>
-<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="k">assert</span> <span class="n">fetched</span><span class="o">.</span><span class="n">username</span> <span class="o">==</span> <span class="n">created</span><span class="o">.</span><span class="n">username</span>
+<a id="__codelineno-0-36" name="__codelineno-0-36" href="#__codelineno-0-36"></a>
+<a id="__codelineno-0-37" name="__codelineno-0-37" href="#__codelineno-0-37"></a>    <span class="k">assert</span> <span class="n">user</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">oid</span>
+<a id="__codelineno-0-38" name="__codelineno-0-38" href="#__codelineno-0-38"></a>    <span class="k">assert</span> <span class="n">user</span><span class="o">.</span><span class="n">username</span> <span class="o">==</span> <span class="s2">&quot;test&quot;</span>
+<a id="__codelineno-0-39" name="__codelineno-0-39" href="#__codelineno-0-39"></a>
+<a id="__codelineno-0-40" name="__codelineno-0-40" href="#__codelineno-0-40"></a>
+<a id="__codelineno-0-41" name="__codelineno-0-41" href="#__codelineno-0-41"></a><span class="nd">@pytest</span><span class="o">.</span><span class="n">mark</span><span class="o">.</span><span class="n">asyncio</span>
+<a id="__codelineno-0-42" name="__codelineno-0-42" href="#__codelineno-0-42"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">test_get_by_id</span><span class="p">(</span><span class="n">repo</span><span class="p">):</span>
+<a id="__codelineno-0-43" name="__codelineno-0-43" href="#__codelineno-0-43"></a>    <span class="n">oid</span> <span class="o">=</span> <span class="n">ObjectId</span><span class="p">()</span>
+<a id="__codelineno-0-44" name="__codelineno-0-44" href="#__codelineno-0-44"></a>    <span class="n">repo</span><span class="o">.</span><span class="n">collection</span><span class="o">.</span><span class="n">find_one</span><span class="o">.</span><span class="n">return_value</span> <span class="o">=</span> <span class="p">{</span>
+<a id="__codelineno-0-45" name="__codelineno-0-45" href="#__codelineno-0-45"></a>        <span class="s2">&quot;_id&quot;</span><span class="p">:</span> <span class="n">oid</span><span class="p">,</span>
+<a id="__codelineno-0-46" name="__codelineno-0-46" href="#__codelineno-0-46"></a>        <span class="s2">&quot;username&quot;</span><span class="p">:</span> <span class="s2">&quot;test&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-47" name="__codelineno-0-47" href="#__codelineno-0-47"></a>        <span class="s2">&quot;email&quot;</span><span class="p">:</span> <span class="s2">&quot;test@example.com&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-48" name="__codelineno-0-48" href="#__codelineno-0-48"></a>        <span class="s2">&quot;created_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-49" name="__codelineno-0-49" href="#__codelineno-0-49"></a>        <span class="s2">&quot;updated_at&quot;</span><span class="p">:</span> <span class="s2">&quot;2024-01-01T00:00:00&quot;</span><span class="p">,</span>
+<a id="__codelineno-0-50" name="__codelineno-0-50" href="#__codelineno-0-50"></a>    <span class="p">}</span>
+<a id="__codelineno-0-51" name="__codelineno-0-51" href="#__codelineno-0-51"></a>
+<a id="__codelineno-0-52" name="__codelineno-0-52" href="#__codelineno-0-52"></a>    <span class="n">fetched</span> <span class="o">=</span> <span class="k">await</span> <span class="n">repo</span><span class="o">.</span><span class="n">get_by_id</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">oid</span><span class="p">))</span>
+<a id="__codelineno-0-53" name="__codelineno-0-53" href="#__codelineno-0-53"></a>
+<a id="__codelineno-0-54" name="__codelineno-0-54" href="#__codelineno-0-54"></a>    <span class="k">assert</span> <span class="n">fetched</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span>
+<a id="__codelineno-0-55" name="__codelineno-0-55" href="#__codelineno-0-55"></a>    <span class="k">assert</span> <span class="n">fetched</span><span class="o">.</span><span class="n">username</span> <span class="o">==</span> <span class="s2">&quot;test&quot;</span>
 </code></pre></div>
 <hr />
+<h2 id="notes">💡 Notes</h2>
+<ul>
+<li><code>from mongo_ops.repository import MongoConnectionManager</code> — patch where it is <strong>used</strong> (<code>mongo_ops.repository.MongoConnectionManager</code>), matching the library's own tests.</li>
+<li>pytest-asyncio runs as <code>auto</code> mode per <code>pyproject.toml</code>, so <code>@pytest.mark.asyncio</code> works without extra config.</li>
+<li>For population, cache, registry, and transaction mockups — see the <a href="../03_use_cases/14_testing_guide/">full testing guide</a>.</li>
+</ul>
+<hr />
+<h2 id="related">Related</h2>
+<ul>
+<li><a href="../03_use_cases/14_testing_guide/">14 – Testing guide</a> · <a href="../04_best_practices/">Best Practices</a></li>
+</ul>
 
 
 
diff --git a/mongo-ops/404.html b/mongo-ops/404.html
index a7386da..5b52149 100644
--- a/mongo-ops/404.html
+++ b/mongo-ops/404.html
@@ -443,7 +443,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
diff --git a/mongo-ops/index.html b/mongo-ops/index.html
index f96e235..25dcc64 100644
--- a/mongo-ops/index.html
+++ b/mongo-ops/index.html
@@ -530,7 +530,7 @@
   
   
   <span class="md-ellipsis">
-    02 components
+    Core Components
     
   </span>
   
@@ -1028,26 +1028,33 @@
 
 
 <h1 id="mongo-ops-async-mongodb-operations-layer-for-fastapi">🧩 mongo-ops — Async MongoDB Operations Layer for FastAPI</h1>
-<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library designed for FastAPI microservices.
-It standardizes repository patterns, async CRUD operations, and model management — with extensible components for both Beanie and Motor.</p>
+<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library for FastAPI microservices. It standardizes connection lifecycle, Pydantic v2 document models, and repository-style async CRUD — with added layers for caching, reference population, and multi-document transactions. It is built on top of Motor.</p>
+<blockquote>
+<p><strong>Doc model:</strong> this wiki is written for humans — how‑to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine‑readable bundle under <code>docs/mcp/</code>.</p>
+</blockquote>
 <hr />
 <h2 id="key-features">🚀 Key Features</h2>
 <ul>
-<li>🧱 Unified repository pattern for MongoDB collections</li>
+<li>🧱 Unified repository pattern — <code>BaseRepository</code> with generic CRUD</li>
 <li>⚡ Fully asynchronous (Motor-based)</li>
-<li>🧬 Pydantic v2 data model integration</li>
-<li>🧰 Built-in CRUD and aggregation utilities</li>
-<li>🔒 Transaction and session helpers</li>
-<li>🧩 Optional Beanie ORM integration</li>
-<li>🧪 Pytest-friendly architecture</li>
+<li>🧬 Pydantic v2 data models with auto‑timestamps (<code>BaseDocument</code>)</li>
+<li>🔒 Model registry for multi-collection startup (<code>ModelRegistry</code>)</li>
+<li>🗄️ ID-based caching — in-memory or Redis (<code>cache/</code>)</li>
+<li>🔗 Reference population with cycle detection (<code>populate/</code>)</li>
+<li>🔁 Transaction and session helpers (<code>transactions/</code>)</li>
+<li>🧪 Mock-friendly architecture — the whole repo test suite runs without MongoDB</li>
 </ul>
 <hr />
 <h2 id="installation">📦 Installation</h2>
 <p>From your internal PyPI:</p>
 <div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span>mongo-ops
 </code></pre></div>
+<p>With the extra batteries your workload needs:</p>
+<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span><span class="s2">&quot;mongo-ops[redis]&quot;</span><span class="w">   </span><span class="c1"># Redis cache backend</span>
+<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-2"></a>pip<span class="w"> </span>install<span class="w"> </span>--extra-index-url<span class="w"> </span>https://<span class="nv">$PYPI_USERNAME</span>:<span class="nv">$PYPI_PASSWORD</span>@pip.aetoskia.com/simple<span class="w"> </span><span class="s2">&quot;mongo-ops[all]&quot;</span><span class="w">     </span><span class="c1"># dev, redis, beanie, fastapi</span>
+</code></pre></div>
 <p>From local source:</p>
-<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
+<div class="language-bash highlight"><span class="filename">Bash</span><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>pip<span class="w"> </span>install<span class="w"> </span>-e<span class="w"> </span>.
 </code></pre></div>
 <hr />
 <h2 id="documentation-structure">📁 Documentation Structure</h2>
@@ -1061,31 +1068,87 @@ It standardizes repository patterns, async CRUD operations, and model management
 <tbody>
 <tr>
 <td><a href="01_overview/">Overview</a></td>
-<td>Core concept and architecture overview</td>
+<td>Architecture, lifecycle, and repository decision table</td>
 </tr>
 <tr>
 <td><a href="02_components/">Core Components</a></td>
-<td><code>BaseDocument</code>, <code>MongoConnectionManager</code>, <code>BaseRepository</code></td>
+<td>Validated reference for the public API surface</td>
 </tr>
 <tr>
-<td><a href="03_use_cases/01_basic_crud/">Use Cases</a></td>
-<td>CRUD, transactions, pagination, and more</td>
+<td><strong>Use cases</strong></td>
+<td>Step-by-step recipes</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/01_basic_crud/">01 – Basic CRUD API</a></td>
+<td>FastAPI user management app</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/02_custom_repo/">02 – Custom repository</a></td>
+<td>Product catalog with business logic</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/03_transactions/">03 – Transactions</a></td>
+<td>Atomic order + inventory updates</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/04_pagination/">04 – Pagination</a></td>
+<td>Filtering, sorting, page metadata</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/05_soft_deletes/">05 – Soft deletes</a></td>
+<td>Recoverable delete pattern</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/06_multi_model/">06 – Multi-model</a></td>
+<td>One service, many collections</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/07_caching/">07 – Caching</a></td>
+<td>In-memory / Redis read cache</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/08_population/">08 – Population</a></td>
+<td>Resolve references on read</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/09_advanced_population/">09 – Advanced population</a></td>
+<td>Nested + circular references</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/10_cache_and_population/">10 – Cache + population</a></td>
+<td>Reading through cache, populating on hit</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/11_cache_lifecycle/">11 – Cache lifecycle</a></td>
+<td>Startup/shutdown hygiene</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/12_transaction_helper/">12 – Transaction helper</a></td>
+<td><code>execute_transaction</code></td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/13_index_creation/">13 – Indexes</a></td>
+<td>Single, compound, and optioned indexes</td>
+</tr>
+<tr>
+<td>· <a href="03_use_cases/14_testing_guide/">14 – Testing guide</a></td>
+<td>Mock Motor, engine, cache, transactions</td>
 </tr>
 <tr>
 <td><a href="04_best_practices/">Best Practices</a></td>
-<td>Recommended repo structure and patterns</td>
+<td>Layering, lifecycle, and gotchas</td>
 </tr>
 <tr>
 <td><a href="05_patterns/">Common Patterns</a></td>
-<td>Service layer, aggregation, soft deletes</td>
+<td>Service layer, aggregation, bulk ops</td>
 </tr>
 <tr>
 <td><a href="06_error_handling/">Error Handling</a></td>
-<td>Centralized error and exception management</td>
+<td>Library exceptions and FastAPI mapping</td>
 </tr>
 <tr>
-<td><a href="07_testing_example/">Testing</a></td>
-<td>Pytest configuration and fixtures</td>
+<td><a href="07_testing_example/">Testing Example</a></td>
+<td>Mock-based quickstart</td>
 </tr>
 </tbody>
 </table>
@@ -1094,10 +1157,10 @@ It standardizes repository patterns, async CRUD operations, and model management
 <ul>
 <li><strong>Source Code:</strong> <a href="https://git.aetoskia.com/aetos/mongo-ops">Gitea Repository</a></li>
 <li><strong>Internal PyPI:</strong> <a href="https://pip.aetoskia.com/simple/mongo-ops">pip.aetoskia.com/simple/mongo-ops</a></li>
-<li><strong>Drone CI:</strong> Auto-builds and publishes tagged releases.</li>
+<li><strong>Drone CI:</strong> Auto-builds and publishes tagged releases, gated on black / ruff / mypy / pytest.</li>
 </ul>
 <hr />
-<p>© Aetoskia Internal — <code>mongo-ops</code> 0.1.4</p>
+<p>© Aetoskia Internal — <code>mongo-ops</code> 0.1.5</p>
 
 
 
diff --git a/mongo-ops/search/search_index.json b/mongo-ops/search/search_index.json
index d7e634a..87d0730 100644
--- a/mongo-ops/search/search_index.json
+++ b/mongo-ops/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 mongo-ops \u2014 Async MongoDB Operations Layer for FastAPI","text":"<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library designed for FastAPI microservices. It standardizes repository patterns, async CRUD operations, and model management \u2014 with extensible components for both Beanie and Motor.</p>"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":"<ul> <li>\ud83e\uddf1 Unified repository pattern for MongoDB collections</li> <li>\u26a1 Fully asynchronous (Motor-based)</li> <li>\ud83e\uddec Pydantic v2 data model integration</li> <li>\ud83e\uddf0 Built-in CRUD and aggregation utilities</li> <li>\ud83d\udd12 Transaction and session helpers</li> <li>\ud83e\udde9 Optional Beanie ORM integration</li> <li>\ud83e\uddea Pytest-friendly architecture</li> </ul>"},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"<p>From your internal PyPI:</p> Bash<pre><code>pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple mongo-ops\n</code></pre> <p>From local source:</p> Bash<pre><code>pip install -e .\n</code></pre>"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview Core concept and architecture overview Core Components <code>BaseDocument</code>, <code>MongoConnectionManager</code>, <code>BaseRepository</code> Use Cases CRUD, transactions, pagination, and more Best Practices Recommended repo structure and patterns Common Patterns Service layer, aggregation, soft deletes Error Handling Centralized error and exception management Testing Pytest configuration and fixtures"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"<ul> <li>Source Code: Gitea Repository</li> <li>Internal PyPI: pip.aetoskia.com/simple/mongo-ops</li> <li>Drone CI: Auto-builds and publishes tagged releases.</li> </ul> <p>\u00a9 Aetoskia Internal \u2014 <code>mongo-ops</code> 0.1.4</p>"},{"location":"01_overview/","title":"Overview","text":""},{"location":"01_overview/#library-overview","title":"Library Overview","text":"<p><code>mongo-ops</code> is a modular MongoDB operations layer for FastAPI microservices. It provides:</p> <ul> <li>Async connection management</li> <li>Base document models with auto-timestamps</li> <li>Generic CRUD repository pattern</li> <li>Transaction support</li> <li>Model registration system</li> </ul>"},{"location":"02_components/","title":"02 components","text":""},{"location":"02_components/#core-components","title":"Core Components","text":""},{"location":"02_components/#1-mongoconnectionmanager","title":"1. MongoConnectionManager","text":"<p>Manages MongoDB connections with async lifecycle. Methods:</p> <ul> <li><code>connect(uri, db_name, **kwargs)</code> - Connect to MongoDB</li> <li><code>disconnect()</code> - Close connection</li> <li><code>get_database()</code> - Get current database instance</li> <li><code>get_client()</code> - Get current client instance</li> <li><code>lifespan(uri, db_name, **kwargs)</code> - Context manager for FastAPI lifespan</li> </ul>"},{"location":"02_components/#2-basedocument","title":"2. BaseDocument","text":"<p>Base model for all MongoDB documents. Provides:</p> <ul> <li><code>id</code> (aliased to <code>_id</code>) - ObjectId</li> <li><code>created_at</code> - Auto-generated timestamp</li> <li><code>updated_at</code> - Auto-updated timestamp</li> </ul>"},{"location":"02_components/#3-baserepositoryt","title":"3. BaseRepository[T]","text":"<p>Generic repository with CRUD operations:</p> <ul> <li><code>create(data: T) -&gt; T</code></li> <li><code>get_by_id(id: str | ObjectId) -&gt; Optional[T]</code></li> <li><code>get_many(filter, skip, limit, sort) -&gt; List[T]</code></li> <li><code>update(id, data: Dict) -&gt; Optional[T]</code></li> <li><code>delete(id) -&gt; bool</code></li> <li><code>count(filter) -&gt; int</code></li> </ul>"},{"location":"02_components/#4-transactionmanager","title":"4. TransactionManager","text":"<p>Handles multi-document transactions:</p> <ul> <li><code>start_session()</code> - Context manager for transactions</li> <li><code>execute_transaction(operations)</code> - Execute multiple operations atomically</li> </ul>"},{"location":"02_components/#5-modelregistry","title":"5. ModelRegistry","text":"<p>Register and initialize models:</p> <ul> <li><code>register(collection_name, model, indexes)</code> - Register a model</li> <li><code>initialize_all()</code> - Create all indexes</li> <li><code>get_model(collection_name)</code> - Get registered model</li> <li><code>list_collections()</code> - List all registered collections</li> </ul>"},{"location":"02_components/#6-cache-backend","title":"6. Cache Backend","text":""},{"location":"02_components/#61-cachebackend-abstract","title":"6.1 CacheBackend (abstract)","text":"<ul> <li>Defines the async interface for cache operations: <code>get</code>, <code>set</code>, <code>delete</code>, <code>exists</code>, <code>clear_pattern</code>, <code>get_stats</code>, <code>initialize</code>, <code>shutdown</code>.</li> <li>Provides <code>CacheStats</code> for hit/miss/size metrics and <code>CircularReferenceError</code> for cycle detection.</li> </ul>"},{"location":"02_components/#62-cacheconfig","title":"6.2 CacheConfig","text":"<ul> <li>Dataclass to configure caching (<code>enabled</code>, <code>backend</code>, <code>redis_client</code>, <code>default_ttl</code>, <code>max_entries</code>, <code>key_prefix</code>, <code>cleanup_interval</code>).</li> </ul>"},{"location":"02_components/#63-inmemorycachebackend","title":"6.3 InMemoryCacheBackend","text":"<ul> <li>In\u2011process cache using an LRU <code>OrderedDict</code> and a TTL heap.</li> <li>Background task periodically evicts expired entries.</li> </ul>"},{"location":"02_components/#64-rediscachebackend","title":"6.4 RedisCacheBackend","text":"<ul> <li>Distributed cache based on <code>redis.asyncio</code>.</li> <li>JSON serialisation, optional pub/sub invalidation.</li> </ul>"},{"location":"02_components/#65-cachedbaserepositoryt","title":"6.5 CachedBaseRepository[T]","text":"<ul> <li>Extends <code>BaseRepository</code> with transparent ID\u2011based caching.</li> <li>Methods:</li> <li><code>get_by_id</code> \u2013 cache\u2011first lookup.</li> <li><code>create</code> \u2013 stores newly created doc in cache.</li> <li><code>update</code> / <code>delete</code> \u2013 invalidate or refresh cache.</li> <li><code>warm_cache(ids)</code> \u2013 pre\u2011load a list of IDs.</li> <li><code>invalidate_cache(id)</code> \u2013 manual invalidation.</li> </ul>"},{"location":"02_components/#7-population-engine","title":"7. Population Engine","text":""},{"location":"02_components/#71-populaterule","title":"7.1 PopulateRule","text":"<ul> <li>Dataclass defining a population rule: <code>field_name</code>, <code>collection_name</code>, <code>ref_field</code>, optional <code>nested_rules</code>, <code>max_depth</code>, <code>filter</code>, <code>projection</code>.</li> </ul>"},{"location":"02_components/#72-populationengine","title":"7.2 PopulationEngine","text":"<ul> <li>Recursively resolves references according to <code>PopulateRule</code> list.</li> <li>Detects circular references and raises <code>CircularReferenceError</code>.</li> <li>Supports per\u2011rule depth limits, filters and projections.</li> </ul>"},{"location":"02_components/#73-populatingrepositoryt","title":"7.3 PopulatingRepository[T]","text":"<ul> <li>Extends <code>BaseRepository</code> to automatically populate related documents.</li> <li>Accepts an optional <code>PopulationEngine</code> and a list of <code>PopulateRule</code>.</li> <li>Provides <code>_populate</code> and <code>_depopulate</code> helpers used in <code>get_by_id</code> and elsewhere.</li> </ul>"},{"location":"04_best_practices/","title":"Best Practices","text":""},{"location":"04_best_practices/#best-practices","title":"Best Practices","text":"<ol> <li>Always use ModelRegistry.register() before initializing the database connection</li> <li>Use lifespan context manager for proper connection lifecycle</li> <li>Inherit from BaseDocument for all models to get auto-timestamps</li> <li>Create custom repository classes for business logic instead of mixing it with models</li> <li>Use transactions for operations that modify multiple documents</li> <li>Add indexes during model registration for frequently queried fields</li> <li>Implement pagination for list endpoints to avoid performance issues</li> <li>Use type hints for better IDE support and type checking</li> </ol>"},{"location":"05_patterns/","title":"Common Patterns","text":""},{"location":"05_patterns/#common-patterns","title":"Common Patterns","text":""},{"location":"05_patterns/#pattern-1-service-layer-with-repository","title":"Pattern 1: Service Layer with Repository","text":"Python<pre><code>class UserService:\n    def __init__(self, user_repo: UserRepository):\n        self.user_repo = user_repo\n\n    async def register_user(self, username: str, email: str) -&gt; User:\n        # Check if user exists\n        existing = await self.user_repo.collection.find_one({\"email\": email})\n        if existing:\n            raise ValueError(\"Email already exists\")\n\n        # Create user\n        user = User(username=username, email=email)\n        return await self.user_repo.create(user)\n</code></pre>"},{"location":"05_patterns/#pattern-2-aggregation-pipeline","title":"Pattern 2: Aggregation Pipeline","text":"Python<pre><code>async def get_user_stats(self, user_id: str) -&gt; dict:\n    pipeline = [\n        {\"$match\": {\"author_id\": user_id}},\n        {\"$group\": {\n            \"_id\": None,\n            \"total_posts\": {\"$sum\": 1},\n            \"total_likes\": {\"$sum\": \"$likes\"}\n        }}\n    ]\n    result = await post_repo.collection.aggregate(pipeline).to_list(1)\n    return result[0] if result else {\"total_posts\": 0, \"total_likes\": 0}\n</code></pre>"},{"location":"05_patterns/#pattern-3-bulk-operations","title":"Pattern 3: Bulk Operations","text":"Python<pre><code>async def bulk_update_status(self, ids: List[str], status: str):\n    from bson import ObjectId\n    object_ids = [ObjectId(id) for id in ids]\n    await self.collection.update_many(\n        {\"_id\": {\"$in\": object_ids}},\n        {\"$set\": {\"status\": status, \"updated_at\": datetime.utcnow()}}\n    )\n</code></pre>"},{"location":"06_error_handling/","title":"Error Handling","text":""},{"location":"06_error_handling/#error-handling","title":"Error Handling","text":"Python<pre><code>from fastapi import HTTPException\nfrom pymongo.errors import DuplicateKeyError\nfrom bson.errors import InvalidId\n\n@app.post(\"/users/\")\nasync def create_user(user: User):\n    try:\n        return await user_repo.create(user)\n    except DuplicateKeyError:\n        raise HTTPException(status_code=409, detail=\"User already exists\")\n    except Exception as e:\n        raise HTTPException(status_code=500, detail=str(e))\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: str):\n    try:\n        user = await user_repo.get_by_id(user_id)\n        if not user:\n            raise HTTPException(status_code=404, detail=\"User not found\")\n        return user\n    except InvalidId:\n        raise HTTPException(status_code=400, detail=\"Invalid user ID format\")\n</code></pre>"},{"location":"07_testing_example/","title":"Testing Example","text":""},{"location":"07_testing_example/#testing-example","title":"Testing Example","text":"Python<pre><code>import pytest\nfrom mongo_ops import (\n    MongoConnectionManager,\n    BaseDocument,\n    BaseRepository,\n)\nfrom pydantic import Field\nfrom typing import Optional\n\n# Define Model\nclass User(BaseDocument):\n    username: str = Field(..., min_length=3, max_length=50)\n    email: str = Field(...)\n    is_active: bool = True\n\n# Create Repository\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n\n@pytest.fixture\nasync def db():\n    await MongoConnectionManager.connect(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"test_db\"\n    )\n    yield MongoConnectionManager.get_database()\n    await MongoConnectionManager.get_client().drop_database(\"test_db\")\n    await MongoConnectionManager.disconnect()\n\n@pytest.mark.asyncio\nasync def test_create_user(db):\n    repo = UserRepository()\n    user = await repo.create(User(username=\"test\", email=\"test@example.com\"))\n    assert user.id is not None\n    assert user.username == \"test\"\n\n@pytest.mark.asyncio\nasync def test_get_by_id(db):\n    repo = UserRepository()\n    created = await repo.create(User(username=\"test\", email=\"test@example.com\"))\n    fetched = await repo.get_by_id(str(created.id))\n    assert fetched.username == created.username\n</code></pre>"},{"location":"03_use_cases/01_basic_crud/","title":"Basic CRUD","text":""},{"location":"03_use_cases/01_basic_crud/#use-case-1-basic-fastapi-crud-api","title":"Use Case 1: Basic FastAPI CRUD API","text":"<p>Scenario: Create a simple user management API with CRUD operations.</p> Python<pre><code>import os\nfrom fastapi import FastAPI, Depends, HTTPException\nfrom contextlib import asynccontextmanager\nfrom pydantic import Field\nfrom mongo_ops import (\n    MongoConnectionManager,\n    BaseDocument,\n    BaseRepository,\n    ModelRegistry,\n)\n\n# ---------------------------\n# Model Definition\n# ---------------------------\nclass User(BaseDocument):\n    username: str = Field(..., min_length=3, max_length=50)\n    email: str = Field(...)\n    is_active: bool = True\n\n\n# ---------------------------\n# Repository\n# ---------------------------\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n\n# Register the model only once\nModelRegistry.register(\"users\", User, indexes=[(\"email\", 1)])\n\n\n# ---------------------------\n# FastAPI Lifespan\n# ---------------------------\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    \"\"\"Manage MongoDB connection during the app lifecycle.\"\"\"\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"mydb\"\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n# ---------------------------\n# Dependency Injection\n# ---------------------------\ndef get_user_repository() -&gt; UserRepository:\n    \"\"\"Dependency-injected repository for users.\"\"\"\n    return UserRepository()\n\n\n# ---------------------------\n# Routes\n# ---------------------------\n@app.post(\"/users/\", response_model=User)\nasync def create_user(user: User, repo: UserRepository = Depends(get_user_repository)):\n    return await repo.create(user)\n\n\n@app.get(\"/users/{user_id}\", response_model=User)\nasync def get_user(user_id: str, repo: UserRepository = Depends(get_user_repository)):\n    user = await repo.get_by_id(user_id)\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n\n\n@app.get(\"/users/\", response_model=list[User])\nasync def list_users(\n    skip: int = 0,\n    limit: int = 10,\n    repo: UserRepository = Depends(get_user_repository),\n):\n    return await repo.get_many(skip=skip, limit=limit)\n\n\n@app.put(\"/users/{user_id}\", response_model=User)\nasync def update_user(\n    user_id: str,\n    email: str,\n    repo: UserRepository = Depends(get_user_repository),\n):\n    user = await repo.update(user_id, {\"email\": email})\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n\n\n@app.delete(\"/users/{user_id}\")\nasync def delete_user(\n    user_id: str,\n    repo: UserRepository = Depends(get_user_repository),\n):\n    deleted = await repo.delete(user_id)\n    if not deleted:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return {\"message\": \"User deleted successfully\"}\n</code></pre>"},{"location":"03_use_cases/02_custom_repo/","title":"Custom Repo","text":""},{"location":"03_use_cases/02_custom_repo/#use-case-2-custom-repository-with-business-logic","title":"Use Case 2: Custom Repository with Business Logic","text":"<p>Scenario: E-commerce product catalog with custom search and filtering.</p> Python<pre><code>from mongo_ops import BaseDocument, BaseRepository\nfrom typing import Optional, List\nfrom pydantic import Field\n\nclass Product(BaseDocument):\n    name: str = Field(..., min_length=1)\n    description: str\n    price: float = Field(..., gt=0)\n    category: str\n    in_stock: bool = True\n    quantity: int = Field(default=0, ge=0)\n    tags: List[str] = []\n\nclass ProductRepository(BaseRepository[Product]):\n    def __init__(self):\n        super().__init__(\"products\", Product)\n\n    async def search_by_name(self, query: str) -&gt; List[Product]:\n        \"\"\"Search products by name (case-insensitive)\"\"\"\n        docs = await self.collection.find({\n            \"name\": {\"$regex\": query, \"$options\": \"i\"}\n        }).to_list(length=100)\n        return [self.model(**doc) for doc in docs]\n\n    async def get_by_category(self, category: str, in_stock_only: bool = True) -&gt; List[Product]:\n        \"\"\"Get products by category\"\"\"\n        filter_query = {\"category\": category}\n        if in_stock_only:\n            filter_query[\"in_stock\"] = True\n        return await self.get_many(filter=filter_query)\n\n    async def get_low_stock(self, threshold: int = 10) -&gt; List[Product]:\n        \"\"\"Get products with low stock\"\"\"\n        return await self.get_many(\n            filter={\"quantity\": {\"$lt\": threshold}, \"in_stock\": True}\n        )\n\n    async def update_stock(self, product_id: str, quantity_delta: int) -&gt; Optional[Product]:\n        \"\"\"Update product stock (increment/decrement)\"\"\"\n        result = await self.collection.find_one_and_update(\n            {\"_id\": ObjectId(product_id)},\n            {\"$inc\": {\"quantity\": quantity_delta}, \"$set\": {\"updated_at\": datetime.utcnow()}},\n            return_document=True\n        )\n        return self.model(**result) if result else None\n\n# Usage in FastAPI\nfrom fastapi import FastAPI, Query\n\napp = FastAPI()\nproduct_repo = ProductRepository()\n\n@app.get(\"/products/search\", response_model=List[Product])\nasync def search_products(q: str = Query(..., min_length=1)):\n    return await product_repo.search_by_name(q)\n\n@app.get(\"/products/category/{category}\", response_model=List[Product])\nasync def products_by_category(category: str, in_stock: bool = True):\n    return await product_repo.get_by_category(category, in_stock)\n\n@app.get(\"/products/low-stock\", response_model=List[Product])\nasync def low_stock_products(threshold: int = 10):\n    return await product_repo.get_low_stock(threshold)\n\n@app.patch(\"/products/{product_id}/stock\")\nasync def update_product_stock(product_id: str, quantity_delta: int):\n    product = await product_repo.update_stock(product_id, quantity_delta)\n    if not product:\n        raise HTTPException(status_code=404, detail=\"Product not found\")\n    return product\n</code></pre>"},{"location":"03_use_cases/03_transactions/","title":"Transactions","text":""},{"location":"03_use_cases/03_transactions/#use-case-3-transaction-support-for-multi-document-operations","title":"Use Case 3: Transaction Support for Multi-Document Operations","text":"<p>Scenario: Order processing system that updates inventory and creates order atomically.</p> Python<pre><code>from mongo_ops import BaseDocument, BaseRepository, TransactionManager\nfrom datetime import datetime\nfrom typing import List\nfrom pydantic import Field\n\nclass Order(BaseDocument):\n    user_id: str\n    items: List[dict]  # [{\"product_id\": \"...\", \"quantity\": 2}]\n    total_amount: float\n    status: str = \"pending\"\n\nclass OrderRepository(BaseRepository[Order]):\n    def __init__(self):\n        super().__init__(\"orders\", Order)\n\nclass OrderService:\n    def __init__(self, order_repo: OrderRepository, product_repo: ProductRepository):\n        self.order_repo = order_repo\n        self.product_repo = product_repo\n\n    async def create_order_with_inventory_update(self, order: Order) -&gt; Order:\n        \"\"\"Create order and update inventory atomically\"\"\"\n\n        async def create_order_transaction(session):\n            # Insert order\n            order_doc = order.model_dump(exclude={\"id\"}, exclude_none=True)\n            order_doc[\"created_at\"] = datetime.utcnow()\n            order_doc[\"updated_at\"] = datetime.utcnow()\n            result = await self.order_repo.collection.insert_one(order_doc, session=session)\n\n            # Update inventory for each item\n            for item in order.items:\n                await self.product_repo.collection.update_one(\n                    {\"_id\": ObjectId(item[\"product_id\"])},\n                    {\n                        \"$inc\": {\"quantity\": -item[\"quantity\"]},\n                        \"$set\": {\"updated_at\": datetime.utcnow()}\n                    },\n                    session=session\n                )\n\n            # Fetch created order\n            created = await self.order_repo.collection.find_one(\n                {\"_id\": result.inserted_id},\n                session=session\n            )\n            return Order(**created)\n\n        # Execute in transaction\n        async with TransactionManager.start_session() as session:\n            return await create_order_transaction(session)\n\n# Usage in FastAPI\n@app.post(\"/orders/\", response_model=Order)\nasync def create_order(order: Order):\n    order_service = OrderService(order_repo, product_repo)\n    try:\n        return await order_service.create_order_with_inventory_update(order)\n    except Exception as e:\n        raise HTTPException(status_code=400, detail=str(e))\n</code></pre>"},{"location":"03_use_cases/04_pagination/","title":"Pagination","text":""},{"location":"03_use_cases/04_pagination/#use-case-4-pagination-filtering","title":"Use Case 4: Pagination &amp; Filtering","text":"<p>Scenario: Blog post API with pagination and filtering.</p> Python<pre><code>from mongo_ops import BaseDocument, BaseRepository\nfrom pydantic import BaseModel, Field\nfrom typing import List, Optional, Generic, TypeVar\n\nT = TypeVar(\"T\")\n\nclass PaginatedResponse(BaseModel, Generic[T]):\n    items: List[T]\n    total: int\n    page: int\n    page_size: int\n    total_pages: int\n    has_next: bool\n    has_prev: bool\n\nclass BlogPost(BaseDocument):\n    title: str\n    content: str\n    author_id: str\n    published: bool = False\n    tags: List[str] = []\n    views: int = 0\n\nclass BlogPostRepository(BaseRepository[BlogPost]):\n    def __init__(self):\n        super().__init__(\"blog_posts\", BlogPost)\n\n    async def paginate(\n        self,\n        page: int = 1,\n        page_size: int = 10,\n        filter_dict: Optional[dict] = None,\n        sort_by: str = \"created_at\",\n        sort_order: int = -1\n    ) -&gt; PaginatedResponse[BlogPost]:\n        \"\"\"Get paginated blog posts\"\"\"\n        filter_dict = filter_dict or {}\n        skip = (page - 1) * page_size\n\n        # Get total count\n        total = await self.count(filter_dict)\n\n        # Get items\n        items = await self.get_many(\n            filter=filter_dict,\n            skip=skip,\n            limit=page_size,\n            sort=[(sort_by, sort_order)]\n        )\n\n        total_pages = (total + page_size - 1) // page_size\n\n        return PaginatedResponse(\n            items=items,\n            total=total,\n            page=page,\n            page_size=page_size,\n            total_pages=total_pages,\n            has_next=page &lt; total_pages,\n            has_prev=page &gt; 1\n        )\n\n    async def get_by_author(self, author_id: str, published_only: bool = True):\n        \"\"\"Get posts by author\"\"\"\n        filter_dict = {\"author_id\": author_id}\n        if published_only:\n            filter_dict[\"published\"] = True\n        return await self.get_many(filter=filter_dict, sort=[(\"created_at\", -1)])\n\n    async def search_by_tags(self, tags: List[str]) -&gt; List[BlogPost]:\n        \"\"\"Search posts by tags\"\"\"\n        return await self.get_many(filter={\"tags\": {\"$in\": tags}, \"published\": True})\n\n# Usage in FastAPI\n@app.get(\"/posts/\", response_model=PaginatedResponse[BlogPost])\nasync def list_posts(\n    page: int = 1,\n    page_size: int = 10,\n    published: Optional[bool] = None,\n    author_id: Optional[str] = None\n):\n    filter_dict = {}\n    if published is not None:\n        filter_dict[\"published\"] = published\n    if author_id:\n        filter_dict[\"author_id\"] = author_id\n\n    return await blog_repo.paginate(page, page_size, filter_dict)\n\n@app.get(\"/posts/author/{author_id}\", response_model=List[BlogPost])\nasync def posts_by_author(author_id: str, published: bool = True):\n    return await blog_repo.get_by_author(author_id, published)\n\n@app.get(\"/posts/tags\", response_model=List[BlogPost])\nasync def posts_by_tags(tags: List[str] = Query(...)):\n    return await blog_repo.search_by_tags(tags)\n</code></pre>"},{"location":"03_use_cases/05_soft_deletes/","title":"Soft Deletes","text":""},{"location":"03_use_cases/05_soft_deletes/#use-case-5-soft-deletes-pattern","title":"Use Case 5: Soft Deletes Pattern","text":"<p>Scenario: Implement soft delete functionality for data recovery.</p> Python<pre><code>from mongo_ops import BaseDocument, BaseRepository\nfrom datetime import datetime\nfrom typing import Optional\n\nclass SoftDeleteDocument(BaseDocument):\n    \"\"\"Base document with soft delete support\"\"\"\n    is_deleted: bool = False\n    deleted_at: Optional[datetime] = None\n    deleted_by: Optional[str] = None\n\nclass Task(SoftDeleteDocument):\n    title: str\n    description: str\n    assignee_id: str\n    status: str = \"pending\"\n    priority: str = \"medium\"\n\nclass SoftDeleteRepository(BaseRepository[T]):\n    \"\"\"Repository with soft delete operations\"\"\"\n\n    async def soft_delete(self, id: str, deleted_by: str = None) -&gt; Optional[T]:\n        \"\"\"Soft delete a document\"\"\"\n        return await self.update(id, {\n            \"is_deleted\": True,\n            \"deleted_at\": datetime.utcnow(),\n            \"deleted_by\": deleted_by\n        })\n\n    async def restore(self, id: str) -&gt; Optional[T]:\n        \"\"\"Restore a soft-deleted document\"\"\"\n        return await self.update(id, {\n            \"is_deleted\": False,\n            \"deleted_at\": None,\n            \"deleted_by\": None\n        })\n\n    async def get_active(self, skip: int = 0, limit: int = 100):\n        \"\"\"Get only non-deleted documents\"\"\"\n        return await self.get_many(\n            filter={\"is_deleted\": False},\n            skip=skip,\n            limit=limit\n        )\n\n    async def get_deleted(self, skip: int = 0, limit: int = 100):\n        \"\"\"Get deleted documents\"\"\"\n        return await self.get_many(\n            filter={\"is_deleted\": True},\n            skip=skip,\n            limit=limit\n        )\n\n    async def permanent_delete(self, id: str) -&gt; bool:\n        \"\"\"Permanently delete a document\"\"\"\n        return await self.delete(id)\n\nclass TaskRepository(SoftDeleteRepository[Task]):\n    def __init__(self):\n        super().__init__(\"tasks\", Task)\n\n# Usage in FastAPI\n@app.delete(\"/tasks/{task_id}\")\nasync def soft_delete_task(task_id: str, user_id: str):\n    task = await task_repo.soft_delete(task_id, deleted_by=user_id)\n    if not task:\n        raise HTTPException(status_code=404, detail=\"Task not found\")\n    return {\"message\": \"Task deleted\", \"task\": task}\n\n@app.post(\"/tasks/{task_id}/restore\")\nasync def restore_task(task_id: str):\n    task = await task_repo.restore(task_id)\n    if not task:\n        raise HTTPException(status_code=404, detail=\"Task not found\")\n    return {\"message\": \"Task restored\", \"task\": task}\n\n@app.get(\"/tasks/\", response_model=List[Task])\nasync def list_active_tasks(skip: int = 0, limit: int = 10):\n    return await task_repo.get_active(skip, limit)\n\n@app.get(\"/tasks/deleted\", response_model=List[Task])\nasync def list_deleted_tasks(skip: int = 0, limit: int = 10):\n    return await task_repo.get_deleted(skip, limit)\n</code></pre>"},{"location":"03_use_cases/06_multi_model/","title":"Multi Model","text":""},{"location":"03_use_cases/06_multi_model/#use-case-6-multi-model-service-with-registration","title":"Use Case 6: Multi-Model Service with Registration","text":"<p>Scenario: Complete microservice with multiple related models.</p> Python<pre><code>from mongo_ops import (\n    MongoConnectionManager,\n    BaseDocument,\n    BaseRepository,\n    ModelRegistry\n)\nfrom fastapi import FastAPI\nfrom contextlib import asynccontextmanager\n\n# Define Models\nclass User(BaseDocument):\n    username: str\n    email: str\n    role: str = \"user\"\n\nclass Post(BaseDocument):\n    title: str\n    content: str\n    author_id: str\n    likes: int = 0\n\nclass Comment(BaseDocument):\n    post_id: str\n    user_id: str\n    content: str\n\n# Define Repositories\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\nclass PostRepository(BaseRepository[Post]):\n    def __init__(self):\n        super().__init__(\"posts\", Post)\n\nclass CommentRepository(BaseRepository[Comment]):\n    def __init__(self):\n        super().__init__(\"comments\", Comment)\n\n# Register all models\nModelRegistry.register(\"users\", User, indexes=[(\"email\", 1), (\"username\", 1)])\nModelRegistry.register(\"posts\", Post, indexes=[(\"author_id\", 1), (\"created_at\", -1)])\nModelRegistry.register(\"comments\", Comment, indexes=[(\"post_id\", 1), (\"user_id\", 1)])\n\n# Setup FastAPI with lifespan\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n    await MongoConnectionManager.connect(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"social_app\"\n    )\n    await ModelRegistry.initialize_all()\n    yield\n    await MongoConnectionManager.disconnect()\n\napp = FastAPI(lifespan=lifespan)\n\n# Initialize repositories\nuser_repo = UserRepository()\npost_repo = PostRepository()\ncomment_repo = CommentRepository()\n\n# Endpoints\n@app.post(\"/users/\", response_model=User)\nasync def create_user(user: User):\n    return await user_repo.create(user)\n\n@app.post(\"/posts/\", response_model=Post)\nasync def create_post(post: Post):\n    return await post_repo.create(post)\n\n@app.post(\"/comments/\", response_model=Comment)\nasync def create_comment(comment: Comment):\n    return await comment_repo.create(comment)\n</code></pre>"},{"location":"03_use_cases/07_caching/","title":"Use Case 7: Caching for High\u2011Performance Reads","text":"<p>Scenario: A read\u2011heavy API (e.g., product catalog) benefits from an in\u2011memory cache or Redis cache to reduce latency and DB load.</p>"},{"location":"03_use_cases/07_caching/#1-whats-new","title":"1\ufe0f\u20e3 What\u2019s New?","text":"<ul> <li>Cache back\u2011ends: <code>InMemoryCacheBackend</code> (TTL + LRU) and <code>RedisCacheBackend</code> (JSON\u2011serialised values, pub/sub invalidation).</li> <li>Cache configuration via <code>CacheConfig</code> (<code>enabled</code>, <code>backend</code>, <code>default_ttl</code>, \u2026).</li> <li><code>CachedBaseRepository</code> extends <code>BaseRepository</code> and adds:</li> <li>Transparent ID\u2011based caching on <code>get_by_id</code>.</li> <li>Automatic cache population on <code>create</code>.</li> <li>Cache invalidation on <code>update</code>/<code>delete</code>.</li> <li>Utility methods <code>warm_cache(ids)</code> and <code>invalidate_cache(id)</code>.</li> </ul>"},{"location":"03_use_cases/07_caching/#2-quick-start","title":"2\ufe0f\u20e3 Quick Start","text":"Python<pre><code>from mongo_ops import (\n    BaseDocument,\n    CachedBaseRepository,\n    MongoConnectionManager,\n    ModelRegistry,\n    CacheConfig,\n)\nfrom mongo_ops.cache import InMemoryCacheBackend\nfrom bson import ObjectId\n\n# Define a model\nclass Product(BaseDocument):\n    name: str\n    price: float\n\n# Initialise cache backend (in\u2011memory example)\ncache = InMemoryCacheBackend(max_entries=10_000, default_ttl=300)\n# Register the cache so the registry can initialise it later\nModelRegistry.set_cache_backend(cache)\n\n# Repository with caching\nclass ProductRepo(CachedBaseRepository[Product]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"products\",\n            model=Product,\n            cache_backend=cache,\n            config=CacheConfig(enabled=True, backend=\"memory\")\n        )\n\n# FastAPI lifespan \u2013 initialise DB and cache\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"shop\"\n    ):\n        await ModelRegistry.initialize_all()\n        await ModelRegistry.initialize_cache()  # Starts background cleanup, etc.\n        yield\n</code></pre>"},{"location":"03_use_cases/07_caching/#3-using-the-repository","title":"3\ufe0f\u20e3 Using the Repository","text":"Python<pre><code>repo = ProductRepo()\n# Create \u2013 automatically caches the new document\nproduct = await repo.create(Product(name=\"Widget\", price=9.99))\n\n# Normal read \u2013 will hit the cache after the first DB fetch\nfetched = await repo.get_by_id(product.id)\n\n# Update \u2013 cache entry is refreshed\nawait repo.update(product.id, {\"price\": 8.99})\n\n# Delete \u2013 cache entry removed\nawait repo.delete(product.id)\n\n# Warm a set of IDs in advance (e.g., during a bulk load)\nawait repo.warm_cache([ObjectId(\"...\"), ObjectId(\"...\")])\n</code></pre>"},{"location":"03_use_cases/07_caching/#4-redis-backend-optional","title":"4\ufe0f\u20e3 Redis Backend (optional)","text":"<p>If you prefer a distributed cache, swap the backend:</p> Python<pre><code>from mongo_ops.cache import RedisCacheBackend\nfrom redis.asyncio import Redis\n\nredis_client = Redis(host=\"localhost\", port=6379)\nredis_backend = RedisCacheBackend(redis_client, key_prefix=\"prod:\")\nModelRegistry.set_cache_backend(redis_backend)\n</code></pre> <p>The repository code stays the same \u2013 just pass the <code>redis_backend</code> instance to <code>CachedBaseRepository</code>.</p>"},{"location":"03_use_cases/07_caching/#5-when-to-use-caching","title":"5\ufe0f\u20e3 When to Use Caching","text":"<ul> <li>Frequently accessed documents (e.g., product details, configuration settings).</li> <li>Low\u2011write\u2011to\u2011read ratios where cache invalidation cost is acceptable.</li> <li>Distributed deployments where a shared Redis cache syncs invalidations via pub/sub.</li> </ul>"},{"location":"03_use_cases/07_caching/#6-related-docs","title":"6\ufe0f\u20e3 Related Docs","text":"<ul> <li>Core Components \u2013 see <code>docs/02_components.md</code> for the <code>CacheBackend</code> abstraction.</li> <li>Best Practices \u2013 remember to call <code>ModelRegistry.initialize_cache()</code> after DB connection.</li> </ul> <p>Feel free to adapt the TTL, max entries, and backend to your workload.</p>"},{"location":"03_use_cases/08_population/","title":"Use Case 8: Document Population","text":"<p>Scenario: An API needs to return a single, denormalised JSON payload that includes related documents (e.g., a <code>User</code> with an embedded <code>Profile</code>, or an <code>Order</code> with its <code>LineItem</code>s) without the caller having to issue multiple requests.</p>"},{"location":"03_use_cases/08_population/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>PopulateRule</code> Declarative rule that tells the engine how to populate a field.Key attributes:\u2022 <code>field_name</code> \u2013 Target attribute on the source model.\u2022 <code>collection_name</code> \u2013 Collection that stores the referenced documents.\u2022 <code>ref_field</code> \u2013 Name of the reference field (normally an <code>ObjectId</code>).\u2022 Optional <code>nested_rules</code> for deep population, <code>max_depth</code> to bound recursion, and <code>filter</code> / <code>projection</code> for fine\u2011grained queries. <code>PopulationEngine</code> Core engine that resolves a list of <code>PopulateRule</code>s recursively. It:\u2022 Detects circular references and raises <code>CircularReferenceError</code>.\u2022 Honors per\u2011rule <code>max_depth</code> and a global <code>global_max_depth</code> (default\u202f10).\u2022 Supports MongoDB filters and projections for each populated relation. <code>PopulatingRepository</code> Extends <code>BaseRepository</code> with automatic population support. Stores a reference to a <code>PopulationEngine</code> and a list of <code>PopulateRule</code>s, exposing two helpers:\u2022 <code>_populate(document)</code> \u2013 Returns the same document with the requested relations populated.\u2022 <code>_depopulate(document)</code> \u2013 Strips populated fields (useful before serialisation). Cache\u2011aware population (optional) \u2013 The engine works with any <code>CacheBackend</code>. When used together with <code>CachedBaseRepository</code>, populated documents benefit from caching in the same way as regular CRUD results."},{"location":"03_use_cases/08_population/#quick-example","title":"\ud83d\ude80 Quick Example","text":"Python<pre><code>from bson import ObjectId\nfrom mongo_ops import BaseDocument, PopulatingRepository, ModelRegistry\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\nfrom mongo_ops.cache import InMemoryCacheBackend\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Define the data models\n# ----------------------------------------------------------------------\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n    bio: str = \"\"\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n    profile_id: ObjectId = None          # Reference to Profile\n    profile: Profile | None = None       # Populated field (filled by engine)\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 (Optional) Set up a cache; helpful for deep graphs\n# ----------------------------------------------------------------------\ncache = InMemoryCacheBackend(max_entries=10_000, default_ttl=300)\nModelRegistry.set_cache_backend(cache)\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Create a PopulationEngine \u2013 repositories will be registered later\n# ----------------------------------------------------------------------\nengine = PopulationEngine({})\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 Declare how the `profile` field should be populated\n# ----------------------------------------------------------------------\nprofile_rule = PopulateRule(\n    field_name=\"profile\",\n    collection_name=\"profiles\",\n    ref_field=\"profile_id\",\n    # No further nesting in this simple example\n)\n\n# ----------------------------------------------------------------------\n# 5\ufe0f\u20e3 Repository that uses the engine + rule\n# ----------------------------------------------------------------------\nclass UserRepository(PopulatingRepository[User]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"users\",\n            model=User,\n            population_engine=engine,\n            populate_rules=[profile_rule],\n        )\n\n# ----------------------------------------------------------------------\n# 6\ufe0f\u20e3 Register the repository with the engine so it can resolve refs\n# ----------------------------------------------------------------------\nengine.register_repo(\"profiles\", PopulatingRepository[Profile](\"profiles\", Profile))\nengine.register_repo(\"users\", UserRepository())\n\n# ----------------------------------------------------------------------\n# 7\ufe0f\u20e3 FastAPI lifespan \u2013 initialise DB, indexes, and the cache\n# ----------------------------------------------------------------------\nfrom mongo_ops import MongoConnectionManager\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"mydb\"\n    ):\n        await ModelRegistry.initialize_all()\n        # If you set up a cache backend (see step 2), initialize it here\n        await ModelRegistry.initialize_cache()\n        yield\n</code></pre>"},{"location":"03_use_cases/09_advanced_population/","title":"Use Case 9: Nested Document Population &amp; Circular\u2011Ref Handling","text":"<p>Scenario: A service must return an <code>Author</code> object with its <code>books</code> populated, and each <code>book</code> must include its <code>publisher</code>. The data model contains a possible circular reference (<code>Author.mentor_id</code> \u2192 another <code>Author</code>).</p>"},{"location":"03_use_cases/09_advanced_population/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>PopulateRule</code> (nested) Allows you to declare a hierarchy of rules. In this example we populate <code>books</code> on <code>Author</code>, then <code>publisher</code> on each <code>Book</code>. <code>max_depth</code> Prevents infinite recursion when circular references exist. Circular\u2011reference guard <code>PopulationEngine</code> raises <code>CircularReferenceError</code> if a cycle exceeds <code>max_depth</code> or is revisited."},{"location":"03_use_cases/09_advanced_population/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from bson import ObjectId\nfrom mongo_ops import BaseDocument, PopulatingRepository, ModelRegistry\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Define the data models\n# ----------------------------------------------------------------------\nclass Publisher(BaseDocument):\n    name: str = \"\"\n    country: str = \"\"\n\nclass Book(BaseDocument):\n    title: str = \"\"\n    publisher_id: ObjectId = None  # Reference to Publisher\n    publisher: Publisher | None = None\n\nclass Author(BaseDocument):\n    name: str = \"\"\n    book_ids: list[ObjectId] = []   # References to Book documents\n    books: list[Book] | None = None\n    mentor_id: ObjectId = None      # Optional circular reference to another Author\n    mentor: \"Author\" | None = None\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 Create a PopulationEngine\n# ----------------------------------------------------------------------\nengine = PopulationEngine({})\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Declare nested rules\n# ----------------------------------------------------------------------\n# Populate the Publisher inside each Book\nbook_rule = PopulateRule(\n    field_name=\"publisher\",\n    collection_name=\"publishers\",\n    ref_field=\"publisher_id\",\n)\n# Populate books on Author, nesting the book_rule\nauthor_rule = PopulateRule(\n    field_name=\"books\",\n    collection_name=\"books\",\n    ref_field=\"book_ids\",\n    nested_rules=[book_rule],\n    max_depth=3,  # safety net for deep graphs\n)\n# Optional mentor rule (demonstrates circular\u2011ref handling)\nmentor_rule = PopulateRule(\n    field_name=\"mentor\",\n    collection_name=\"authors\",\n    ref_field=\"mentor_id\",\n    max_depth=2,\n)\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 Repository that uses the engine + rules\n# ----------------------------------------------------------------------\nclass AuthorRepository(PopulatingRepository[Author]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"authors\",\n            model=Author,\n            population_engine=engine,\n            populate_rules=[author_rule, mentor_rule],\n        )\n\n# ----------------------------------------------------------------------\n# 5\ufe0f\u20e3 Register all repositories with the engine\n# ----------------------------------------------------------------------\nengine.register_repo(\"publishers\", PopulatingRepository[Publisher](\"publishers\", Publisher))\nengine.register_repo(\"books\", PopulatingRepository[Book](\"books\", Book))\nengine.register_repo(\"authors\", AuthorRepository())\n\n# ----------------------------------------------------------------------\n# 6\ufe0f\u20e3 FastAPI lifespan \u2013 initialise DB &amp; cache (if any)\n# ----------------------------------------------------------------------\nfrom mongo_ops import MongoConnectionManager\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"library\",\n    ):\n        await ModelRegistry.initialize_all()\n        await ModelRegistry.initialize_cache()\n        yield\n</code></pre>"},{"location":"03_use_cases/09_advanced_population/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Use <code>max_depth</code> conservatively; a value of <code>2\u20113</code> is enough for most graphs.</li> <li>When you know there are no cycles, you can omit <code>max_depth</code> on nested rules.</li> <li>The <code>CircularReferenceError</code> includes the visited path, which helps debugging.</li> </ul>"},{"location":"03_use_cases/10_cache_and_population/","title":"Use Case 10: Caching + Population (Read\u2011Through + Populated Docs)","text":"<p>Scenario: A service needs fast reads of a <code>User</code> document and its related <code>Profile</code>. The repository should cache the final populated result so subsequent calls hit the cache directly.</p>"},{"location":"03_use_cases/10_cache_and_population/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>CachedBaseRepository</code> Provides transparent ID\u2011based caching for CRUD operations. <code>PopulatingRepository</code> Adds automatic population of referenced documents. Combined usage By inheriting from <code>CachedBaseRepository</code> and wiring a <code>PopulationEngine</code>, the repository caches the populated document, eliminating both DB and population overhead on cache hits."},{"location":"03_use_cases/10_cache_and_population/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from bson import ObjectId\nfrom mongo_ops import BaseDocument, CachedBaseRepository, ModelRegistry\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\nfrom mongo_ops.cache import InMemoryCacheBackend\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Define models\n# ----------------------------------------------------------------------\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n    bio: str = \"\"\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n    profile_id: ObjectId = None        # Reference to Profile\n    profile: Profile | None = None     # Populated field\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 Initialise cache backend (in\u2011memory example)\n# ----------------------------------------------------------------------\ncache = InMemoryCacheBackend(max_entries=20_000, default_ttl=600)\nModelRegistry.set_cache_backend(cache)\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Set up a PopulationEngine (repositories will be registered later)\n# ----------------------------------------------------------------------\nengine = PopulationEngine({})\nprofile_rule = PopulateRule(\n    field_name=\"profile\",\n    collection_name=\"profiles\",\n    ref_field=\"profile_id\",\n)\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 Cached + Populating repository\n# ----------------------------------------------------------------------\nclass UserRepository(CachedBaseRepository[User]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"users\",\n            model=User,\n            cache_backend=cache,\n            config=None,  # defaults to enabled=True, backend=\"memory\"\n        )\n        # Attach the population engine after the base repo is ready\n        self.population_engine = engine\n        self._populate_rules = [profile_rule]\n\n    # Override get_by_id to include population before caching\n    async def get_by_id(self, id):\n        # First attempt cache lookup (as in CachedBaseRepository)\n        cached = await super().get_by_id(id)\n        if cached:\n            return cached\n        # Not in cache \u2013 fetch from DB and populate\n        doc = await super().get_by_id(id)  # this will hit the DB (no cache hit)\n        if doc is None:\n            return None\n        # Populate related docs\n        populated = await engine.populate(doc, self._populate_rules)\n        # Store the fully populated result in cache for next call\n        await self._cache.set(self._cache_key(id), populated)\n        return populated\n\n# ----------------------------------------------------------------------\n# 5\ufe0f\u20e3 Register repositories with the engine for population resolution\n# ----------------------------------------------------------------------\nengine.register_repo(\"profiles\", PopulatingRepository[Profile](\"profiles\", Profile))\nengine.register_repo(\"users\", UserRepository())\n\n# ----------------------------------------------------------------------\n# 6\ufe0f\u20e3 FastAPI lifespan \u2013 initialise DB, create indexes, and start cache cleanup\n# ----------------------------------------------------------------------\nfrom mongo_ops import MongoConnectionManager\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"app_db\",\n    ):\n        await ModelRegistry.initialize_all()\n        await ModelRegistry.initialize_cache()\n        yield\n</code></pre>"},{"location":"03_use_cases/10_cache_and_population/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>The example overrides <code>get_by_id</code> to keep the caching logic simple; you could also create a mixin that composes <code>CachedBaseRepository</code> and <code>PopulatingRepository</code>.</li> <li>Remember to call <code>await ModelRegistry.initialize_cache()</code> after the DB connection is ready; otherwise the background cleanup task will never start.</li> <li>Cache keys are generated by <code>CachedBaseRepository._cache_key(id)</code>. If you change the repository\u2019s <code>config.key_prefix</code>, the same prefix will be used for populated results.</li> </ul>"},{"location":"03_use_cases/11_cache_lifecycle/","title":"Use Case 11: Proper Cache Lifecycle in FastAPI","text":"<p>Scenario: A microservice uses <code>InMemoryCacheBackend</code> (or Redis) and needs to start the cache cleanup task when the app starts, then shut it down cleanly on termination.</p>"},{"location":"03_use_cases/11_cache_lifecycle/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>ModelRegistry.initialize_cache()</code> Starts the async background task for the registered cache backend. <code>ModelRegistry.shutdown_cache()</code> Gracefully stops the background task and releases resources. FastAPI lifespan integration Demonstrates where to call both init and shutdown methods."},{"location":"03_use_cases/11_cache_lifecycle/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from mongo_ops import MongoConnectionManager, ModelRegistry\nfrom mongo_ops.cache import InMemoryCacheBackend\nfrom contextlib import asynccontextmanager\n\n# Initialise a cache backend (in\u2011memory example)\ncache = InMemoryCacheBackend(max_entries=10_000, default_ttl=300)\nModelRegistry.set_cache_backend(cache)\n\n@asynccontextmanager\nasync def lifespan(app):\n    # Start MongoDB connection and cache background task\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"mydb\",\n    ):\n        await ModelRegistry.initialize_all()   # create indexes\n        await ModelRegistry.initialize_cache()  # start cache cleanup\n        yield\n    # FastAPI will exit the `with` block here \u2013 clean up cache\n    await ModelRegistry.shutdown_cache()\n</code></pre>"},{"location":"03_use_cases/11_cache_lifecycle/#why-a-separate-shutdown-step","title":"Why a separate shutdown step?","text":"<ul> <li>The cache backend may spawn an <code>asyncio.Task</code> that periodically removes expired entries. If the task is left dangling, the event loop may complain about pending tasks on shutdown.</li> <li><code>shutdown_cache()</code> cancels the internal task and waits for it to finish, ensuring a clean exit.</li> </ul>"},{"location":"03_use_cases/11_cache_lifecycle/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Register the cache before calling <code>initialize_cache()</code>; otherwise the registry won\u2019t know which backend to start.</li> <li>For Redis backends, the shutdown step also closes the underlying <code>redis.asyncio.Redis</code> client connection.</li> <li>You can also hook the shutdown into a FastAPI <code>@app.on_event(\"shutdown\")</code> handler if you prefer not to use the lifespan context manager.</li> </ul>"},{"location":"03_use_cases/12_transaction_helper/","title":"Use Case 12: Using <code>TransactionManager.execute_transaction</code>","text":"<p>Scenario: You need to perform several writes across different collections atomically (e.g., creating an <code>Order</code> and updating the <code>Inventory</code> for each ordered item). The low\u2011level <code>start_session</code> context manager works, but the high\u2011level <code>execute_transaction</code> helper makes the code cleaner and returns all operation results in a list.</p>"},{"location":"03_use_cases/12_transaction_helper/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>TransactionManager.execute_transaction</code> Accepts a list of async callables (each receiving a <code>session</code>) and executes them inside a single MongoDB transaction. Returns a list of each callable\u2019s result. Automatic rollback If any operation raises an exception, the transaction is aborted and the exception propagates."},{"location":"03_use_cases/12_transaction_helper/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from mongo_ops import MongoConnectionManager, ModelRegistry\nfrom mongo_ops.transactions import TransactionManager\nfrom mongo_ops.repository import BaseRepository\nfrom mongo_ops.models import BaseDocument\nfrom bson import ObjectId\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Define simple models\n# ----------------------------------------------------------------------\nclass Order(BaseDocument):\n    user_id: str\n    items: list[dict]  # [{\"product_id\": ObjectId, \"qty\": int}]\n    total: float = 0.0\n\nclass Inventory(BaseDocument):\n    product_id: ObjectId\n    quantity: int = 0\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 Repositories\n# ----------------------------------------------------------------------\nclass OrderRepo(BaseRepository[Order]):\n    def __init__(self):\n        super().__init__(\"orders\", Order)\n\nclass InventoryRepo(BaseRepository[Inventory]):\n    def __init__(self):\n        super().__init__(\"inventory\", Inventory)\n\norder_repo = OrderRepo()\ninv_repo = InventoryRepo()\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Transaction helper\n# ----------------------------------------------------------------------\nasync def create_order_with_inventory(order: Order):\n    async def insert_order(session):\n        # Insert the order document\n        doc = order.model_dump(exclude={\"id\"}, exclude_none=True)\n        doc[\"created_at\"] = doc[\"updated_at\"] = __import__(\"datetime\").datetime.utcnow()\n        result = await order_repo.collection.insert_one(doc, session=session)\n        return await order_repo.collection.find_one({\"_id\": result.inserted_id}, session=session)\n\n    async def update_inventory(session):\n        # Decrease quantity for each ordered item\n        for item in order.items:\n            await inv_repo.collection.update_one(\n                {\"product_id\": ObjectId(item[\"product_id\"])},\n                {\"$inc\": {\"quantity\": -item[\"qty\"]}},\n                session=session,\n            )\n        return \"inventory-updated\"\n\n    # Execute both operations atomically\n    results = await TransactionManager.execute_transaction([\n        lambda s: insert_order(s),\n        lambda s: update_inventory(s),\n    ])\n    # `results[0]` is the created order document, `results[1]` is the marker string\n    return results[0]\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 FastAPI lifespan \u2013 initialise DB and run the example endpoint\n# ----------------------------------------------------------------------\nfrom fastapi import FastAPI, HTTPException\nfrom contextlib import asynccontextmanager\n\napp = FastAPI()\n\n@asynccontextmanager\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"shop\",\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n\napp.lifespan = lifespan\n\n@app.post(\"/orders/\", response_model=Order)\nasync def create_order(order: Order):\n    created = await create_order_with_inventory(order)\n    if created is None:\n        raise HTTPException(status_code=400, detail=\"Transaction failed\")\n    return created\n</code></pre>"},{"location":"03_use_cases/12_transaction_helper/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Return values: Each callable can return whatever you need (inserted document, stats, etc.). The helper collects them in order.</li> <li>Error handling: Raising any exception inside a callable will abort the transaction automatically.</li> <li>Read\u2011only ops: You can also run queries inside the transaction \u2013 just pass <code>session=session</code> to the <code>find_one</code>/<code>find</code> calls.</li> <li>Testing: In unit tests you can mock <code>TransactionManager.start_session</code> to ensure the helpers are called.</li> </ul>"},{"location":"03_use_cases/13_index_creation/","title":"Use Case 13: Declaring Indexes (Single\u2011field, Composite, Unique)","text":"<p>Scenario: You want to ensure your collection has the right indexes for fast queries and data integrity. This doc shows how to register models with different index configurations using <code>ModelRegistry.register</code> and have them created automatically during startup.</p>"},{"location":"03_use_cases/13_index_creation/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>ModelRegistry.register</code> (indexes argument) Accepts a list of index specifications. Each spec can be a tuple <code>(field, direction)</code> or a full dict with <code>keys</code> and optional options (e.g., <code>unique</code>). <code>ModelRegistry.initialize_all</code> Scans all registered collections and creates the defined indexes on application start\u2011up."},{"location":"03_use_cases/13_index_creation/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from mongo_ops import ModelRegistry, BaseDocument\nfrom pymongo import ASCENDING, DESCENDING\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Simple single\u2011field index (e.g., email lookup)\n# ----------------------------------------------------------------------\nclass User(BaseDocument):\n    username: str\n    email: str\n\nModelRegistry.register(\n    collection_name=\"users\",\n    model=User,\n    indexes=[(\"email\", ASCENDING)],  # creates an index on \"email\"\n)\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 Composite index (e.g., queries filtering by user and creation date)\n# ----------------------------------------------------------------------\nclass BlogPost(BaseDocument):\n    author_id: str\n    created_at: str\n    title: str\n\nModelRegistry.register(\n    collection_name=\"posts\",\n    model=BlogPost,\n    indexes=[[(\"author_id\", ASCENDING), (\"created_at\", DESCENDING)]],  # compound index\n)\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Unique index (e.g., enforce unique usernames)\n# ----------------------------------------------------------------------\nModelRegistry.register(\n    collection_name=\"users\",\n    model=User,\n    indexes=[\n        {\n            \"keys\": [(\"username\", ASCENDING)],\n            \"options\": {\"unique\": True, \"name\": \"uq_username\"},\n        }\n    ],\n)\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 Initialise all indexes during FastAPI startup\n# ----------------------------------------------------------------------\nfrom mongo_ops import MongoConnectionManager\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"mydb\",\n    ):\n        # This will create every index declared above (if it does not already exist)\n        await ModelRegistry.initialize_all()\n        yield\n</code></pre>"},{"location":"03_use_cases/13_index_creation/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Idempotence: <code>initialize_all</code> uses <code>create_index</code>, which is safe to run multiple times \u2013 MongoDB will skip creation if the index already exists.</li> <li>Index options: You can also set <code>expireAfterSeconds</code> for TTL indexes, <code>sparse</code> for sparse indexes, etc., by adding them to the <code>options</code> dict.</li> <li>Verification: After the app starts, you can verify indexes with the Mongo shell:   JavaScript<pre><code>db.&lt;collection&gt;.getIndexes()\n</code></pre></li> </ul>"},{"location":"03_use_cases/14_testing_guide/","title":"Use Case 14: Testing Guide \u2013 Mocking Motor &amp; Population Engine","text":"<p>Scenario: You want to write unit tests for repositories that use async Motor collections and the <code>PopulationEngine</code> without connecting to a real MongoDB instance.</p>"},{"location":"03_use_cases/14_testing_guide/#whats-new","title":"\ud83d\udce6 What\u2019s New?","text":"Component Description <code>AsyncMock</code> for collections Allows you to stub <code>find_one</code>, <code>insert_one</code>, etc., and control returned data. Patching <code>MongoConnectionManager.get_database</code> Redirects repository initialization to a mock collection. Mocking <code>PopulationEngine</code> Replace the real engine with a lightweight stub that returns pre\u2011crafted objects. Example test files <code>tests/test_populating_repository.py</code> and <code>tests/test_transactions.py</code> are used as reference implementations."},{"location":"03_use_cases/14_testing_guide/#example-test-boilerplate","title":"\ud83d\ude80 Example Test Boilerplate","text":"Python<pre><code>import pytest\nfrom unittest.mock import AsyncMock, patch\nfrom bson import ObjectId\n\nfrom mongo_ops.models import BaseDocument\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\nfrom mongo_ops.repository import PopulatingRepository\n\n# ----------------------------------------------------------------------\n# 1\ufe0f\u20e3 Define simple models (same as in the library tests)\n# ----------------------------------------------------------------------\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n\nclass User(BaseDocument):\n    name: str = \"\"\n    profile_id: ObjectId | None = None\n    profile: Profile | None = None\n\n# ----------------------------------------------------------------------\n# 2\ufe0f\u20e3 Fixture \u2013 mock Motor collection\n# ----------------------------------------------------------------------\n@pytest.fixture\ndef mock_collection():\n    return AsyncMock()\n\n# ----------------------------------------------------------------------\n# 3\ufe0f\u20e3 Fixture \u2013 mock PopulationEngine (optional)\n# ----------------------------------------------------------------------\n@pytest.fixture\ndef engine():\n    # Provide a real engine but replace the repo for \"profiles\" with a mock\n    profile_repo = AsyncMock()\n    return PopulationEngine({\"profiles\": profile_repo})\n\n# ----------------------------------------------------------------------\n# 4\ufe0f\u20e3 Fixture \u2013 repository under test\n# ----------------------------------------------------------------------\n@pytest.fixture\ndef repo(mock_collection, engine):\n    with patch(\"mongo_ops.repository.MongoConnectionManager.get_database\") as mock_db:\n        mock_db.return_value.__getitem__.return_value = mock_collection\n        repo = PopulatingRepository(\n            \"users\",\n            User,\n            population_engine=engine,\n            populate_rules=[\n                PopulateRule(\n                    field_name=\"profile\",\n                    collection_name=\"profiles\",\n                    ref_field=\"profile_id\",\n                )\n            ],\n        )\n        repo.collection = mock_collection\n        return repo\n\n# ----------------------------------------------------------------------\n# 5\ufe0f\u20e3 Test \u2013 `get_by_id` populates the related document\n# ----------------------------------------------------------------------\n@pytest.mark.asyncio\nasync def test_get_by_id_populates(repo, mock_collection, engine):\n    # Arrange \u2013 user document returned from the DB\n    uid = ObjectId()\n    pid = ObjectId()\n    mock_collection.find_one.return_value = {\n        \"_id\": uid,\n        \"name\": \"Alice\",\n        \"profile_id\": pid,\n        \"created_at\": \"2024-01-01T00:00:00\",\n        \"updated_at\": \"2024-01-01T00:00:00\",\n    }\n    # Mock the profile repo to return a concrete Profile instance\n    engine._repos[\"profiles\"].get_by_id.return_value = Profile(id=pid, avatar_url=\"pic.png\")\n\n    # Act\n    result = await repo.get_by_id(uid)\n\n    # Assert\n    assert result is not None\n    assert result.name == \"Alice\"\n    assert result.profile is not None\n    assert result.profile.avatar_url == \"pic.png\"\n\n# ----------------------------------------------------------------------\n# 6\ufe0f\u20e3 Test \u2013 transaction helper uses the real `TransactionManager`\n# ----------------------------------------------------------------------\nfrom mongo_ops.transactions import TransactionManager\n\n@pytest.mark.asyncio\nasync def test_execute_transaction(monkeypatch):\n    # Fake a Motor client session that records calls\n    async def fake_op(session):\n        return \"ok\"\n    # Execute with the helper \u2013 it should return a list with the result\n    results = await TransactionManager.execute_transaction([fake_op])\n    assert results == [\"ok\"]\n</code></pre>"},{"location":"03_use_cases/14_testing_guide/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Never hit the network: All DB calls are mocked, so tests run instantly.</li> <li>Reuse fixtures: Keep the <code>mock_collection</code> and <code>engine</code> fixtures in a <code>conftest.py</code> file for other repo tests.</li> <li>Coverage: The same pattern works for <code>CachedBaseRepository</code> \u2013 just mock <code>cache_backend</code> methods (<code>get</code>, <code>set</code>, <code>delete</code>).</li> <li>AsyncTestCase: If you prefer <code>unittest</code> style, use <code>IsolatedAsyncioTestCase</code> from Python 3.8+.</li> </ul>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"\ud83e\udde9 mongo-ops \u2014 Async MongoDB Operations Layer for FastAPI","text":"<p><code>mongo-ops</code> is a modular, high-performance MongoDB operations library for FastAPI microservices. It standardizes connection lifecycle, Pydantic v2 document models, and repository-style async CRUD \u2014 with added layers for caching, reference population, and multi-document transactions. It is built on top of Motor.</p> <p>Doc model: this wiki is written for humans \u2014 how\u2011to guides, examples, and testing recipes. The authoritative API contracts live in the code (docstrings) and the machine\u2011readable bundle under <code>docs/mcp/</code>.</p>"},{"location":"#key-features","title":"\ud83d\ude80 Key Features","text":"<ul> <li>\ud83e\uddf1 Unified repository pattern \u2014 <code>BaseRepository</code> with generic CRUD</li> <li>\u26a1 Fully asynchronous (Motor-based)</li> <li>\ud83e\uddec Pydantic v2 data models with auto\u2011timestamps (<code>BaseDocument</code>)</li> <li>\ud83d\udd12 Model registry for multi-collection startup (<code>ModelRegistry</code>)</li> <li>\ud83d\uddc4\ufe0f ID-based caching \u2014 in-memory or Redis (<code>cache/</code>)</li> <li>\ud83d\udd17 Reference population with cycle detection (<code>populate/</code>)</li> <li>\ud83d\udd01 Transaction and session helpers (<code>transactions/</code>)</li> <li>\ud83e\uddea Mock-friendly architecture \u2014 the whole repo test suite runs without MongoDB</li> </ul>"},{"location":"#installation","title":"\ud83d\udce6 Installation","text":"<p>From your internal PyPI:</p> Bash<pre><code>pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple mongo-ops\n</code></pre> <p>With the extra batteries your workload needs:</p> Bash<pre><code>pip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple \"mongo-ops[redis]\"   # Redis cache backend\npip install --extra-index-url https://$PYPI_USERNAME:$PYPI_PASSWORD@pip.aetoskia.com/simple \"mongo-ops[all]\"     # dev, redis, beanie, fastapi\n</code></pre> <p>From local source:</p> Bash<pre><code>pip install -e .\n</code></pre>"},{"location":"#documentation-structure","title":"\ud83d\udcc1 Documentation Structure","text":"Section Description Overview Architecture, lifecycle, and repository decision table Core Components Validated reference for the public API surface Use cases Step-by-step recipes \u00b7 01 \u2013 Basic CRUD API FastAPI user management app \u00b7 02 \u2013 Custom repository Product catalog with business logic \u00b7 03 \u2013 Transactions Atomic order + inventory updates \u00b7 04 \u2013 Pagination Filtering, sorting, page metadata \u00b7 05 \u2013 Soft deletes Recoverable delete pattern \u00b7 06 \u2013 Multi-model One service, many collections \u00b7 07 \u2013 Caching In-memory / Redis read cache \u00b7 08 \u2013 Population Resolve references on read \u00b7 09 \u2013 Advanced population Nested + circular references \u00b7 10 \u2013 Cache + population Reading through cache, populating on hit \u00b7 11 \u2013 Cache lifecycle Startup/shutdown hygiene \u00b7 12 \u2013 Transaction helper <code>execute_transaction</code> \u00b7 13 \u2013 Indexes Single, compound, and optioned indexes \u00b7 14 \u2013 Testing guide Mock Motor, engine, cache, transactions Best Practices Layering, lifecycle, and gotchas Common Patterns Service layer, aggregation, bulk ops Error Handling Library exceptions and FastAPI mapping Testing Example Mock-based quickstart"},{"location":"#related-resources","title":"\ud83d\udd17 Related Resources","text":"<ul> <li>Source Code: Gitea Repository</li> <li>Internal PyPI: pip.aetoskia.com/simple/mongo-ops</li> <li>Drone CI: Auto-builds and publishes tagged releases, gated on black / ruff / mypy / pytest.</li> </ul> <p>\u00a9 Aetoskia Internal \u2014 <code>mongo-ops</code> 0.1.5</p>"},{"location":"01_overview/","title":"Library Overview","text":"<p><code>mongo-ops</code> gives FastAPI/microservice teams a small, opinionated toolkit for talking to MongoDB asynchronously. This page builds the mental model: what the layers are, in what order they must be wired up, and which repository to reach for.</p>"},{"location":"01_overview/#architecture","title":"\ud83c\udfd7\ufe0f Architecture","text":"Text Only<pre><code>\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502  Application (FastAPI)                                    \u2502\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502  \u2502 CachedBase  \u2502 Populating    \u2502 BaseRepository\u2502  Raw    \u2502 \u2502\n\u2502  \u2502 Repository  \u2502 Repository    \u2502 (CRUDMixin)   \u2502 Motor   \u2502 \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502         \u2502              \u2502               \u2502                   \u2502\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2510  \u250c\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502  \u2502 Cache backend\u2502  \u2502 Population\u2502  \u2502 TransactionManager    \u2502 \u2502\n\u2502  \u2502 memory/redis \u2502  \u2502 Engine    \u2502  \u2502 (session helpers)     \u2502 \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2514\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2518  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502  \u2502 ModelRegistry  (models, indexes, cache lifecycle)      \u2502 \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u2502\n\u2502  \u2502 MongoConnectionManager  (Motor client + database)      \u2502 \u2502\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                              \u25bc\n                        MongoDB (Motor / PyMongo)\n</code></pre> <p>The layers build on each other:</p> <ol> <li>Connection \u2014 <code>MongoConnectionManager</code> owns the Motor client and active database.</li> <li>Models \u2014 <code>BaseDocument</code> (Pydantic v2) gives every document <code>id</code> (aliased <code>_id</code>) plus <code>created_at</code> / <code>updated_at</code>.</li> <li>CRUD \u2014 <code>CRUDMixin</code> / <code>BaseRepository</code> implement generic async CRUD against a collection.</li> <li>Startup \u2014 <code>ModelRegistry</code> centralizes model + index registration and cache lifecycle for multi-collection services.</li> <li>Advanced layers \u2014 caching and population compose around a repository:</li> <li><code>CachedBaseRepository</code> wraps <code>BaseRepository</code> with a <code>CacheBackend</code>.</li> <li><code>PopulatingRepository</code> wraps <code>BaseRepository</code> with a <code>PopulationEngine</code>.</li> <li>Transactions \u2014 <code>TransactionManager</code> runs a list of async operations atomically on a session.</li> </ol>"},{"location":"01_overview/#lifecycle-rules","title":"\ud83d\udd04 Lifecycle Rules","text":"<p><code>mongo-ops</code> has a strict startup order. Violating it raises fast, loud exceptions:</p> Step Call Why 1 <code>await MongoConnectionManager.connect(uri, db_name)</code> Without a connection, <code>get_database()</code>/<code>get_client()</code> raise <code>RuntimeError(\"Database not connected...\")</code>. 2 <code>await ModelRegistry.initialize_all()</code> Create registered indexes (idempotent via <code>create_index</code>). 3 <code>await ModelRegistry.set_cache_backend(...)</code> then <code>await ModelRegistry.initialize_cache()</code> Must happen after connection, before any cache-backed operation. Raises <code>RuntimeError(\"No cache backend registered...\")</code> if skipped. 4 Use repositories Constructed repos resolve the collection from the live database. 5 <code>await ModelRegistry.shutdown_cache()</code> + <code>await MongoConnectionManager.disconnect()</code> On shutdown (in-memory TTL task cancelled; Redis pub/sub closed). <p>The canonical wiring is the FastAPI lifespan context manager (see use case 01).</p>"},{"location":"01_overview/#which-repository-should-you-use","title":"\ud83e\udded Which Repository Should You Use?","text":"Repository Use when Adds <code>BaseRepository[T]</code> Plain CRUD \u2014 the default nothing extra <code>CachedBaseRepository[T]</code> Read\u2011heavy, low\u2011write fields (lookups by <code>_id</code>) cache\u2011first <code>get_by_id</code>, cache on <code>create</code>, invalidate on <code>update</code>/<code>delete</code>, <code>warm_cache</code> <code>PopulatingRepository[T]</code> You return related docs (FK references) denormalized <code>_populate</code> on read, <code>_depopulate</code> on write, FK\u2011guarded <code>patch</code> <code>CRUDMixin</code> Reusing CRUD inside an existing class raw CRUD against a collection you already have <p>There is no built\u2011in <code>CachedPopulatingRepository</code>. Use case 10 shows how to compose caching + population in a small subclass.</p>"},{"location":"01_overview/#read-next","title":"\u27a1\ufe0f Read Next","text":"<ul> <li>Core Components \u2014 the validated public API surface.</li> <li>Use case 01 \u2014 the minimal FastAPI app.</li> <li>Best Practices \u2014 team-wide conventions.</li> </ul>"},{"location":"02_components/","title":"Core Components","text":"<p>A validated reference to the public API. Signatures match the code in <code>mongo_ops/</code> exactly. See the use cases for runnable recipes.</p>"},{"location":"02_components/#1-mongoconnectionmanager","title":"1. MongoConnectionManager","text":"<p>Singleton-style owner of the Motor client and active database.</p> Method Signature Behavior <code>connect</code> <code>async (uri: str, db_name: str, **kwargs) -&gt; AsyncIOMotorDatabase</code> Creates <code>AsyncIOMotorClient(uri, **kwargs)</code> and selects the database. Idempotent. <code>disconnect</code> <code>async () -&gt; None</code> Closes the client and clears state. <code>get_database</code> <code>() -&gt; AsyncIOMotorDatabase</code> Returns the active database; raises <code>RuntimeError(\"Database not connected. Call connect() first.\")</code>. <code>get_client</code> <code>() -&gt; AsyncIOMotorClient</code> Returns the active client; raises <code>RuntimeError(\"Client not connected. Call connect() first.\")</code>. <code>lifespan</code> <code>async ctx manager (uri, db_name, **kwargs)</code> <code>connect()</code> on entry, yields the database, <code>disconnect()</code> on exit. Designed for FastAPI lifespan."},{"location":"02_components/#2-basedocument-pyobjectid","title":"2. BaseDocument &amp; PyObjectId","text":"<p><code>BaseDocument(BaseModel)</code> \u2014 inherit for every Mongo entity.</p> <ul> <li><code>id: Optional[PyObjectId]</code> \u2014 aliased to <code>_id</code>, serialized to <code>str</code>.</li> <li><code>created_at: datetime</code> \u2014 defaults to <code>datetime.utcnow()</code>.</li> <li><code>updated_at: datetime</code> \u2014 defaults to <code>datetime.utcnow()</code>.</li> <li><code>Config.populate_by_name = True</code>, <code>arbitrary_types_allowed = True</code>, <code>json_encoders = {ObjectId: str}</code>.</li> </ul> <p><code>PyObjectId(ObjectId)</code> \u2014 Pydantic v2-compatible <code>ObjectId</code> that accepts <code>str</code> or <code>ObjectId</code> and validates with <code>ObjectId.is_valid</code>.</p>"},{"location":"02_components/#3-crudmixint","title":"3. CRUDMixin[T]","text":"<p>Generic CRUD over a Motor collection. The building block of all repositories.</p> Method Signature Notes <code>create</code> <code>async (data: T) -&gt; T</code> Dumps model (excludes <code>id</code>, <code>None</code>), stamps <code>created_at</code>/<code>updated_at</code>, inserts, returns model with assigned <code>_id</code>. <code>get_by_id</code> <code>async (id: str \\| ObjectId) -&gt; Optional[T]</code> <code>str</code> is accepted and converted to <code>ObjectId</code>. <code>get_many</code> <code>async (filter: dict \\| None = None, skip: int = 0, limit: int = 100, sort: list[tuple] \\| None = None) -&gt; list[T]</code> Cursor <code>.skip().limit().sort(...)</code> then <code>to_list(limit)</code>. <code>limit=0</code> disables the limit clause. <code>update</code> <code>async (id, data: dict[str, Any]) -&gt; Optional[T]</code> <code>$set</code> + refreshed <code>updated_at</code> via <code>find_one_and_update</code>. <code>patch</code> <code>async (id, data: dict[str, Any]) -&gt; Optional[T]</code> Same as <code>update</code> but intended for REST PATCH semantics. <code>delete</code> <code>async (id) -&gt; bool</code> True if a document was deleted. <code>count</code> <code>async (filter: dict \\| None = None) -&gt; int</code> <code>count_documents</code>."},{"location":"02_components/#4-baserepositoryt","title":"4. BaseRepository[T]","text":"<p><code>BaseRepository(collection_name: str, model: type[T])</code> \u2014 resolves the collection from <code>MongoConnectionManager.get_database()[collection_name]</code>. Requires an active connection at construction time. Provides everything in <code>CRUDMixin</code> plus <code>collection_name</code>.</p>"},{"location":"02_components/#5-populatingrepositoryt","title":"5. PopulatingRepository[T]","text":"<p><code>PopulatingRepository(collection_name, model, population_engine: PopulationEngine | None = None, populate_rules: list[PopulateRule] | None = None)</code>.</p> <ul> <li><code>set_population_engine(engine)</code> / <code>set_populate_rules(rules)</code> \u2014 swap engine/rules at runtime.</li> <li><code>data_to_model</code> hooks <code>_populate</code> \u2014 <code>get_by_id</code>/<code>get_many</code> return fully populated models.</li> <li><code>_depopulate(document)</code> \u2014 collapses populated FK fields back to <code>ObjectId</code> before <code>create</code>/<code>update</code>.</li> <li><code>create</code> / <code>update</code> accept a model <code>T</code> (not a dict) so depopulation can run.</li> <li><code>patch</code> blocks FK fields \u2014 raises <code>ValueError(\"Cannot patch FK fields via patch(): ... Use update() to change FK fields.\")</code>.</li> </ul> <p>Populate semantics (important): a <code>PopulateRule</code> names a field that holds either an <code>ObjectId</code> or a <code>list[ObjectId]</code> and is the same field that gets replaced with the resolved document(s). There is no separate \"ref field\" vs \"target field\". See use case 08.</p>"},{"location":"02_components/#6-transactionmanager","title":"6. TransactionManager","text":"Method Signature Behavior <code>start_session</code> <code>async ctx manager (**kwargs) -&gt; AsyncIOMotorClientSession</code> Yields a session with an active transaction. Pass <code>session=</code> to every collection call inside. <code>execute_transaction</code> <code>async (operations: list[Callable[[session], Awaitable[Any]]], **kwargs) -&gt; list[Any]</code> Runs each op inside one transaction and returns results in order; any exception aborts the transaction and propagates."},{"location":"02_components/#7-modelregistry","title":"7. ModelRegistry","text":"<p>Centralized models, indexes, and cache lifecycle for multi-collection services.</p> Method Signature Behavior <code>register</code> <code>(collection_name: str, model: type[BaseDocument], indexes: list[Any] \\| None = None)</code> Records model + index specs. Index specs are passed as-is to pymongo <code>create_index</code> \u2014 single tuples, compound lists, or dicts with <code>keys</code>/<code>options</code>. <code>initialize_all</code> <code>async (db: AsyncIOMotorDatabase \\| None = None) -&gt; None</code> <code>create_index</code> per registered spec (idempotent). Uses the manager database if <code>db</code> omitted. <code>get_model</code> <code>(collection_name) -&gt; type[BaseDocument]</code> Raises <code>KeyError</code> if unregistered. <code>list_collections</code> <code>() -&gt; list[str]</code> Registered collection names. <code>set_cache_backend</code> <code>(backend: CacheBackend) -&gt; None</code> Register the single shared backend. <code>initialize_cache</code> <code>async () -&gt; None</code> Starts the backend (background TTL cleanup) \u2014 raises <code>RuntimeError</code> if no backend registered. <code>shutdown_cache</code> <code>async () -&gt; None</code> Stops the backend cleanly and clears it. <code>get_cache_backend</code> <code>() -&gt; Optional[CacheBackend]</code> Current backend, if any."},{"location":"02_components/#8-cache-layer","title":"8. Cache Layer","text":""},{"location":"02_components/#81-cachebackend-abstract","title":"8.1 CacheBackend (abstract)","text":"<p>Async interface: <code>get(key) -&gt; Optional[bytes]</code>, <code>set(key, value: bytes, ttl | None)</code>, <code>delete(key)</code>, <code>exists(key)</code>, <code>clear_pattern(pattern)</code>, <code>get_stats() -&gt; CacheStats</code>, <code>initialize()</code>, <code>shutdown()</code>. Values are bytes (JSON-encoded).</p>"},{"location":"02_components/#82-cachestats","title":"8.2 CacheStats","text":"<p>Dataclass: <code>hits</code>, <code>misses</code>, <code>sets</code>, <code>deletes</code>, <code>current_size</code>, <code>max_size</code>.</p>"},{"location":"02_components/#83-cacheconfig","title":"8.3 CacheConfig","text":"<p>Dataclass: <code>enabled: bool = True</code>, <code>backend: Literal[\"memory\", \"redis\"] = \"memory\"</code>, <code>redis_client</code>, <code>default_ttl: int = 300</code>, <code>max_entries: int = 10000</code>, <code>key_prefix: str = \"\"</code>, <code>cleanup_interval: int = 60</code>. Raises <code>ValueError</code> if <code>backend=\"redis\"</code> without a client, and <code>ImportError</code> if <code>redis</code> is not installed.</p>"},{"location":"02_components/#84-inmemorycachebackend","title":"8.4 InMemoryCacheBackend","text":"<p><code>InMemoryCacheBackend(max_entries=10000, default_ttl=300, cleanup_interval=60)</code> \u2014 LRU <code>OrderedDict</code> + TTL heap; <code>initialize()</code> spawns the periodic cleanup task (TTL 0 expires immediately).</p>"},{"location":"02_components/#85-rediscachebackend","title":"8.5 RedisCacheBackend","text":"<p><code>RedisCacheBackend(redis_client, key_prefix=\"\", default_ttl=300)</code> \u2014 <code>setex</code> storage, SCAN-based <code>clear_pattern</code>, and <code>publish_invalidate(key)</code> for cross-service invalidation on <code>delete</code> via the <code>mongo_ops:cache:invalidate</code> channel.</p>"},{"location":"02_components/#86-cachedbaserepositoryt","title":"8.6 CachedBaseRepository[T]","text":"<p><code>CachedBaseRepository(collection_name, model, cache_backend: CacheBackend, config: CacheConfig | None = None)</code>.</p> <ul> <li>Cache keys are <code>\"{key_prefix}{id}\"</code> (prefix defaults to <code>\"{collection_name}:\"</code>).</li> <li><code>get_by_id</code> \u2014 cache-first; cache miss reads DB and stores <code>model_dump(by_alias=True)</code> (JSON-encoded) for <code>default_ttl</code>. Honors <code>config.enabled=False</code> (bypass).</li> <li><code>create</code> \u2014 inserts then caches the result.</li> <li><code>update</code>/<code>delete</code> \u2014 refresh or remove the cache entry.</li> <li><code>warm_cache(ids) -&gt; int</code> \u2014 prefetch a list of IDs, returns count warmed.</li> <li><code>invalidate_cache(id)</code> \u2014 manual eviction.</li> </ul>"},{"location":"02_components/#9-population-layer","title":"9. Population Layer","text":""},{"location":"02_components/#91-populaterule","title":"9.1 PopulateRule","text":"<p>Dataclass:</p> Python<pre><code>@dataclass\nclass PopulateRule:\n    field_name: str          # field holding the ObjectId / list[ObjectId]; replaced in-place with the resolved doc(s)\n    collection_name: str     # collection the references point at\n    nested_rules: list[PopulateRule] | None = None\n    max_depth: int = 1\n    filter: dict | None = None      # DECLARED but NOT yet applied by the engine\n    projection: dict | None = None  # DECLARED but NOT yet applied by the engine\n</code></pre> <p>\u26a0\ufe0f <code>filter</code> and <code>projection</code> are accepted but currently ignored by <code>PopulationEngine</code> \u2014 do not rely on them yet.</p>"},{"location":"02_components/#92-populationengine","title":"9.2 PopulationEngine","text":"<p><code>PopulationEngine(repos: dict[str, Any], global_max_depth: int = 10)</code> \u2014 <code>repos</code> maps <code>collection_name</code> \u2192 repository.</p> <ul> <li><code>register_repo(collection_name, repo)</code> \u2014 add repositories at runtime.</li> <li><code>populate(document, rules, depth=0)</code> \u2014 resolves refs recursively, replacing <code>field_name</code> in place; raises <code>CircularReferenceError(collection, doc_id, path)</code> when a <code>(Class, id)</code> pair is revisited.</li> <li><code>depopulate(document, rules)</code> \u2014 collapse populated docs back to IDs (for storage).</li> <li><code>global_max_depth</code> caps recursion; per-rule <code>max_depth</code> bounds a rule's descent.</li> </ul>"},{"location":"02_components/#93-circularreferenceerrorvalueerror","title":"9.3 CircularReferenceError(ValueError)","text":"<p>Holds <code>collection</code>, <code>doc_id</code>, and the visited <code>path</code> for debugging cycle messages.</p>"},{"location":"02_components/#related","title":"Related","text":"<ul> <li>Use case 01 \u2013 Basic CRUD \u00b7 07 \u2013 Caching \u00b7 08 \u2013 Population</li> </ul>"},{"location":"04_best_practices/","title":"Best Practices","text":"<p>Team-wide conventions for building fast, testable MongoDB services with <code>mongo-ops</code>.</p>"},{"location":"04_best_practices/#layering","title":"\ud83c\udfd7\ufe0f Layering","text":"<ol> <li>One repository per collection. Encapsulate every query the domain needs behind repository methods; keep Mongo details (<code>$regex</code>, <code>$inc</code>, projections) inside the repository.</li> <li>Keep models thin. <code>BaseDocument</code> for the shape; use Pydantic <code>Field</code> constraints for validation; never put business rules in the model.</li> <li>Use services for cross-repository logic. A <code>Service</code> composes multiple repositories (and <code>TransactionManager</code>) \u2014 routes stay thin.</li> <li>Expose <code>get_many(filter=..., skip=..., limit=..., sort=...)</code> instead of raw <code>find</code> for list endpoints \u2014 you get controlled pagination for free.</li> </ol>"},{"location":"04_best_practices/#lifecycle","title":"\ud83d\udd04 Lifecycle","text":"<ol> <li>Connect once, in the lifespan. <code>MongoConnectionManager.lifespan(...)</code> (or explicit <code>connect</code>/<code>disconnect</code>) \u2014 never lazily per request.</li> <li>Construct repositories after <code>connect()</code>. Module-level <code>Repo()</code> before connection raises <code>RuntimeError(\"Database not connected...\")</code>. Use dependencies or construct inside the lifespan/request.</li> <li>Order the cache lifecycle strictly: <code>set_cache_backend(backend)</code> \u2192 <code>initialize_cache()</code> (after connect, before use) \u2192 <code>shutdown_cache()</code> on exit.</li> <li>Register all models up front via <code>ModelRegistry.register(...)</code> and let <code>initialize_all()</code> create indexes once at startup (idempotent).</li> </ol>"},{"location":"04_best_practices/#data-performance","title":"\ud83d\uddc4\ufe0f Data &amp; Performance","text":"<ol> <li>Declare indexes for every hot query. Single-field, composite, and optioned (unique/TTL) specs all work via <code>ModelRegistry.register</code> \u2014 see use case 13.</li> <li>Cache only hot, low-write <code>_id</code> reads. Use <code>CachedBaseRepository</code> for lookups-by-id; invalidate (<code>update</code>/<code>delete</code> handle it) and pick a sensible <code>default_ttl</code>.</li> <li>Populate at the repository boundary. <code>PopulatingRepository</code> resolves refs on read and depopulates on write; do not hand-roll joins in endpoints.</li> <li>Respect the populate invariants: rules name the field that holds the reference and that is replaced; <code>patch()</code> cannot touch FK fields \u2014 use <code>update()</code>.</li> </ol>"},{"location":"04_best_practices/#transactions-errors","title":"\ud83d\udd01 Transactions &amp; Errors","text":"<ol> <li>Use transactions for multi-document writes. <code>TransactionManager.start_session</code> (inline) or <code>execute_transaction</code> (list of ops) \u2014 and pass <code>session=</code> to every collection call inside.</li> <li>Handle the library's real exceptions at the edges: <code>DuplicateKeyError</code> \u2192 409, <code>InvalidId</code> \u2192 400, <code>CircularReferenceError</code> \u2192 409, <code>ValueError</code> guides \u2192 400/422 (see Error Handling).</li> </ol>"},{"location":"04_best_practices/#testing","title":"\ud83e\uddea Testing","text":"<ol> <li>Default to mock-based unit tests. Patch <code>MongoConnectionManager.get_database</code>, use <code>AsyncMock</code> collections and cursor chains \u2014 the whole suite runs without MongoDB (use case 14).</li> <li>Mirror the library tests. <code>tests/test_{repository,populating_repository,cache,registry,transactions}.py</code> are canonical examples of every pattern above.</li> <li>Use type hints end-to-end \u2014 mypy-gated CI (see pyproject) catches drift early.</li> </ol>"},{"location":"04_best_practices/#related","title":"Related","text":"<ul> <li>Overview \u00b7 Core Components \u00b7 Use Cases</li> </ul>"},{"location":"05_patterns/","title":"Common Patterns","text":"<p>Reusable code shapes built on <code>BaseRepository</code> and friends.</p>"},{"location":"05_patterns/#pattern-1-service-layer-with-repository","title":"Pattern 1: Service Layer with Repository","text":"<p>Keep orchestration out of routes. A service composes one or more repositories and owns the domain rules.</p> Python<pre><code>from mongo_ops import BaseRepository, BaseDocument\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n\n\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n    async def find_by_email(self, email: str) -&gt; User | None:\n        doc = await self.collection.find_one({\"email\": email})\n        return self.model(**doc) if doc else None\n\n\nclass UserService:\n    def __init__(self, user_repo: UserRepository):\n        self.user_repo = user_repo\n\n    async def register_user(self, username: str, email: str) -&gt; User:\n        if await self.user_repo.find_by_email(email):\n            raise ValueError(\"Email already exists\")\n        return await self.user_repo.create(User(username=username, email=email))\n</code></pre> <p>Register a unique index on <code>email</code> via <code>ModelRegistry</code> so the race is also caught by <code>DuplicateKeyError</code> \u2014 see use case 13.</p>"},{"location":"05_patterns/#pattern-2-aggregation-pipeline","title":"Pattern 2: Aggregation Pipeline","text":"<p>Aggregations hit the raw Motor collection \u2014 wrap them in a repository method so callers stay at the domain level.</p> Python<pre><code>from mongo_ops import BaseRepository, BaseDocument\n\n\nclass Post(BaseDocument):\n    author_id: str = \"\"\n    title: str = \"\"\n    likes: int = 0\n\n\nclass PostRepository(BaseRepository[Post]):\n    def __init__(self):\n        super().__init__(\"posts\", Post)\n\n    async def get_user_stats(self, user_id: str) -&gt; dict:\n        pipeline = [\n            {\"$match\": {\"author_id\": user_id}},\n            {\"$group\": {\"_id\": None, \"total_posts\": {\"$sum\": 1}, \"total_likes\": {\"$sum\": \"$likes\"}}},\n        ]\n        result = await self.collection.aggregate(pipeline).to_list(1)\n        return result[0] if result else {\"total_posts\": 0, \"total_likes\": 0}\n</code></pre>"},{"location":"05_patterns/#pattern-3-bulk-operations","title":"Pattern 3: Bulk Operations","text":"<p>Multi-document mutation in one call \u2014 again wrapped at the repository boundary.</p> Python<pre><code>from datetime import datetime\n\nfrom bson import ObjectId\nfrom mongo_ops import BaseRepository, BaseDocument\n\n\nclass Task(BaseDocument):\n    status: str = \"pending\"\n\n\nclass TaskRepository(BaseRepository[Task]):\n    def __init__(self):\n        super().__init__(\"tasks\", Task)\n\n    async def bulk_update_status(self, ids: list[str], status: str) -&gt; int:\n        object_ids = [ObjectId(i) for i in ids]\n        result = await self.collection.update_many(\n            {\"_id\": {\"$in\": object_ids}},\n            {\"$set\": {\"status\": status, \"updated_at\": datetime.utcnow()}},\n        )\n        return result.modified_count\n</code></pre> <p>Bulk/aggregation methods bypass the caching and population layers \u2014 keep them deliberate and documented.</p>"},{"location":"05_patterns/#pattern-4-transactional-multi-step-write","title":"Pattern 4: Transactional Multi-Step Write","text":"<p>Cross-collection atomicity with <code>execute_transaction</code> \u2014 see use case 12 for the full code.</p> Python<pre><code>results = await TransactionManager.execute_transaction([op1, op2, op3])\n# op1/op2/op3 each receive the shared session; one failure rolls back all.\n</code></pre>"},{"location":"05_patterns/#related","title":"Related","text":"<ul> <li>02 \u2013 Custom repository \u00b7 03 \u2013 Transactions \u00b7 Best Practices</li> </ul>"},{"location":"06_error_handling/","title":"Error Handling","text":"<p>What can raise, what it means, and how to map it in a FastAPI app.</p>"},{"location":"06_error_handling/#library-raised-exceptions","title":"\ud83d\udccb Library-Raised Exceptions","text":"Exception Source Meaning / fix <code>RuntimeError(\"Database not connected. Call connect() first.\")</code> <code>get_database()</code> / <code>get_client()</code> and any repository constructed first <code>MongoConnectionManager.connect()</code> hasn't run \u2014 wire the lifespan. <code>RuntimeError(\"No cache backend registered. Call set_cache_backend() first.\")</code> <code>ModelRegistry.initialize_cache()</code> Call <code>set_cache_backend(backend)</code> before <code>initialize_cache()</code>. <code>KeyError(\"Model for collection '...' not registered\")</code> <code>ModelRegistry.get_model()</code> Collection was never <code>register</code>ed (or typo). <code>ValueError(\"Cannot patch FK fields via patch(): ...\")</code> <code>PopulatingRepository.patch()</code> <code>patch</code> must not touch populated ref fields \u2014 use <code>update()</code> with a model. <code>ValueError(\"...contains embedded dict(s) \u2014 run repair script\")</code> <code>_populate</code> on read A FK field holds an embedded document instead of an <code>ObjectId</code> \u2014 migrate the data. <code>ValueError(\"...contains ObjectId \u2014 was populate skipped?\")</code> <code>_depopulate</code> on write A populate-ruled field is still an <code>ObjectId</code> at depopulate time \u2014 the read must have populated it first. <code>CircularReferenceError(collection, doc_id, path)</code> <code>PopulationEngine.populate</code> A <code>(Class, id)</code> pair was revisited \u2014 raise <code>max_depth</code> or fix the graph. <code>ImportError(\"redis package required ... mongo-ops[redis]\")</code> <code>CacheConfig</code> / <code>RedisCacheBackend</code> Missing <code>redis</code> extra. <code>ValueError(\"redis_client required when backend='redis'\")</code> <code>CacheConfig</code> <code>backend=\"redis\"</code> without a client. Pymongo <code>DuplicateKeyError</code> any insert/update Unique index violation (e.g., duplicate email). <code>bson.errors.InvalidId</code> <code>ObjectId(...)</code> on a bad string Wrapped by <code>PyObjectId</code> model validation on API inputs. <p><code>KeyError</code> for <code>ModelRegistry.get_model</code> and the <code>RuntimeError</code>/<code>ValueError</code> guards are by design \u2014 they fail loudly at startup or first call instead of misbehaving silently.</p>"},{"location":"06_error_handling/#fastapi-mapping-example","title":"\ud83d\ude80 FastAPI Mapping Example","text":"Python<pre><code>from fastapi import FastAPI, HTTPException, Request\nfrom fastapi.responses import JSONResponse\nfrom bson.errors import InvalidId\nfrom pymongo.errors import DuplicateKeyError\nfrom mongo_ops.cache import CircularReferenceError\n\n\napp = FastAPI()\n\n\n@app.exception_handler(DuplicateKeyError)\nasync def duplicate_key_handler(_: Request, __: DuplicateKeyError) -&gt; JSONResponse:\n    return JSONResponse(status_code=409, content={\"detail\": \"Resource already exists\"})\n\n\n@app.exception_handler(InvalidId)\nasync def invalid_id_handler(_: Request, __: InvalidId) -&gt; JSONResponse:\n    return JSONResponse(status_code=400, content={\"detail\": \"Invalid ID format\"})\n\n\n@app.exception_handler(CircularReferenceError)\nasync def circular_ref_handler(_: Request, exc: CircularReferenceError) -&gt; JSONResponse:\n    return JSONResponse(\n        status_code=409,\n        content={\"detail\": f\"Circular reference detected: {exc.path}\"},\n    )\n\n\n# Or handle inline for route-specific responses:\n@app.post(\"/users/\")\nasync def create_user(user: User, repo=Depends(get_user_repository)):\n    try:\n        return await repo.create(user)\n    except DuplicateKeyError:\n        raise HTTPException(status_code=409, detail=\"User already exists\")\n    except Exception as exc:\n        raise HTTPException(status_code=500, detail=str(exc))\n\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: str, repo=Depends(get_user_repository)):\n    try:\n        user = await repo.get_by_id(user_id)\n    except InvalidId:\n        raise HTTPException(status_code=400, detail=\"Invalid user ID\")\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n</code></pre> <p>Prefer exception handlers for the library-level exceptions (409/400 above) and per-endpoint <code>try/except</code> for domain decisions (404).</p>"},{"location":"06_error_handling/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>The <code>ValueError</code> populate guards are your friends: they surface data-shape drift (embedded docs, skipped population) at the exact call site.</li> <li>In dev, log the <code>CircularReferenceError.path</code> \u2014 it prints the visited <code>Class:id</code> chain.</li> <li>Never swallow <code>RuntimeError</code>s at startup; let the app fail to load so the misconfiguration is obvious.</li> </ul>"},{"location":"06_error_handling/#related","title":"Related","text":"<ul> <li>03 \u2013 Transactions \u00b7 08 \u2013 Population \u00b7 11 \u2013 Cache lifecycle</li> </ul>"},{"location":"07_testing_example/","title":"Testing Example","text":"<p>A zero-MongoDB unit-test quickstart. The full guide is use case 14.</p>"},{"location":"07_testing_example/#mock-based-quickstart","title":"\ud83d\ude80 Mock-Based Quickstart","text":"<p>Patch the connection manager and stub the collection \u2014 no network, no docker.</p> Python<pre><code>import pytest\nfrom unittest.mock import AsyncMock, patch\n\nfrom bson import ObjectId\nfrom mongo_ops import BaseDocument, BaseRepository\nfrom mongo_ops.repository import MongoConnectionManager\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n\n\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n\n@pytest.fixture\ndef repo():\n    mock_collection = AsyncMock()\n    with patch.object(MongoConnectionManager, \"get_database\") as mock_db:\n        mock_db.return_value.__getitem__.return_value = mock_collection\n        r = UserRepository()\n        r.collection = mock_collection\n        return r\n\n\n@pytest.mark.asyncio\nasync def test_create_user(repo):\n    mock_collection = repo.collection\n    oid = ObjectId()\n    mock_collection.insert_one.return_value.inserted_id = oid\n\n    user = await repo.create(User(username=\"test\", email=\"test@example.com\"))\n\n    assert user.id == oid\n    assert user.username == \"test\"\n\n\n@pytest.mark.asyncio\nasync def test_get_by_id(repo):\n    oid = ObjectId()\n    repo.collection.find_one.return_value = {\n        \"_id\": oid,\n        \"username\": \"test\",\n        \"email\": \"test@example.com\",\n        \"created_at\": \"2024-01-01T00:00:00\",\n        \"updated_at\": \"2024-01-01T00:00:00\",\n    }\n\n    fetched = await repo.get_by_id(str(oid))\n\n    assert fetched is not None\n    assert fetched.username == \"test\"\n</code></pre>"},{"location":"07_testing_example/#notes","title":"\ud83d\udca1 Notes","text":"<ul> <li><code>from mongo_ops.repository import MongoConnectionManager</code> \u2014 patch where it is used (<code>mongo_ops.repository.MongoConnectionManager</code>), matching the library's own tests.</li> <li>pytest-asyncio runs as <code>auto</code> mode per <code>pyproject.toml</code>, so <code>@pytest.mark.asyncio</code> works without extra config.</li> <li>For population, cache, registry, and transaction mockups \u2014 see the full testing guide.</li> </ul>"},{"location":"07_testing_example/#related","title":"Related","text":"<ul> <li>14 \u2013 Testing guide \u00b7 Best Practices</li> </ul>"},{"location":"03_use_cases/01_basic_crud/","title":"Use Case 1: Basic FastAPI CRUD API","text":"<p>Scenario: A simple user management API with CRUD endpoints, index registration, and a correct connection lifecycle.</p>"},{"location":"03_use_cases/01_basic_crud/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>MongoConnectionManager.lifespan</code> Connect on startup, disconnect on shutdown. <code>BaseRepository[User]</code> Generic CRUD \u2014 no endpoint-level Mongo code. <code>ModelRegistry.register</code> Declares the <code>email</code> index; <code>initialize_all</code> creates it at startup."},{"location":"03_use_cases/01_basic_crud/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>import os\nfrom contextlib import asynccontextmanager\n\nfrom fastapi import Depends, FastAPI, HTTPException\nfrom pydantic import Field\n\nfrom mongo_ops import BaseDocument, BaseRepository, ModelRegistry, MongoConnectionManager\n\n# ---------------------------\n# Model\n# ---------------------------\nclass User(BaseDocument):\n    username: str = Field(..., min_length=3, max_length=50)\n    email: str = Field(...)\n    is_active: bool = True\n\n\n# ---------------------------\n# Repository\n# ---------------------------\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n\n# ---------------------------\n# Registration + index\n# ---------------------------\nModelRegistry.register(\"users\", User, indexes=[(\"email\", 1)])\n\n\n# ---------------------------\n# Lifecycle\n# ---------------------------\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=os.getenv(\"MONGO_URI\", \"mongodb://localhost:27017\"),\n        db_name=\"mydb\",\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n# ---------------------------\n# Dependency \u2014 created per request, after connect()\n# ---------------------------\ndef get_user_repository() -&gt; UserRepository:\n    return UserRepository()\n\n\n# ---------------------------\n# Routes\n# ---------------------------\n@app.post(\"/users/\", response_model=User)\nasync def create_user(user: User, repo: UserRepository = Depends(get_user_repository)):\n    return await repo.create(user)\n\n\n@app.get(\"/users/{user_id}\", response_model=User)\nasync def get_user(user_id: str, repo: UserRepository = Depends(get_user_repository)):\n    user = await repo.get_by_id(user_id)\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n\n\n@app.get(\"/users/\", response_model=list[User])\nasync def list_users(\n    skip: int = 0,\n    limit: int = 10,\n    repo: UserRepository = Depends(get_user_repository),\n):\n    return await repo.get_many(skip=skip, limit=limit)\n\n\n@app.put(\"/users/{user_id}\", response_model=User)\nasync def update_user(\n    user_id: str,\n    email: str,\n    repo: UserRepository = Depends(get_user_repository),\n):\n    user = await repo.update(user_id, {\"email\": email})\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user\n\n\n@app.delete(\"/users/{user_id}\")\nasync def delete_user(user_id: str, repo: UserRepository = Depends(get_user_repository)):\n    deleted = await repo.delete(user_id)\n    if not deleted:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return {\"message\": \"User deleted successfully\"}\n</code></pre>"},{"location":"03_use_cases/01_basic_crud/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li><code>UserRepository()</code> is created inside the dependency, i.e., only after the lifespan has connected. Instantiating a repository at module import time raises <code>RuntimeError</code> because the database isn't connected yet.</li> <li><code>BaseRepository.update(id, {...})</code> takes a dict; only <code>PopulatingRepository.update</code> takes a model.</li> <li>Use <code>patch()</code> for REST PATCH semantics \u2014 it accepts a partial dict like <code>update</code>, but <code>PopulatingRepository</code> rejects FK fields.</li> </ul>"},{"location":"03_use_cases/01_basic_crud/#related","title":"Related","text":"<ul> <li>02 \u2013 Custom repository \u00b7 04 \u2013 Pagination \u00b7 Overview</li> </ul>"},{"location":"03_use_cases/02_custom_repo/","title":"Use Case 2: Custom Repository with Business Logic","text":"<p>Scenario: An e-commerce product catalog needs search, filtering, and stock updates without Mongo leaking into routes.</p>"},{"location":"03_use_cases/02_custom_repo/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description Repository methods Encapsulate queries (<code>$regex</code>, filters, <code>$inc</code>) behind domain methods. <code>get_many</code> Filtering + default pagination via the base repository. Direct <code>collection</code> access For operations with no base-repo helper (regex search, atomic <code>$inc</code>)."},{"location":"03_use_cases/02_custom_repo/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from fastapi import FastAPI, HTTPException, Query\nfrom mongo_ops import BaseDocument, BaseRepository\n\n# ---------------------------\n# Model\n# ---------------------------\nclass Product(BaseDocument):\n    name: str\n    description: str = \"\"\n    price: float = 0.0\n    category: str = \"\"\n    in_stock: bool = True\n    quantity: int = 0\n    tags: list[str] = []\n\n\n# ---------------------------\n# Repository\n# ---------------------------\nclass ProductRepository(BaseRepository[Product]):\n    def __init__(self):\n        super().__init__(\"products\", Product)\n\n    async def search_by_name(self, query: str) -&gt; list[Product]:\n        \"\"\"Case-insensitive name search.\"\"\"\n        docs = await self.collection.find(\n            {\"name\": {\"$regex\": query, \"$options\": \"i\"}}\n        ).to_list(length=100)\n        return [self.model(**doc) for doc in docs]\n\n    async def get_by_category(self, category: str, in_stock_only: bool = True) -&gt; list[Product]:\n        filter_query = {\"category\": category}\n        if in_stock_only:\n            filter_query[\"in_stock\"] = True\n        return await self.get_many(filter=filter_query)\n\n    async def get_low_stock(self, threshold: int = 10) -&gt; list[Product]:\n        return await self.get_many(filter={\"quantity\": {\"$lt\": threshold}, \"in_stock\": True})\n\n    async def update_stock(self, product_id: str, quantity_delta: int) -&gt; Product | None:\n        \"\"\"Atomically increment/decrement stock.\"\"\"\n        from bson import ObjectId\n        from datetime import datetime\n\n        result = await self.collection.find_one_and_update(\n            {\"_id\": ObjectId(product_id)},\n            {\"$inc\": {\"quantity\": quantity_delta}, \"$set\": {\"updated_at\": datetime.utcnow()}},\n            return_document=True,\n        )\n        return self.model(**result) if result else None\n\n\napp = FastAPI()\nproduct_repo = ProductRepository()\n\n\n@app.get(\"/products/search\", response_model=list[Product])\nasync def search_products(q: str = Query(..., min_length=1)):\n    return await product_repo.search_by_name(q)\n\n\n@app.get(\"/products/category/{category}\", response_model=list[Product])\nasync def products_by_category(category: str, in_stock: bool = True):\n    return await product_repo.get_by_category(category, in_stock)\n\n\n@app.get(\"/products/low-stock\", response_model=list[Product])\nasync def low_stock_products(threshold: int = 10):\n    return await product_repo.get_low_stock(threshold)\n\n\n@app.patch(\"/products/{product_id}/stock\")\nasync def update_product_stock(product_id: str, quantity_delta: int):\n    product = await product_repo.update_stock(product_id, quantity_delta)\n    if not product:\n        raise HTTPException(status_code=404, detail=\"Product not found\")\n    return product\n</code></pre> <p>Note: this snippet omits the FastAPI <code>lifespan</code> connection wiring for brevity \u2014 copy it from use case 01 so <code>ProductRepository()</code> is created only after <code>MongoConnectionManager.connect()</code>.</p>"},{"location":"03_use_cases/02_custom_repo/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Methods that hit <code>self.collection</code> directly (regex search, <code>$inc</code>) bypass the caching and population layers. If a feature composes them \u2014 extend <code>CachedBaseRepository</code> or <code>PopulatingRepository</code> instead and add the domain methods there.</li> <li>Prefer <code>get_many(filter=...)</code> over raw <code>find</code> when you want pagination/sort defaults for free.</li> <li>Reuse <code>self.model(**doc)</code> to convert raw dicts to model instances consistently.</li> </ul>"},{"location":"03_use_cases/02_custom_repo/#related","title":"Related","text":"<ul> <li>01 \u2013 Basic CRUD \u00b7 04 \u2013 Pagination \u00b7 05 \u2013 Soft deletes</li> </ul>"},{"location":"03_use_cases/03_transactions/","title":"Use Case 3: Transaction Support for Multi-Document Operations","text":"<p>Scenario: Order processing must update inventory and create an order atomically. Any failure rolls both back.</p>"},{"location":"03_use_cases/03_transactions/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>TransactionManager.start_session</code> Async context manager yielding a session with an active transaction. <code>session=</code> kwarg Pass to every <code>insert_one</code> / <code>update_one</code> / <code>find_one</code> inside the block."},{"location":"03_use_cases/03_transactions/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\nfrom datetime import datetime\n\nfrom bson import ObjectId\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, BaseRepository, MongoConnectionManager, TransactionManager\n\n\nclass Order(BaseDocument):\n    user_id: str\n    items: list[dict]  # [{\"product_id\": \"...\", \"quantity\": 2}]\n    total_amount: float = 0.0\n    status: str = \"pending\"\n\n\nclass Inventory(BaseDocument):\n    product_id: ObjectId = None\n    quantity: int = 0\n\n\nclass OrderRepository(BaseRepository[Order]):\n    def __init__(self):\n        super().__init__(\"orders\", Order)\n\n\nclass InventoryRepository(BaseRepository[Inventory]):\n    def __init__(self):\n        super().__init__(\"inventory\", Inventory)\n\n\nasync def create_order_with_inventory_update(\n    order: Order,\n    order_repo: OrderRepository,\n    inv_repo: InventoryRepository,\n) -&gt; Order:\n    async def insert_order(session):\n        doc = order.model_dump(exclude={\"id\"}, exclude_none=True)\n        doc[\"created_at\"] = doc[\"updated_at\"] = datetime.utcnow()\n        result = await order_repo.collection.insert_one(doc, session=session)\n        return await order_repo.collection.find_one({\"_id\": result.inserted_id}, session=session)\n\n    async def update_inventory(session):\n        for item in order.items:\n            await inv_repo.collection.update_one(\n                {\"product_id\": ObjectId(item[\"product_id\"])},\n                {\n                    \"$inc\": {\"quantity\": -item[\"quantity\"]},\n                    \"$set\": {\"updated_at\": datetime.utcnow()},\n                },\n                session=session,\n            )\n        return None\n\n    async with TransactionManager.start_session() as session:\n        created = await insert_order(session)\n        await update_inventory(session)\n        return Order(**created)\n\n\n# ---------------------------\n# FastAPI wiring\n# ---------------------------\napp = FastAPI()\n\norder_repo = OrderRepository()\ninv_repo = InventoryRepository()\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"shop\"\n    ):\n        yield\n\n\napp.lifespan = lifespan\n\n\n@app.post(\"/orders/\", response_model=Order)\nasync def create_order(order: Order):\n    try:\n        return await create_order_with_inventory_update(order, order_repo, inv_repo)\n    except Exception as exc:\n        raise HTTPException(status_code=400, detail=str(exc))\n</code></pre>"},{"location":"03_use_cases/03_transactions/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Repositories are created inside the lifespan (or a dependency) so the database is connected \u2014 see the note in use case 01.</li> <li>Every operation inside the transaction context must receive <code>session=&lt;session&gt;</code> \u2014 a missing session silently runs outside the transaction.</li> <li>MongoDB transactions require a replica set (or the local standalone test server that emulates one).</li> <li>For a list-of-operations style, see <code>TransactionManager.execute_transaction</code> in use case 12.</li> </ul>"},{"location":"03_use_cases/03_transactions/#related","title":"Related","text":"<ul> <li>06 \u2013 Multi-model \u00b7 12 \u2013 Transaction helper \u00b7 Error Handling</li> </ul>"},{"location":"03_use_cases/04_pagination/","title":"Use Case 4: Pagination &amp; Filtering","text":"<p>Scenario: A blog post API lists posts with page metadata, filtering, and sorting.</p>"},{"location":"03_use_cases/04_pagination/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>BaseRepository.get_many</code> <code>filter</code>, <code>skip</code>, <code>limit</code>, <code>sort</code> in one call. <code>BaseRepository.count</code> Total matching documents for page metadata. <code>PaginatedResponse</code> Reusable generic response wrapper."},{"location":"03_use_cases/04_pagination/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from typing import Generic, TypeVar\n\nfrom fastapi import FastAPI, Query\nfrom pydantic import BaseModel\nfrom mongo_ops import BaseDocument, BaseRepository\n\nT = TypeVar(\"T\")\n\n\nclass PaginatedResponse(BaseModel, Generic[T]):\n    items: list[T]\n    total: int\n    page: int\n    page_size: int\n    total_pages: int\n    has_next: bool\n    has_prev: bool\n\n\nclass BlogPost(BaseDocument):\n    title: str = \"\"\n    content: str = \"\"\n    author_id: str = \"\"\n    published: bool = False\n    tags: list[str] = []\n    views: int = 0\n\n\nclass BlogPostRepository(BaseRepository[BlogPost]):\n    def __init__(self):\n        super().__init__(\"blog_posts\", BlogPost)\n\n    async def paginate(\n        self,\n        page: int = 1,\n        page_size: int = 10,\n        filter_dict: dict | None = None,\n        sort_by: str = \"created_at\",\n        sort_order: int = -1,\n    ) -&gt; PaginatedResponse[BlogPost]:\n        filter_dict = filter_dict or {}\n        skip = (page - 1) * page_size\n        total = await self.count(filter_dict)\n        items = await self.get_many(\n            filter=filter_dict,\n            skip=skip,\n            limit=page_size,\n            sort=[(sort_by, sort_order)],\n        )\n        total_pages = (total + page_size - 1) // page_size\n        return PaginatedResponse(\n            items=items,\n            total=total,\n            page=page,\n            page_size=page_size,\n            total_pages=total_pages,\n            has_next=page &lt; total_pages,\n            has_prev=page &gt; 1,\n        )\n\n    async def get_by_author(self, author_id: str, published_only: bool = True) -&gt; list[BlogPost]:\n        filter_dict = {\"author_id\": author_id}\n        if published_only:\n            filter_dict[\"published\"] = True\n        return await self.get_many(filter=filter_dict, sort=[(\"created_at\", -1)])\n\n    async def search_by_tags(self, tags: list[str]) -&gt; list[BlogPost]:\n        return await self.get_many(filter={\"tags\": {\"$in\": tags}, \"published\": True})\n\n\napp = FastAPI()\nblog_repo = BlogPostRepository()\n\n\n@app.get(\"/posts/\", response_model=PaginatedResponse[BlogPost])\nasync def list_posts(\n    page: int = 1,\n    page_size: int = 10,\n    published: bool | None = None,\n    author_id: str | None = None,\n):\n    filter_dict = {}\n    if published is not None:\n        filter_dict[\"published\"] = published\n    if author_id:\n        filter_dict[\"author_id\"] = author_id\n    return await blog_repo.paginate(page, page_size, filter_dict)\n\n\n@app.get(\"/posts/author/{author_id}\", response_model=list[BlogPost])\nasync def posts_by_author(author_id: str, published: bool = True):\n    return await blog_repo.get_by_author(author_id, published)\n\n\n@app.get(\"/posts/tags\", response_model=list[BlogPost])\nasync def posts_by_tags(tags: list[str] = Query(...)):\n    return await blog_repo.search_by_tags(tags)\n</code></pre> <p>Note: add the <code>lifespan</code> wiring from use case 01 so <code>blog_repo</code> is created after connection.</p>"},{"location":"03_use_cases/04_pagination/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li><code>get_many</code> calls <code>cursor.to_list(limit)</code>; pass <code>limit=0</code> to skip the limit entirely, otherwise a large explicit limit is safer than unbounded reads.</li> <li>Always <code>count</code> first for stable metadata \u2014 it uses the same filter as the page query.</li> <li>Combine with <code>sort=[(field, -1|1)]</code> for deterministic ordering; create matching indexes to avoid full collection scans (see use case 13).</li> </ul>"},{"location":"03_use_cases/04_pagination/#related","title":"Related","text":"<ul> <li>02 \u2013 Custom repository \u00b7 13 \u2013 Indexes \u00b7 05 \u2013 Soft deletes</li> </ul>"},{"location":"03_use_cases/05_soft_deletes/","title":"Use Case 5: Soft Deletes Pattern","text":"<p>Scenario: Deleting a task should be recoverable. Instead of removing the document, set a tombstone flag and filter it from normal queries.</p>"},{"location":"03_use_cases/05_soft_deletes/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>SoftDeleteDocument</code> Base model carrying <code>is_deleted</code>, <code>deleted_at</code>, <code>deleted_by</code>. <code>SoftDeleteRepository[T]</code> Repository-level soft delete / restore / filtering using <code>update</code> + <code>get_many</code>. <code>permanent_delete</code> Escapes to the real <code>delete</code>."},{"location":"03_use_cases/05_soft_deletes/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from datetime import datetime\n\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, BaseRepository\n\n\nclass SoftDeleteDocument(BaseDocument):\n    is_deleted: bool = False\n    deleted_at: datetime | None = None\n    deleted_by: str | None = None\n\n\nclass Task(SoftDeleteDocument):\n    title: str = \"\"\n    description: str = \"\"\n    assignee_id: str = \"\"\n    status: str = \"pending\"\n    priority: str = \"medium\"\n\n\nclass SoftDeleteRepository(BaseRepository[T]):\n    async def soft_delete(self, id: str, deleted_by: str | None = None):\n        return await self.update(\n            id,\n            {\"is_deleted\": True, \"deleted_at\": datetime.utcnow(), \"deleted_by\": deleted_by},\n        )\n\n    async def restore(self, id: str):\n        return await self.update(\n            id, {\"is_deleted\": False, \"deleted_at\": None, \"deleted_by\": None}\n        )\n\n    async def get_active(self, skip: int = 0, limit: int = 100):\n        return await self.get_many(filter={\"is_deleted\": False}, skip=skip, limit=limit)\n\n    async def get_deleted(self, skip: int = 0, limit: int = 100):\n        return await self.get_many(filter={\"is_deleted\": True}, skip=skip, limit=limit)\n\n    async def permanent_delete(self, id: str) -&gt; bool:\n        return await self.delete(id)\n\n\nclass TaskRepository(SoftDeleteRepository[Task]):\n    def __init__(self):\n        super().__init__(\"tasks\", Task)\n\n\napp = FastAPI()\ntask_repo = TaskRepository()\n\n\n@app.delete(\"/tasks/{task_id}\")\nasync def soft_delete_task(task_id: str, user_id: str):\n    task = await task_repo.soft_delete(task_id, deleted_by=user_id)\n    if not task:\n        raise HTTPException(status_code=404, detail=\"Task not found\")\n    return {\"message\": \"Task deleted\", \"task\": task}\n\n\n@app.post(\"/tasks/{task_id}/restore\")\nasync def restore_task(task_id: str):\n    task = await task_repo.restore(task_id)\n    if not task:\n        raise HTTPException(status_code=404, detail=\"Task not found\")\n    return {\"message\": \"Task restored\", \"task\": task}\n\n\n@app.get(\"/tasks/\", response_model=list[Task])\nasync def list_active_tasks(skip: int = 0, limit: int = 10):\n    return await task_repo.get_active(skip, limit)\n\n\n@app.get(\"/tasks/deleted\", response_model=list[Task])\nasync def list_deleted_tasks(skip: int = 0, limit: int = 10):\n    return await task_repo.get_deleted(skip, limit)\n</code></pre> <p>Note: add the <code>lifespan</code> wiring from use case 01 so <code>task_repo</code> is created after connection.</p>"},{"location":"03_use_cases/05_soft_deletes/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li><code>BaseRepository[T]</code> is generic \u2014 subclasses must parameterize it (see <code>SoftDeleteRepository[T]</code> above). <code>from mongo_ops import BaseRepository; BaseRepository[T]</code> works out of the box.</li> <li>Keep a compound index on <code>{\"is_deleted\": 1, \"status\": 1}</code> for active-list queries (see use case 13).</li> <li>Soft-deleted documents should be excluded at the repository boundary, never re-filtered ad hoc in endpoints.</li> </ul>"},{"location":"03_use_cases/05_soft_deletes/#related","title":"Related","text":"<ul> <li>01 \u2013 Basic CRUD \u00b7 13 \u2013 Indexes \u00b7 04 \u2013 Pagination</li> </ul>"},{"location":"03_use_cases/06_multi_model/","title":"Use Case 6: Multi-Model Service with Registration","text":"<p>Scenario: A social app manages <code>users</code>, <code>posts</code>, and <code>comments</code>. Each has its own model, repository, and indexes \u2014 registered centrally and initialized at startup.</p>"},{"location":"03_use_cases/06_multi_model/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>ModelRegistry.register</code> One call per collection \u2014 model + indexes together. <code>ModelRegistry.initialize_all</code> Creates every registered index at startup (idempotent). Repositories One repository class per collection, all sharing the same connection."},{"location":"03_use_cases/06_multi_model/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom fastapi import FastAPI\nfrom mongo_ops import BaseDocument, BaseRepository, ModelRegistry, MongoConnectionManager\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n    role: str = \"user\"\n\n\nclass Post(BaseDocument):\n    title: str = \"\"\n    content: str = \"\"\n    author_id: str = \"\"\n    likes: int = 0\n\n\nclass Comment(BaseDocument):\n    post_id: str = \"\"\n    user_id: str = \"\"\n    content: str = \"\"\n\n\nclass UserRepository(BaseRepository[User]):\n    def __init__(self):\n        super().__init__(\"users\", User)\n\n\nclass PostRepository(BaseRepository[Post]):\n    def __init__(self):\n        super().__init__(\"posts\", Post)\n\n\nclass CommentRepository(BaseRepository[Comment]):\n    def __init__(self):\n        super().__init__(\"comments\", Comment)\n\n\n# ---------------------------\n# Central registration + indexes\n# ---------------------------\nModelRegistry.register(\"users\", User, indexes=[(\"email\", 1), (\"username\", 1)])\nModelRegistry.register(\"posts\", Post, indexes=[(\"author_id\", 1), (\"created_at\", -1)])\nModelRegistry.register(\"comments\", Comment, indexes=[(\"post_id\", 1), (\"user_id\", 1)])\n\n\n# ---------------------------\n# Lifecycle\n# ---------------------------\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"social_app\"\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n# Created after connect() \u2014 inside the lifespan body is fine, or use a dependency.\nuser_repo = UserRepository()\npost_repo = PostRepository()\ncomment_repo = CommentRepository()\n\n\n@app.post(\"/users/\", response_model=User)\nasync def create_user(user: User):\n    return await user_repo.create(user)\n\n\n@app.post(\"/posts/\", response_model=Post)\nasync def create_post(post: Post):\n    return await post_repo.create(post)\n\n\n@app.post(\"/comments/\", response_model=Comment)\nasync def create_comment(comment: Comment):\n    return await comment_repo.create(comment)\n</code></pre>"},{"location":"03_use_cases/06_multi_model/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Place <code>user_repo = ...</code> inside the lifespan/after connect. Module-level instantiation before <code>connect()</code> raises <code>RuntimeError(\"Database not connected...\")</code>.</li> <li>Model relationships here are plain <code>ObjectId</code> strings stored on the child docs. To resolve them on read, see use case 08 \u2013 Population.</li> <li>Registering indexes on <code>created_at</code>/<code>author_id</code>/<code>post_id</code> keeps the common queries indexed (see use case 13).</li> </ul>"},{"location":"03_use_cases/06_multi_model/#related","title":"Related","text":"<ul> <li>01 \u2013 Basic CRUD \u00b7 08 \u2013 Population \u00b7 13 \u2013 Indexes</li> </ul>"},{"location":"03_use_cases/07_caching/","title":"Use Case 7: Caching for High-Performance Reads","text":"<p>Scenario: A read-heavy API (product catalog) reduces DB load by caching documents by <code>_id</code> \u2014 in-memory locally, or shared via Redis.</p>"},{"location":"03_use_cases/07_caching/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>InMemoryCacheBackend</code> TTL + LRU cache with a background cleanup task. <code>RedisCacheBackend</code> Distributed cache on <code>redis.asyncio</code> with pub/sub invalidation. <code>CachedBaseRepository[T]</code> Extends <code>BaseRepository</code> \u2014 cache-first <code>get_by_id</code>, cache on <code>create</code>, invalidate on <code>update</code>/<code>delete</code>, <code>warm_cache(ids)</code>, <code>invalidate_cache(id)</code>. Backend lifecycle The same backend instance must be both passed to the repository AND registered via <code>ModelRegistry.set_cache_backend</code> so <code>initialize_cache()</code> starts its task."},{"location":"03_use_cases/07_caching/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, ModelRegistry, MongoConnectionManager\nfrom mongo_ops.cache import CacheConfig, CachedBaseRepository, InMemoryCacheBackend\n\n\nclass Product(BaseDocument):\n    name: str = \"\"\n    price: float = 0.0\n\n\n# One shared backend \u2014 used by both the repository and the registry lifecycle.\ncache = InMemoryCacheBackend(max_entries=10_000, default_ttl=300)\nModelRegistry.set_cache_backend(cache)\n\n\nclass ProductRepo(CachedBaseRepository[Product]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"products\",\n            model=Product,\n            cache_backend=cache,\n            config=CacheConfig(enabled=True, backend=\"memory\"),\n        )\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"shop\"\n    ):\n        await ModelRegistry.initialize_all()\n        await ModelRegistry.initialize_cache()  # starts the TTL cleanup task\n        yield\n        await ModelRegistry.shutdown_cache()    # cancels it on exit\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n@app.post(\"/products/\", response_model=Product)\nasync def create_product(product: Product):\n    return await ProductRepo().create(product)  # created after connect()\n\n\n@app.get(\"/products/{product_id}\", response_model=Product)\nasync def get_product(product_id: str):\n    product = await ProductRepo().get_by_id(product_id)\n    if not product:\n        raise HTTPException(status_code=404, detail=\"Product not found\")\n    return product\n\n\n@app.put(\"/products/{product_id}\", response_model=Product)\nasync def update_product(product_id: str, name: str | None = None, price: float | None = None):\n    data = {}\n    if name is not None:\n        data[\"name\"] = name\n    if price is not None:\n        data[\"price\"] = price\n    return await ProductRepo().update(product_id, data)\n\n\n# Outside request handlers:\n#   await ProductRepo().warm_cache([object_id_1, object_id_2])   # pre-load n ids -&gt; int\n#   await ProductRepo().invalidate_cache(object_id_3)            # manual eviction\n</code></pre>"},{"location":"03_use_cases/07_caching/#redis-backend","title":"\ud83d\udd04 Redis Backend","text":"<p>Swap the backend \u2014 the repository code stays identical:</p> Python<pre><code>from mongo_ops.cache import RedisCacheBackend\nfrom redis.asyncio import Redis\n\nredis_client = Redis(host=\"localhost\", port=6379)\nredis_backend = RedisCacheBackend(redis_client, key_prefix=\"prod:\")\n\nModelRegistry.set_cache_backend(redis_backend)  # for the lifecycle in lifespan()\n\nclass ProductRepo(CachedBaseRepository[Product]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"products\",\n            model=Product,\n            cache_backend=redis_backend,\n            config=CacheConfig(enabled=True, backend=\"redis\"),\n        )\n</code></pre>"},{"location":"03_use_cases/07_caching/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Cache keys are <code>\"{key_prefix}{id}\"</code> (default prefix <code>\"products:\"</code>). <code>clear_pattern(\"products:*\")</code> wipes a whole collection's entries.</li> <li>Values are JSON-encoded (<code>json.dumps(obj, default=str)</code>) \u2014 nested models inside a cached document are stored as dicts, not objects.</li> <li>Enable/disable per repository with <code>CacheConfig(enabled=False)</code>; a disabled repo bypasses the cache entirely.</li> <li>Distinguish the two <code>initialize*</code> calls: <code>initialize_cache()</code> starts the backend task; <code>initialize_all()</code> creates indexes. Both belong in the lifespan, after <code>connect()</code>.</li> </ul>"},{"location":"03_use_cases/07_caching/#related","title":"Related","text":"<ul> <li>11 \u2013 Cache lifecycle \u00b7 10 \u2013 Cache + population \u00b7 Components: cache</li> </ul>"},{"location":"03_use_cases/08_population/","title":"Use Case 8: Document Population","text":"<p>Scenario: An API returns a <code>User</code> with its related <code>Profile</code> embedded in one JSON payload \u2014 no second round-trip from the client, no joins.</p>"},{"location":"03_use_cases/08_population/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>PopulateRule</code> Declares which field to resolve. <code>field_name</code> holds the <code>ObjectId</code> (or <code>list[ObjectId]</code>) and is the same field the resolved document replaces in place. <code>collection_name</code> says where the referenced documents live. <code>PopulationEngine</code> Holds repositories by collection name and resolves rules recursively, detecting cycles (<code>CircularReferenceError</code>). <code>PopulatingRepository[T]</code> <code>get_by_id</code>/<code>get_many</code> populate on read; <code>create</code>/<code>update</code> depopulate on write; <code>patch</code> rejects FK fields. <p>\u26a0\ufe0f <code>PopulateRule</code> does not have a separate \"ref field\" vs \"target field\" \u2014 the ref field is the populated field. <code>filter</code>/<code>projection</code> on <code>PopulateRule</code> are declared but not yet applied by the engine.</p>"},{"location":"03_use_cases/08_population/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, MongoConnectionManager, ModelRegistry, PopulatingRepository\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\n\n\n# 1. Models \u2014 `profile` holds an ObjectId in the DB and becomes a Profile on read.\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n    bio: str = \"\"\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n    profile: Profile | None = None  # ObjectId in MongoDB, Profile in memory\n\n\n# 2. Engine + rule \u2014 repositories are registered later (after connect()).\nengine = PopulationEngine({})\nprofile_rule = PopulateRule(\n    field_name=\"profile\",\n    collection_name=\"profiles\",\n)\n\n\n# 3. The repository the app uses.\nclass UserRepository(PopulatingRepository[User]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"users\",\n            model=User,\n            population_engine=engine,\n            populate_rules=[profile_rule],\n        )\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"mydb\"\n    ):\n        # Tells the engine which repository resolves \"profiles\" refs.\n        engine.register_repo(\"profiles\", PopulatingRepository[Profile](\"profiles\", Profile))\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp = FastAPI(lifespan=lifespan)\n\n\n# 4. Writing \u2014 pass the model; the repository depopulates to an ObjectId.\n@app.post(\"/users/\", response_model=User)\nasync def create_user():\n    user = User(\n        username=\"alice\",\n        email=\"alice@example.com\",\n        profile=Profile(avatar_url=\"alice.png\", bio=\"hi\"),\n    )\n    return await UserRepository().create(user)\n    # ^ stored as {\"profile\": &lt;ObjectId&gt;}, returned with profile populated\n\n\n# 5. Reading \u2014 get_by_id resolves the reference on the way back.\n@app.get(\"/users/{user_id}\", response_model=User)\nasync def get_user(user_id: str):\n    user = await UserRepository().get_by_id(user_id)\n    if not user:\n        raise HTTPException(status_code=404, detail=\"User not found\")\n    return user  # user.profile is a Profile instance\n</code></pre>"},{"location":"03_use_cases/08_population/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li><code>Patch</code>ing an FK field raises <code>ValueError</code> \u2014 switch FK changes to <code>update(user_id, model)</code> instead. See use case 05 for the reasoning with soft deletes.</li> <li>Missing references resolve to <code>None</code>, not an error.</li> <li>A field holding an embedded dict (instead of an <code>ObjectId</code>) raises a <code>ValueError</code> (\"run repair script\") \u2014 migrate embedded docs to a separate collection first.</li> <li>If <code>create</code>/<code>update</code> receives a field that is already an <code>ObjectId</code> under a populate rule, <code>_depopulate</code> raises <code>ValueError(\"...was populate skipped?\")</code> \u2014 populate-then-depopulate pairs must be balanced.</li> </ul>"},{"location":"03_use_cases/08_population/#related","title":"Related","text":"<ul> <li>09 \u2013 Advanced population \u00b7 10 \u2013 Cache + population \u00b7 14 \u2013 Testing guide</li> </ul>"},{"location":"03_use_cases/09_advanced_population/","title":"Use Case 9: Nested Document Population &amp; Circular-Ref Handling","text":"<p>Scenario: An <code>Author</code> has <code>books</code> (a list of references), each <code>Book</code> references a <code>publisher</code>, and an <code>Author</code> may reference a <code>mentor</code> \u2014 which is another <code>Author</code> (a potential cycle).</p>"},{"location":"03_use_cases/09_advanced_population/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>nested_rules</code> Populates deeper levels: resolve <code>books</code> on <code>Author</code>, then <code>publisher</code> inside each <code>Book</code>. <code>max_depth</code> Per-rule recursion bound \u2014 the safety net for cyclic graphs. <code>global_max_depth</code> <code>PopulationEngine(repos, global_max_depth=10)</code> global cap. <code>CircularReferenceError</code> Raised when a <code>(Class, id)</code> pair is revisited; carries the visited path."},{"location":"03_use_cases/09_advanced_population/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom bson import ObjectId\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, ModelRegistry, MongoConnectionManager, PopulatingRepository\nfrom mongo_ops.cache import CircularReferenceError\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\n\n\n# 1. Models \u2014 each ref field holds ObjectId(s) in the DB and becomes model(s) in memory.\nclass Publisher(BaseDocument):\n    name: str = \"\"\n    country: str = \"\"\n\n\nclass Book(BaseDocument):\n    title: str = \"\"\n    publisher: Publisher | None = None  # ObjectId in DB, Publisher in memory\n\n\nclass Author(BaseDocument):\n    name: str = \"\"\n    books: list[Book] | None = None      # list[ObjectId] in DB, list[Book] in memory\n    mentor: \"Author\" | None = None        # self-reference \u2014 potential cycle\n\n\n# 2. Engine + nested rules.\nengine = PopulationEngine({})\n\npublisher_rule = PopulateRule(\n    field_name=\"publisher\",\n    collection_name=\"publishers\",\n)\n\nbook_rule = PopulateRule(\n    field_name=\"books\",\n    collection_name=\"books\",\n    nested_rules=[publisher_rule],  # fetch each book, then its publisher\n    max_depth=3,\n)\n\nmentor_rule = PopulateRule(\n    field_name=\"mentor\",\n    collection_name=\"authors\",\n    max_depth=2,  # stops mentor chains early \u2014 also avoids unbounded cycles\n)\n\n\nclass AuthorRepository(PopulatingRepository[Author]):\n    def __init__(self):\n        super().__init__(\n            collection_name=\"authors\",\n            model=Author,\n            population_engine=engine,\n            populate_rules=[book_rule, mentor_rule],\n        )\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"library\"\n    ):\n        engine.register_repo(\"publishers\", PopulatingRepository[Publisher](\"publishers\", Publisher))\n        engine.register_repo(\"books\", PopulatingRepository[Book](\"books\", Book))\n        engine.register_repo(\"authors\", AuthorRepository())\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp = FastAPI()\n\n\n@app.get(\"/authors/{author_id}\")\nasync def get_author(author_id: str):\n    try:\n        author = await AuthorRepository().get_by_id(author_id)\n    except CircularReferenceError as exc:\n        raise HTTPException(status_code=409, detail=f\"Circular reference: {exc}\")\n    if not author:\n        raise HTTPException(status_code=404, detail=\"Author not found\")\n    return author\n</code></pre>"},{"location":"03_use_cases/09_advanced_population/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li><code>CircularReferenceError</code> is a <code>ValueError</code> subtype exposing <code>.collection</code>, <code>.doc_id</code>, and the visited <code>.path</code> \u2014 use it in error responses and logging.</li> <li>Keep <code>max_depth</code> conservative (2\u20133) for most graphs; combine with the global <code>global_max_depth=10</code> default.</li> <li>List refs depopulate back to <code>list[ObjectId]</code> on <code>create</code>/<code>update</code>, mirroring the scalar case.</li> </ul>"},{"location":"03_use_cases/09_advanced_population/#related","title":"Related","text":"<ul> <li>08 \u2013 Population \u00b7 10 \u2013 Cache + population \u00b7 Error Handling</li> </ul>"},{"location":"03_use_cases/10_cache_and_population/","title":"Use Case 10: Caching + Population (Read-Through, Populated on Read)","text":"<p>Scenario: A service needs fast reads of a <code>User</code> and its related <code>Profile</code>. We want the cache-hit path to skip the DB entirely while still returning a populated document.</p>"},{"location":"03_use_cases/10_cache_and_population/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>CachedBaseRepository</code> Provides the cache layer (<code>cache-first get_by_id</code>, invalidation on <code>update</code>/<code>delete</code>). <code>PopulationEngine</code> Provides the reference resolution. Composed subclass A small <code>CachedBaseRepository</code> subclass adds two <code>_populate</code> helpers so cache hits return populated models. <p>\u26a0\ufe0f Known limitation: there is no built-in <code>CachedPopulatingRepository</code> in the library. This use case documents the composition. We cache the raw (depopulated) document \u2014 references stay <code>ObjectId</code>s until read time, so <code>Profile</code> changes are reflected on the next fetch (within TTL) and <code>update</code>/<code>delete</code> invalidation remains correct.</p>"},{"location":"03_use_cases/10_cache_and_population/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\nfrom typing import Any\n\nfrom bson import ObjectId\nfrom fastapi import FastAPI\nfrom mongo_ops import BaseDocument, ModelRegistry, MongoConnectionManager\nfrom mongo_ops.cache import CacheConfig, CachedBaseRepository, InMemoryCacheBackend, decode_value\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\n\n\n# 1. Models \u2014 `profile` holds an ObjectId in DB, a Profile in memory.\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n    bio: str = \"\"\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n    profile: Profile | None = None\n\n\n# 2. Engine + rule.\nengine = PopulationEngine({})\nprofile_rule = PopulateRule(field_name=\"profile\", collection_name=\"profiles\")\n\n\n# 3. Composed repository.\nclass CachedUserRepository(CachedBaseRepository[User]):\n    def __init__(\n        self,\n        cache_backend: InMemoryCacheBackend,\n        population_engine: PopulationEngine,\n        populate_rules: list[PopulateRule],\n        config: CacheConfig | None = None,\n    ):\n        super().__init__(\"users\", User, cache_backend, config)\n        self.population_engine = population_engine\n        self._populate_rules = populate_rules\n\n    async def _populate(self, data: dict[str, Any]) -&gt; dict[str, Any]:\n        \"\"\"Dict-level resolution (mirrors PopulatingRepository._populate).\"\"\"\n        for rule in self._populate_rules:\n            ref = data.get(rule.field_name)\n            if ref is None:\n                continue\n            if isinstance(ref, str):  # JSON round-trip turns ObjectId into hex str\n                ref = ObjectId(ref)\n            if isinstance(ref, list):\n                resolved = []\n                for item in ref:\n                    item = ObjectId(item) if isinstance(item, str) else item\n                    repo = self.population_engine._repos.get(rule.collection_name)\n                    doc = await repo.get_by_id(item) if repo else None\n                    resolved.append(doc)\n                data[rule.field_name] = resolved\n            elif isinstance(ref, ObjectId):\n                repo = self.population_engine._repos.get(rule.collection_name)\n                data[rule.field_name] = await repo.get_by_id(ref) if repo else None\n        return data\n\n    async def get_by_id(self, id):\n        if not self._cache_config.enabled:\n            return await super().get_by_id(id)  # no cache -&gt; raw, unpopulated\n\n        cached = await self._cache.get(self._cache_key(id))\n        if cached is not None:\n            # Cache hit: decode the RAW doc, then populate before returning.\n            data = await self._populate(decode_value(cached))\n            return self.model(**data)\n\n        # Cache miss: single DB read; the base class caches the raw (depopulated) doc.\n        result = await super().get_by_id(id)\n        if result is None:\n            return None\n        return await self.model(**await self._populate(result.model_dump(by_alias=True)))\n\n\n# 4. Wire-up \u2014 one backend for both the repo and the registry lifecycle.\ncache = InMemoryCacheBackend(max_entries=20_000, default_ttl=600)\nModelRegistry.set_cache_backend(cache)\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"app_db\"\n    ):\n        # Register the repositories the engine resolves refs against:\n        # engine.register_repo(\"profiles\", ProfileRepo())\n        engine.register_repo(\"users\", CachedUserRepository(cache, engine, [profile_rule]))\n        await ModelRegistry.initialize_all()\n        await ModelRegistry.initialize_cache()\n        yield\n        await ModelRegistry.shutdown_cache()\n\n\napp = FastAPI(lifespan=lifespan)\n</code></pre> <p>Note: replace the placeholder <code>engine.register_repo(\"profiles\", ...)</code> line with a repository for <code>Profile</code>. A matching <code>CachedBaseRepository[Profile](\"profiles\", Profile, cache)</code> keeps profile reads cached too \u2014 e.g. <code>engine.register_repo(\"profiles\", CachedBaseRepository[Profile](\"profiles\", Profile, cache))</code>.</p>"},{"location":"03_use_cases/10_cache_and_population/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Cache the raw doc, populate at read time. Ref fields stay <code>ObjectId</code>s in the cache; JSON round-trips them to hex strings, so <code>_populate</code> must normalize <code>str \u2192 ObjectId</code> (shown above).</li> <li><code>update</code>/<code>delete</code> from the base class still invalidate the right key because we never repopulate in the cache.</li> <li>Set a sensible <code>default_ttl</code> \u2014 cached <code>User</code> entries resolve <code>Profile</code> on each read, so profile edits show up within the TTL (or call <code>invalidate_cache(user_id)</code> explicitly).</li> <li>If you want one repo class used app-wide, keep the populate helpers in a mixin shared with regular <code>PopulatingRepository</code>.</li> </ul>"},{"location":"03_use_cases/10_cache_and_population/#related","title":"Related","text":"<ul> <li>07 \u2013 Caching \u00b7 08 \u2013 Population \u00b7 11 \u2013 Cache lifecycle</li> </ul>"},{"location":"03_use_cases/11_cache_lifecycle/","title":"Use Case 11: Proper Cache Lifecycle in FastAPI","text":"<p>Scenario: A microservice uses an in-memory (or Redis) cache backend and must start the cleanup task on app start, then shut it down cleanly on termination.</p>"},{"location":"03_use_cases/11_cache_lifecycle/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>ModelRegistry.set_cache_backend(backend)</code> Registers the single shared backend. <code>ModelRegistry.initialize_cache()</code> Starts the backend (spawns the in-memory TTL cleanup task). Raises <code>RuntimeError</code> if no backend was registered. <code>ModelRegistry.shutdown_cache()</code> Cancels the cleanup task, closes pub/sub, clears the backend. If a repo uses a backend directly Same instance must be registered so <code>initialize_cache</code> starts its task."},{"location":"03_use_cases/11_cache_lifecycle/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom fastapi import FastAPI\nfrom mongo_ops import ModelRegistry, MongoConnectionManager\nfrom mongo_ops.cache import InMemoryCacheBackend\n\ncache = InMemoryCacheBackend(max_entries=10_000, default_ttl=300)\nModelRegistry.set_cache_backend(cache)  # before any cache-backed repo is used\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"mydb\"\n    ):\n        await ModelRegistry.initialize_all()    # create indexes (idempotent)\n        await ModelRegistry.initialize_cache()  # start the TTL cleanup task\n        yield\n        await ModelRegistry.shutdown_cache()    # cancel task + close cleanly\n\n\napp = FastAPI(lifespan=lifespan)\n</code></pre>"},{"location":"03_use_cases/11_cache_lifecycle/#what-actually-happens","title":"\ud83d\udd01 What Actually Happens","text":"<ul> <li><code>InMemoryCacheBackend.initialize()</code> spawns an <code>asyncio.Task</code> that evicts expired entries every <code>cleanup_interval</code> seconds. Without a shutdown, the event loop flags the dangling task on exit \u2014 <code>shutdown_cache()</code> cancels it and awaits it.</li> <li><code>shutdown_cache()</code> also NULs the registry cache backend and closes the Redis pub/sub handle (if Redis).</li> <li>If <code>initialize_cache()</code> is called before <code>set_cache_backend()</code>, it raises:</li> </ul> Text Only<pre><code>RuntimeError: No cache backend registered. Call set_cache_backend() first.\n</code></pre>"},{"location":"03_use_cases/11_cache_lifecycle/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Per-repository toggling is independent of the lifecycle: <code>CacheConfig(enabled=False)</code> bypasses the cache for that repo even after <code>initialize_cache()</code>.</li> <li>The cleanup task uses <code>cleanup_interval</code> seconds for scans; entries also expire on access via the TTL heap (<code>default_ttl=0</code> expires immediately).</li> <li>Register the backend before constructing any <code>CachedBaseRepository</code> that references it \u2014 otherwise a repo may hold an uninitialized backend (no cleanup task, no Redis pub/sub).</li> </ul>"},{"location":"03_use_cases/11_cache_lifecycle/#related","title":"Related","text":"<ul> <li>07 \u2013 Caching \u00b7 Components: ModelRegistry \u00b7 10 \u2013 Cache + population</li> </ul>"},{"location":"03_use_cases/12_transaction_helper/","title":"Use Case 12: Using <code>TransactionManager.execute_transaction</code>","text":"<p>Scenario: Perform several writes across different collections atomically \u2014 e.g., create an <code>Order</code> and decrement <code>Inventory</code>. The low-level <code>start_session</code> context works, but <code>execute_transaction</code> collects results from a list of async operations.</p>"},{"location":"03_use_cases/12_transaction_helper/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>TransactionManager.execute_transaction</code> Runs a list of async callables (each receives a session) inside one transaction; returns the result of each callable, in order. Automatic rollback Any raised exception aborts the transaction and propagates to the caller. <code>start_session</code> The underlying async context manager <code>async with TransactionManager.start_session() as session:</code>."},{"location":"03_use_cases/12_transaction_helper/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\nfrom datetime import datetime\n\nfrom bson import ObjectId\nfrom fastapi import FastAPI, HTTPException\nfrom mongo_ops import BaseDocument, ModelRegistry, MongoConnectionManager\nfrom mongo_ops.repository import BaseRepository\nfrom mongo_ops.transactions import TransactionManager\n\n\n# 1. Models\nclass Order(BaseDocument):\n    user_id: str = \"\"\n    items: list[dict] = []  # [{\"product_id\": ObjectId, \"qty\": int}]\n    total: float = 0.0\n\n\nclass Inventory(BaseDocument):\n    product_id: ObjectId = None\n    quantity: int = 0\n\n\n# 2. Repositories (constructed inside the lifespan \u2014 after connect()).\nclass OrderRepo(BaseRepository[Order]):\n    def __init__(self):\n        super().__init__(\"orders\", Order)\n\n\nclass InventoryRepo(BaseRepository[Inventory]):\n    def __init__(self):\n        super().__init__(\"inventory\", Inventory)\n\n\n# 3. The atomic operation.\nasync def create_order_with_inventory(order: Order, order_repo: OrderRepo, inv_repo: InventoryRepo):\n    async def insert_order(session):\n        doc = order.model_dump(exclude={\"id\"}, exclude_none=True)\n        doc[\"created_at\"] = doc[\"updated_at\"] = datetime.utcnow()\n        result = await order_repo.collection.insert_one(doc, session=session)\n        return await order_repo.collection.find_one({\"_id\": result.inserted_id}, session=session)\n\n    async def update_inventory(session):\n        for item in order.items:\n            await inv_repo.collection.update_one(\n                {\"product_id\": ObjectId(item[\"product_id\"])},\n                {\"$inc\": {\"quantity\": -item[\"qty\"]}},\n                session=session,\n            )\n        return \"inventory-updated\"\n\n    results = await TransactionManager.execute_transaction(\n        [insert_order, update_inventory]\n    )\n    return results[0]  # created order document; results[1] == \"inventory-updated\"\n\n\n# 4. FastAPI wiring.\napp = FastAPI()\n\n\n@asynccontextmanager\nasync def lifespan(_app: FastAPI):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\", db_name=\"shop\"\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n\n\napp.lifespan = lifespan\n\n\n@app.post(\"/orders/\", response_model=Order)\nasync def create_order(order: Order):\n    created = await create_order_with_inventory(order, OrderRepo(), InventoryRepo())\n    if created is None:\n        raise HTTPException(status_code=400, detail=\"Transaction failed\")\n    return created\n</code></pre>"},{"location":"03_use_cases/12_transaction_helper/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Return values: each callable can return whatever you need; results are collected in the same order.</li> <li>Errors: raise inside any callable \u2192 the whole transaction aborts (session rolls back) and the exception propagates.</li> <li>Reads inside a transaction: pass <code>session=session</code> to <code>find_one</code>/<code>find</code> too.</li> <li>Testing (no Mongo): <code>monkeypatch</code> a fake client on <code>mongo_ops.transactions.MongoConnectionManager.get_client</code> and stub <code>start_session</code> \u2014 see <code>tests/test_transactions.py</code>.</li> <li>Repo models still carry <code>created_at</code>/<code>updated_at</code>; for raw collection inserts inside the transaction you set them manually (as shown).</li> </ul>"},{"location":"03_use_cases/12_transaction_helper/#related","title":"Related","text":"<ul> <li>03 \u2013 Transactions \u00b7 14 \u2013 Testing guide \u00b7 Error Handling</li> </ul>"},{"location":"03_use_cases/13_index_creation/","title":"Use Case 13: Declaring Indexes (Single-Field, Composite, Unique)","text":"<p>Scenario: Ensure each collection has the right indexes for fast queries and data integrity \u2014 declared in one place and created at startup.</p>"},{"location":"03_use_cases/13_index_creation/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>ModelRegistry.register(indexes=...)</code> Each spec is passed as-is to pymongo <code>create_index</code>. Supported forms: tuple <code>(\"field\", direction)</code>, compound list <code>[(\"a\", 1), (\"b\", -1)]</code>, or a dict with <code>keys</code> + <code>options</code>. <code>ModelRegistry.initialize_all</code> Creates every registered index during startup (idempotent \u2014 <code>create_index</code> skips existing indexes)."},{"location":"03_use_cases/13_index_creation/#example","title":"\ud83d\ude80 Example","text":"Python<pre><code>from contextlib import asynccontextmanager\n\nfrom pymongo import ASCENDING, DESCENDING\nfrom mongo_ops import BaseDocument, ModelRegistry, MongoConnectionManager\n\n\nclass User(BaseDocument):\n    username: str = \"\"\n    email: str = \"\"\n\n\nclass BlogPost(BaseDocument):\n    author_id: str = \"\"\n    created_at: str = \"\"\n    title: str = \"\"\n\n\nclass Passenger(BaseDocument):\n    email: str = \"\"\n    seat: str = \"\"\n\n\n# 1\ufe0f\u20e3 Single-field index \u2014 email lookups.\nModelRegistry.register(\n    collection_name=\"users\",\n    model=User,\n    indexes=[(\"email\", ASCENDING)],\n)\n\n# 2\ufe0f\u20e3 Composite index \u2014 queries filtering by author + creation date.\nModelRegistry.register(\n    collection_name=\"posts\",\n    model=BlogPost,\n    indexes=[[(\"author_id\", ASCENDING), (\"created_at\", DESCENDING)]],\n)\n\n# 3\ufe0f\u20e3 Unique index with a custom name \u2014 enforce unique emails.\nModelRegistry.register(\n    collection_name=\"passengers\",\n    model=Passenger,\n    indexes=[\n        {\n            \"keys\": [(\"email\", ASCENDING)],\n            \"options\": {\"unique\": True, \"name\": \"uq_passenger_email\"},\n        }\n    ],\n)\n\n\n# 4\ufe0f\u20e3 Everything is created on startup.\n@asynccontextmanager\nasync def lifespan(_app):\n    async with MongoConnectionManager.lifespan(\n        uri=\"mongodb://localhost:27017\",\n        db_name=\"mydb\",\n    ):\n        await ModelRegistry.initialize_all()\n        yield\n</code></pre>"},{"location":"03_use_cases/13_index_creation/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>Every spec passes through to <code>collection.create_index(spec)</code> \u2014 so MongoDB options like <code>unique</code>, <code>sparse</code>, and <code>expireAfterSeconds</code> (TTL) belong in the <code>options</code> dict.</li> <li>Idempotent by construction: <code>create_index</code> is a no-op when a same-shape index already exists.</li> <li>Verify with the Mongo shell:</li> </ul> JavaScript<pre><code>db.&lt;collection&gt;.getIndexes()\n</code></pre> <ul> <li>A unique index on an already-duplicated field will fail with <code>DuplicateKeyError</code> on startup \u2014 clean the data first.</li> </ul>"},{"location":"03_use_cases/13_index_creation/#related","title":"Related","text":"<ul> <li>01 \u2013 Basic CRUD \u00b7 06 \u2013 Multi-model \u00b7 Components: ModelRegistry</li> </ul>"},{"location":"03_use_cases/14_testing_guide/","title":"Use Case 14: Testing Guide \u2014 Mocking Motor, Cache, Registry &amp; Transactions","text":"<p>Scenario: Write unit tests that never touch a real MongoDB \u2014 mock the collection, the cache backend, and the client, exactly like the library's own test suite (<code>tests/</code>).</p>"},{"location":"03_use_cases/14_testing_guide/#whats-new","title":"\ud83d\udce6 What's New?","text":"Component Description <code>AsyncMock</code> collections Stub <code>find_one</code>, <code>insert_one</code>, <code>find_one_and_update</code>, cursor chains. Patching <code>MongoConnectionManager.get_database</code> Gives repositories a mock collection without a live connection. <code>monkeypatch</code> on <code>get_client</code> Fakes sessions for <code>TransactionManager</code> tests. Reference tests <code>tests/test_populating_repository.py</code>, <code>tests/test_cache.py</code>, <code>tests/test_registry.py</code>, <code>tests/test_transactions.py</code>."},{"location":"03_use_cases/14_testing_guide/#example-boilerplate","title":"\ud83d\ude80 Example Boilerplate","text":"Python<pre><code>import pytest\nfrom unittest.mock import AsyncMock, MagicMock, patch\n\nfrom bson import ObjectId\nfrom mongo_ops.cache import CacheConfig, InMemoryCacheBackend, CachedBaseRepository\nfrom mongo_ops.models import BaseDocument\nfrom mongo_ops.registry import ModelRegistry\nfrom mongo_ops.populate import PopulateRule, PopulationEngine\nfrom mongo_ops.repository import PopulatingRepository\n\n\n# ----------------------------------------------------------------------\n# 1. Models (same shape as the library tests)\n# ----------------------------------------------------------------------\nclass Profile(BaseDocument):\n    avatar_url: str = \"\"\n\n\nclass User(BaseDocument):\n    name: str = \"\"\n    profile: Profile | None = None  # ObjectId in DB, Profile in memory\n\n\n# ----------------------------------------------------------------------\n# 2. Fixtures\n# ----------------------------------------------------------------------\n@pytest.fixture\ndef mock_collection():\n    return AsyncMock()\n\n\n@pytest.fixture\ndef engine():\n    profile_repo = AsyncMock()\n    return PopulationEngine({\"profiles\": profile_repo})\n\n\n@pytest.fixture\ndef repo(mock_collection, engine):\n    with patch(\"mongo_ops.repository.MongoConnectionManager.get_database\") as mock_db:\n        mock_db.return_value.__getitem__.return_value = mock_collection\n        r = PopulatingRepository(\n            \"users\",\n            User,\n            population_engine=engine,\n            populate_rules=[PopulateRule(field_name=\"profile\", collection_name=\"profiles\")],\n        )\n        r.collection = mock_collection\n        return r\n\n\n# ----------------------------------------------------------------------\n# 3. Population \u2014 get_by_id resolves the reference\n# ----------------------------------------------------------------------\n@pytest.mark.asyncio\nasync def test_get_by_id_populates(repo, mock_collection, engine):\n    uid, pid = ObjectId(), ObjectId()\n    mock_collection.find_one.return_value = {\n        \"_id\": uid,\n        \"name\": \"Alice\",\n        \"profile\": pid,                                   # ObjectId stored in DB\n        \"created_at\": \"2024-01-01T00:00:00\",\n        \"updated_at\": \"2024-01-01T00:00:00\",\n    }\n    engine._repos[\"profiles\"].get_by_id.return_value = Profile(id=pid, avatar_url=\"pic.png\")\n\n    result = await repo.get_by_id(uid)\n\n    assert result is not None\n    assert result.name == \"Alice\"\n    assert isinstance(result.profile, Profile)\n    assert result.profile.avatar_url == \"pic.png\"\n\n\n# ----------------------------------------------------------------------\n# 4. Patch FK guard\n# ----------------------------------------------------------------------\n@pytest.mark.asyncio\nasync def test_patch_rejects_fk_field(repo):\n    with pytest.raises(ValueError, match=\"Cannot patch FK fields\"):\n        await repo.patch(ObjectId(), {\"profile\": ObjectId()})\n\n\n# ----------------------------------------------------------------------\n# 5. Registry \u2014 index specs pass through to create_index\n# ----------------------------------------------------------------------\n@pytest.mark.asyncio\nasync def test_initialize_all_creates_indexes():\n    ModelRegistry.register(\"users\", User, indexes=[(\"email\", 1)])\n\n    fake_collection = AsyncMock()\n    await ModelRegistry.initialize_all(db={\"users\": fake_collection})\n\n    fake_collection.create_index.assert_awaited_once_with((\"email\", 1))\n\n\n# ----------------------------------------------------------------------\n# 6. Cached repository \u2014 cache-first reads + invalidation\n# ----------------------------------------------------------------------\n@pytest.mark.asyncio\nasync def test_cached_get_by_id_populates_cache():\n    backend = InMemoryCacheBackend(\n        max_entries=100, default_ttl=300, cleanup_interval=9999\n    )\n    await backend.initialize()\n    try:\n        with patch(\"mongo_ops.repository.MongoConnectionManager.get_database\") as mock_db:\n            mock_collection = AsyncMock()\n            mock_db.return_value.__getitem__.return_value = mock_collection\n            repo = CachedBaseRepository(\n                \"users\", User, backend, CacheConfig(enabled=True)\n            )\n            repo.collection = mock_collection\n\n            oid = ObjectId()\n            mock_collection.find_one.return_value = {\n                \"_id\": oid,\n                \"name\": \"cached\",\n                \"created_at\": \"2024-01-01T00:00:00\",\n                \"updated_at\": \"2024-01-01T00:00:00\",\n            }\n\n            first = await repo.get_by_id(oid)\n            assert first is not None\n\n            mock_collection.find_one.return_value = None  # DB now \"empty\"\n            second = await repo.get_by_id(oid)            # served from cache\n\n            assert second is not None\n            assert second.name == \"cached\"\n            mock_collection.find_one.assert_awaited_once()  # only one DB read\n    finally:\n        await backend.shutdown()\n\n\n# ----------------------------------------------------------------------\n# 7. Transactions \u2014 fake the client's start_session\n# ----------------------------------------------------------------------\nfrom mongo_ops.transactions import TransactionManager\n\n\n@pytest.mark.asyncio\nasync def test_execute_transaction(monkeypatch):\n    session_ctx = AsyncMock()\n    session_ctx.__aenter__.return_value = AsyncMock()\n    session_ctx.__aexit__.return_value = None\n\n    client = MagicMock()\n    client.start_session = AsyncMock(return_value=session_ctx)\n\n    # NOTE: start_transaction must return a context manager, not a coroutine.\n    async_session = session_ctx.__aenter__.return_value\n    async_session.start_transaction = lambda **_: session_ctx\n\n    monkeypatch.setattr(\n        \"mongo_ops.transactions.MongoConnectionManager.get_client\",\n        lambda: client,\n    )\n\n    async def fake_op(session):\n        return \"ok\"\n\n    results = await TransactionManager.execute_transaction([fake_op])\n    assert results == [\"ok\"]\n</code></pre>"},{"location":"03_use_cases/14_testing_guide/#tips","title":"\ud83d\udca1 Tips","text":"<ul> <li>pytest-asyncio is already configured in <code>pyproject.toml</code> (<code>asyncio_mode = \"auto\"</code>), so <code>@pytest.mark.asyncio</code> tests work out of the box. Run with <code>pytest</code> (coverage reports are enabled there too).</li> <li>Never hit the network. Keep the patches in fixtures (or a <code>conftest.py</code>) and reuse them.</li> <li>Mock <code>cursor</code> chains with <code>MagicMock()</code> + <code>.to_list = AsyncMock(...)</code>, exactly like <code>tests/test_repository.py</code>.</li> <li>For an optional integration check (real Mongo), use <code>MongoConnectionManager.lifespan</code> against a local replica set and drop the test database in teardown \u2014 keep it separate from the unit suite.</li> <li>The pattern works symmetrically for Redis: mock the <code>RedisCacheBackend</code> methods (<code>get</code>, <code>set</code>, <code>delete</code>) \u2014 no Redis process required.</li> </ul>"},{"location":"03_use_cases/14_testing_guide/#related","title":"Related","text":"<ul> <li>08 \u2013 Population \u00b7 07 \u2013 Caching \u00b7 12 \u2013 Transaction helper</li> </ul>"}]}
\ No newline at end of file
diff --git a/mongo-ops/sitemap.xml.gz b/mongo-ops/sitemap.xml.gz
index 65eaafde7498f518d1a764503c663c7881ed13a2..2984a5c0604425d6c75a5222b5179590ee6a2ad7 100644
GIT binary patch
delta 13
Ucmb=gXP58h;9#&^K9Riw02xFBumAu6

delta 13
Ucmb=gXP58h;An7JJdwQu032%sHvj+t