Update docs

Author: nielsweistra

docs/10-GUIDES/12-TESTING_GUIDE.md

@@ -1,16 +1,16 @@
-# Testing Guide: Unit, Integration, and E2E Tests
+# Testing Guide: Unit, Integration, and E2E Tests
 
 Complete testing strategy for SDK-based resource providers.
 
 ---
 
 ## Testing Architecture
 
-```
-Your Provider
-├── Unit Tests (models, handlers, validation)
-├── Integration Tests (SDK + storage layer)
-└── E2E Tests (full provider + API Gateway)
+```mermaid
+graph TD
+    A[Your Provider] --> B[Unit Tests<br/>models, handlers, validation]
+    A --> C[Integration Tests<br/>SDK + storage layer]
+    A --> D[E2E Tests<br/>full provider + API Gateway]
 ```
 
 ---
@@ -137,7 +137,7 @@ def test_invalid_transition_raises_error(handler):
     """Invalid transitions raise error"""
     id, data = handler.create_resource("resource-001", {})
 
-    # Can't go Accepted → Failed directly
+    # Can't go Accepted -> Failed directly
     with pytest.raises(ValueError, match="Invalid transition"):
         handler.transition_state(id, ProvisioningState.FAILED)
 ```
@@ -161,7 +161,7 @@ async def provider():
 
 @pytest.mark.asyncio
 async def test_create_resource_flow(provider):
-    """Full create flow: Accepted → Provisioning → Succeeded"""
+    """Full create flow: Accepted -> Provisioning -> Succeeded"""
 
     request = ResourceRequest(
         resource_type="myresources",
@@ -463,13 +463,13 @@ async def test_request():
 
 ## Best Practices
 
-✅ **Test at all levels** - Unit, integration, and E2E  
-✅ **Use fixtures** - Reusable test setup  
-✅ **Test error paths** - Not just happy path  
-✅ **Test validation** - Invalid inputs must fail gracefully  
-✅ **Mock external** - Don't hit real APIs in tests  
-✅ **Async tests** - Use @pytest.mark.asyncio  
-✅ **Measure coverage** - Track test coverage over time  
+ **Test at all levels** - Unit, integration, and E2E  
+ **Use fixtures** - Reusable test setup  
+ **Test error paths** - Not just happy path  
+ **Test validation** - Invalid inputs must fail gracefully  
+ **Mock external** - Don't hit real APIs in tests  
+ **Async tests** - Use @pytest.mark.asyncio  
+ **Measure coverage** - Track test coverage over time  
 
 ---
 

docs/11-WORKER_ROLES.md

@@ -1,22 +1,22 @@
-# Worker Roles: Asynchronous Job Processing
+# Worker Roles: Asynchronous Job Processing
 
-**Status**: ✅ Production-Ready  
+**Status**:  Production-Ready  
 **Implementation**: Complete worker system with Kubernetes integration  
 **Coverage**: Job queues, worker lifecycle, async offloading, scaling
 
 Enable horizontal scaling and asynchronous processing of provider operations. Offload long-running tasks to backend worker pods while API server returns immediately with job tracking IDs.
 
 ---
 
-## 🎯 Overview
+## Overview
 
 The **Worker Role system** transforms synchronous provider operations into asynchronous, scalable jobs:
 
 ### Before (Synchronous, Blocking)
 ```
 Client Request
     ↓
-API Server ─→ Provider Logic (blocking for 5+ seconds) ─→ Response
+API Server --> Provider Logic (blocking for 5+ seconds) --> Response
                 ↓
             Client waits for completion
 ```
@@ -25,7 +25,7 @@ API Server ─→ Provider Logic (blocking for 5+ seconds) ─→ Response
 ```
 Client Request
     ↓
-API Server ─→ Submit to Queue (instant) ─→ Response with job_id
+API Server --> Submit to Queue (instant) --> Response with job_id
                     ↓
             Worker Pod (processes asynchronously)
                     ↓
@@ -34,55 +34,28 @@ API Server ─→ Submit to Queue (instant) ─→ Response with job_id
 
 ### Key Benefits
 
-✅ **Horizontal Scaling** — Scale worker pods independently from API  
-✅ **Async Processing** — Client gets immediate response with job_id  
-✅ **Load Distribution** — Multiple workers share operation workload  
-✅ **Resilience** — Failed jobs captured in dead-letter queue  
-✅ **Kubernetes Native** — Full RBAC, health checks, Prometheus metrics  
-✅ **Production Ready** — Used in ITL ControlPlane core infrastructure
+ **Horizontal Scaling** — Scale worker pods independently from API  
+ **Async Processing** — Client gets immediate response with job_id  
+ **Load Distribution** — Multiple workers share operation workload  
+ **Resilience** — Failed jobs captured in dead-letter queue  
+ **Kubernetes Native** — Full RBAC, health checks, Prometheus metrics  
+ **Production Ready** — Used in ITL ControlPlane core infrastructure
 
 ---
 
-## 🏗️ Architecture
+## Architecture
 
 ### System Flow Diagram
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    API Server (Main)                         │
-│  - Receives HTTP requests                                    │
-│  - Validates input                                           │
-│  - Submits jobs to queue                                     │
-│  - Returns job_id to client for tracking                     │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       │ Submit Job
-                       ▼
-┌─────────────────────────────────────────────────────────────┐
-│              RabbitMQ Job Queue (Message Broker)             │
-│  - provider.jobs: Queue for pending jobs                     │
-│  - provider.results: Queue for job results                   │
-│  - provider.jobs.dlq: Dead-letter queue for failures         │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       │ Consume Job
-                       ▼
-┌──────────────────────────────────────────────────────────────┐
-│            Worker Pod #1    Worker Pod #2    Worker Pod #3   │
-│  ┌────────────────────┐ ┌────────────────────┐              │
-│  │ ProviderWorker     │ │ ProviderWorker     │              │
-│  │ - Process jobs     │ │ - Process jobs     │              │
-│  │ - Execute ops      │ │ - Execute ops      │              │
-│  │ - Store results    │ │ - Store results    │              │
-│  └────────────────────┘ └────────────────────┘              │
-└──────────────────────┬──────────────────────────────────────┘
-                       │
-                       │ Publish Result
-                       ▼
-┌─────────────────────────────────────────────────────────────┐
-│              Result Store (Redis/Cache)                      │
-│  (Clients poll this for job completion)                      │
-└─────────────────────────────────────────────────────────────┘
+```mermaid
+flowchart TD
+    A["API Server (Main)<br>- Receives HTTP requests<br>- Validates input<br>- Submits jobs to queue<br>- Returns job_id to client"]
+    B["RabbitMQ Job Queue (Message Broker)<br>- provider.jobs: pending jobs<br>- provider.results: job results<br>- provider.jobs.dlq: dead-letter queue"]
+    C["Worker Pods (x3) — ProviderWorker<br>- Process jobs  - Execute ops  - Store results"]
+    D["Result Store (Redis/Cache)<br>Clients poll for job completion"]
+    A -->|Submit Job| B
+    B -->|Consume Job| C
+    C -->|Publish Result| D
 ```
 
 ### Components
@@ -97,7 +70,7 @@ API Server ─→ Submit to Queue (instant) ─→ Response with job_id
 
 ---
 
-## ⚡ Quick Start (5 Minutes)
+## Quick Start (5 Minutes)
 
 ### Step 1: Enable Workers in Helm
 
@@ -161,7 +134,7 @@ kubectl port-forward svc/rabbitmq 15672:15672
 
 ---
 
-## 📚 Components & API Reference
+## Components & API Reference
 
 ### JobQueue
 
@@ -200,11 +173,11 @@ result = await job_queue.get_result(
 ```python
 stats = await job_queue.get_queue_stats()
 # {
-#   "connected": true,
-#   "queues": {
-#     "provider.jobs": {"message_count": 5, "consumer_count": 3},
-#     "provider.jobs.dlq": {"message_count": 0}
-#   }
+# "connected": true,
+# "queues": {
+# "provider.jobs": {"message_count": 5, "consumer_count": 3},
+# "provider.jobs.dlq": {"message_count": 0}
+# }
 # }
 ```
 
@@ -339,10 +312,10 @@ registry.register_worker(worker)
 # Get status
 status = registry.get_registry_status()
 # {
-#   "total_workers": 3,
-#   "active_workers": 3,
-#   "total_jobs_processed": 1542,
-#   "total_jobs_failed": 3
+# "total_workers": 3,
+# "active_workers": 3,
+# "total_jobs_processed": 1542,
+# "total_jobs_failed": 3
 # }
 
 # Start/stop all
@@ -352,7 +325,7 @@ await registry.stop_all_workers()
 
 ---
 
-## ⚙️ Configuration
+## Configuration
 
 ### Development (1 Worker)
 
@@ -439,7 +412,7 @@ JOB_TIMEOUT=300                             # Default job timeout (seconds)
 
 ---
 
-## 🚀 Deployment (Kubernetes/Helm)
+## Deployment (Kubernetes/Helm)
 
 ### Files Created
 
@@ -487,7 +460,7 @@ kubectl exec <worker-pod> -- curl http://localhost:8001/health
 
 ---
 
-## 📊 Health & Monitoring
+## Health & Monitoring
 
 ### Health Check Endpoints
 
@@ -557,7 +530,7 @@ kubectl port-forward svc/rabbitmq 15672:15672
 
 ---
 
-## 📈 Scaling Strategies
+## Scaling Strategies
 
 ### Horizontal Scaling (Number of Workers)
 
@@ -607,7 +580,7 @@ await queue.submit_job(..., priority=1)
 
 ---
 
-## ⚠️ Error Handling & Resilience
+## Error Handling & Resilience
 
 ### Dead-Letter Queue (DLQ)
 
@@ -674,7 +647,7 @@ class CustomWorker(ProviderWorker):
 
 ---
 
-## 🔒 Security
+## Security
 
 ### RBAC (ClusterRole)
 
@@ -714,7 +687,7 @@ workers:
 
 ---
 
-## 🆘 Troubleshooting
+## Troubleshooting
 
 ### Workers Not Consuming Jobs
 
@@ -796,7 +769,7 @@ helm upgrade --set workers.resources.limits.memory=1Gi
 
 ---
 
-## 💡 Real-World Examples
+## Real-World Examples
 
 ### Example 1: API with Offloading
 
@@ -888,7 +861,7 @@ except asyncio.TimeoutError:
 
 ---
 
-## 👍 Best Practices
+## Best Practices
 
 ### Priority Management
 
@@ -935,7 +908,7 @@ finally:
 
 ---
 
-## 🔗 Related Documentation
+## Related Documentation
 
 - [08-API_ENDPOINTS.md](08-API_ENDPOINTS.md) - FastAPI integration
 - [06-HANDLER_MIXINS.md](06-HANDLER_MIXINS.md) - Handler patterns
@@ -944,7 +917,7 @@ finally:
 
 ---
 
-## 📖 Quick Reference
+## Quick Reference
 
 ### Install
 ```bash
@@ -993,5 +966,5 @@ return {"job_id": response.job_id, "status": "pending"}
 
 **Document Version**: 1.0 (Consolidated from 4 docs)  
 **Last Updated**: February 14, 2026  
-**Status**: ✅ Production-Ready
+**Status**:  Production-Ready