go-duck-cli 1.0.9 → 1.1.12

package/templates/docs/pages/keycloak.hbs

@@ -0,0 +1,43 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Keycloak: Identity & Access Management</h1>
+<p class="text-lg text-gray-600 mb-8">Secure your microservices with industrial-strength OIDC/JWT authentication powered by Keycloak.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Centralized Identity</h2>
+    <p class="mb-4 text-gray-700">Identity management is a first-class citizen in GO-DUCK. Every microservice is pre-configured to validate <strong>JSON Web Tokens (JWT)</strong> issued by Keycloak. This ensures that only authenticated users and services can access your data.</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">JWT Validation & Security</h2>
+    <p class="mb-4">The generated <code>middleware.JWTMiddleware()</code> handles several critical security tasks:</p>
+    <ul class="list-disc pl-8 mb-4 text-gray-700 space-y-2">
+        <li><strong>Digital Signature Verification</strong>: Validates the token against Keycloak's public keys (JWKS).</li>
+        <li><strong>Expiration Enforcement</strong>: Ensures tokens are still within their valid time window.</li>
+        <li><strong>Role Extraction</strong>: Seamlessly extracts user roles and injects them into the Gin context for downstream authorization.</li>
+        <li><strong>Context Safety</strong>: Populates <code>KeycloakID</code> in the context to prevent header spoofing in audit and metering modules.</li>
+    </ul>
+    
+    <div class="bg-yellow-50 border-l-4 border-yellow-500 p-4 mb-6 rounded-r">
+        <p class="text-yellow-900"><strong>Authorization:</strong> Beyond simple authentication, the middleware extracts the <code>realm_access.roles</code> from the token. You can use these roles to implement fine-grained RBAC inside your controllers.</p>
+    </div>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Configuration</h2>
+    <p class="mb-4 text-gray-700">Connecting your GO-DUCK app to Keycloak is a simple matter of YAML configuration:</p>
+    <pre><code class="language-yaml">go-duck:
+  security:
+    oidc:
+      issuer: "http://keycloak:8080/realms/{{appName}}"
+      client-id: "backend-service"
+      # Public key URL for token verification
+      jwks-url: "http://keycloak:8080/realms/{{appName}}/protocol/openid-connect/certs"</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">External Resources</h2>
+    <ul class="space-y-2">
+        <li><a href="https://www.keycloak.org/documentation" target="_blank" class="text-indigo-600 hover:underline">Keycloak Official Documentation &rarr;</a></li>
+        <li><a href="https://openid.net/connect/" target="_blank" class="text-indigo-600 hover:underline">OpenID Connect (OIDC) Standard &rarr;</a></li>
+        <li><a href="https://jwt.io/" target="_blank" class="text-indigo-600 hover:underline">JWT.io: Debugging & Decoding Tokens &rarr;</a></li>
+    </ul>
+</section>

package/templates/docs/pages/legend.hbs

@@ -0,0 +1,116 @@
+<div class="prose prose-slate max-w-none">
+
+    <!-- Page Header -->
+    <div class="mb-16">
+        <div class="flex items-center gap-4 mb-6">
+            <span class="w-14 h-14 rounded-2xl bg-gradient-to-tr from-orange-400 to-rose-500 text-white flex items-center justify-center shadow-lg text-2xl">🦆</span>
+            <div>
+                <p class="text-xs font-bold uppercase tracking-widest text-orange-500 mb-1">Brand Lore</p>
+                <h1 class="text-5xl font-black text-slate-900 tracking-tighter m-0 leading-none">The Legend of the Century</h1>
+            </div>
+        </div>
+        <p class="text-xl text-slate-500 leading-relaxed max-w-3xl">The epic origin story of GO-DUCK — how a Gopher, a Duck, a Bottle of Gin, and the Mark of Kratos forged the mightiest microservice generator ever conceived.</p>
+        <div class="mt-6 h-px bg-gradient-to-r from-orange-200 via-rose-200 to-purple-200"></div>
+    </div>
+
+    <!-- Story Container -->
+    <div class="bg-white rounded-[2.5rem] p-10 md:p-16 border border-slate-200 shadow-2xl shadow-indigo-100/50 relative overflow-hidden">
+        <!-- Background Accents -->
+        <div class="absolute top-0 right-0 w-[40rem] h-[40rem] bg-indigo-50/50 rounded-full blur-[100px] -mr-48 -mt-48 pointer-events-none"></div>
+        <div class="absolute bottom-0 left-0 w-[30rem] h-[30rem] bg-purple-50/50 rounded-full blur-[100px] -ml-32 -mb-32 pointer-events-none"></div>
+
+        <div class="relative z-10 space-y-20">
+
+            <!-- Chapter 1 -->
+            <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center">
+                <div class="order-2 lg:order-1">
+                    <p class="text-xs font-bold uppercase tracking-widest text-indigo-400 mb-3">Chapter I</p>
+                    <h2 class="text-3xl font-extrabold text-slate-800 mb-5 font-serif italic text-indigo-700">The Encounter at the Crossroads</h2>
+                    <p class="text-slate-600 leading-relaxed text-lg">In the legendary Silicon Valley of Code, a nomadic <strong>Gopher</strong>—lightning-fast and known for his tireless concurrency—crossed paths with a <strong>Duck</strong> from the Great Persistence Bayou. The Duck held the wisdom of adaptability and the secret to navigating ever-shifting business tides. They realized that while the Gopher built fast, the Duck built to survive. Together, they forged a pact to create the <strong>Generator of Kings</strong>.</p>
+                </div>
+                <div class="order-1 lg:order-2 flex justify-center">
+                    <div class="relative group cursor-zoom-in" onclick="openLightbox('logo.png')">
+                        <div class="absolute inset-0 bg-indigo-400 blur-3xl opacity-20 group-hover:opacity-40 transition-all duration-700 rounded-full"></div>
+                        <img src="logo.png" alt="Partnership" class="w-80 h-80 object-contain filter drop-shadow-[0_20px_50px_rgba(0,0,0,0.2)] group-hover:scale-110 transition-transform duration-700 relative z-10">
+                    </div>
+                </div>
+            </div>
+
+            <div class="h-px bg-gradient-to-r from-transparent via-slate-200 to-transparent"></div>
+
+            <!-- Chapter 2 -->
+            <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center">
+                <div class="flex justify-center">
+                    <div class="relative group cursor-zoom-in" onclick="openLightbox('gin_bottle.png')">
+                        <img src="gin_bottle.png" alt="The Brew" class="w-80 h-80 object-contain filter drop-shadow-2xl group-hover:rotate-6 transition-transform duration-500">
+                        <div class="absolute -bottom-4 -right-4 bg-white px-4 py-2 rounded-xl shadow-lg border border-slate-100 font-bold text-indigo-600 text-sm">Gin Gonic Tonic</div>
+                    </div>
+                </div>
+                <div>
+                    <p class="text-xs font-bold uppercase tracking-widest text-fuchsia-400 mb-3">Chapter II</p>
+                    <h2 class="text-3xl font-extrabold text-slate-800 mb-5 font-serif italic text-fuchsia-700">The Refreshment of Performance</h2>
+                    <p class="text-slate-600 leading-relaxed text-lg">To fuel their grand design, they sought the <strong>Legendary Bottle of Gin</strong>. This magical brew wasn't just for hydration; it transformed their web routing into a crystalline, high-performance flow. Routes became fast, middleware became transparent, and the developer experience became as refreshing as a cold tonic on a summer's day. This gave GO-DUCK its distinctive, lightweight spirit.</p>
+                </div>
+            </div>
+
+            <div class="h-px bg-gradient-to-r from-transparent via-slate-200 to-transparent"></div>
+
+            <!-- Chapter 3 -->
+            <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center">
+                <div class="order-2 lg:order-1">
+                    <p class="text-xs font-bold uppercase tracking-widest text-emerald-400 mb-3">Chapter III</p>
+                    <h2 class="text-3xl font-extrabold text-slate-800 mb-5 font-serif italic text-emerald-700">The Armor of the Divine</h2>
+                    <p class="text-slate-600 leading-relaxed text-lg text-pretty">But speed without strength is a house made of cards. In the digital forge of the underworld, they recovered the <strong>Mark of Kratos</strong>. By stamping this sigil onto their internal services, they achieved gRPC industrial resilience. Every service became armored with strict Protocol Buffer contracts, ensuring that no matter how hard the system scaled, it would never break under the divine weight of technical debt.</p>
+                </div>
+                <div class="order-1 lg:order-2 flex justify-center">
+                    <div class="relative group cursor-zoom-in" onclick="openLightbox('kratos_mark.png')">
+                        <div class="absolute inset-0 bg-emerald-400 blur-3xl opacity-20 group-hover:opacity-40 transition-opacity"></div>
+                        <img src="kratos_mark.png" alt="The Sigil" class="w-80 h-80 object-contain relative z-10 group-hover:scale-110 transition-transform duration-700">
+                    </div>
+                </div>
+            </div>
+
+            <div class="h-px bg-gradient-to-r from-transparent via-slate-200 to-transparent"></div>
+
+            <!-- Chapter 4 -->
+            <div class="text-center max-w-4xl mx-auto">
+                <p class="text-xs font-bold uppercase tracking-widest text-amber-400 mb-3">Chapter IV</p>
+                <h2 class="text-3xl font-extrabold text-slate-900 mb-6 font-serif italic">The GDL Genesis</h2>
+                <p class="text-slate-600 leading-relaxed text-xl mb-10">Thus, the <strong>GDL (Go-Duck Language)</strong> was hatched. A single, simple tongue that could command entire legions of code. From that day forth, every developer who whispered GDL into the CLI would see their architecture <strong>evolve</strong>—bringing the Gopher's speed, the Duck's wisdom, the Gin's clarity, and the Kratos' strength into a single, unified masterpiece.</p>
+                <div class="flex justify-center gap-8 mb-10">
+                    <div class="flex flex-col items-center gap-2">
+                        <img src="logo.png" class="h-16 w-auto opacity-60 grayscale hover:grayscale-0 hover:opacity-100 transition-all duration-300 cursor-help" title="Adaptability — The Duck & Gopher">
+                        <span class="text-xs font-bold text-slate-400 uppercase tracking-wider">Adaptability</span>
+                    </div>
+                    <div class="flex flex-col items-center gap-2">
+                        <img src="gin_bottle.png" class="h-16 w-auto opacity-60 grayscale hover:grayscale-0 hover:opacity-100 transition-all duration-300 cursor-help" title="Clarity — The Gin Bottle">
+                        <span class="text-xs font-bold text-slate-400 uppercase tracking-wider">Clarity</span>
+                    </div>
+                    <div class="flex flex-col items-center gap-2">
+                        <img src="kratos_mark.png" class="h-16 w-auto opacity-60 grayscale hover:grayscale-0 hover:opacity-100 transition-all duration-300 cursor-help" title="Resilience — The Mark of Kratos">
+                        <span class="text-xs font-bold text-slate-400 uppercase tracking-wider">Resilience</span>
+                    </div>
+                </div>
+                <div class="inline-flex items-center gap-3 bg-gradient-to-r from-indigo-50 to-purple-50 border border-indigo-100 px-8 py-4 rounded-2xl">
+                    <span class="text-2xl">🦆</span>
+                    <span class="font-bold text-indigo-900">GO-DUCK — The Generator of Kings</span>
+                </div>
+            </div>
+
+        </div>
+    </div>
+
+    <!-- Epilogue CTA -->
+    <div class="mt-12 bg-slate-900 rounded-[2.5rem] p-12 text-center text-white relative overflow-hidden">
+        <div class="absolute inset-0 bg-gradient-to-br from-indigo-900/40 to-transparent"></div>
+        <div class="relative z-10">
+            <p class="text-slate-400 font-mono text-sm uppercase tracking-widest mb-4">The legend continues…</p>
+            <h3 class="text-3xl font-black mb-6 tracking-tight italic">Ready to write your chapter?</h3>
+            <div class="flex flex-wrap gap-4 justify-center">
+                <a href="gdl.html" class="px-8 py-4 bg-indigo-600 text-white font-bold rounded-xl hover:bg-indigo-500 transition-all uppercase tracking-widest text-xs shadow-lg">Learn GDL</a>
+                <a href="cli.html" class="px-8 py-4 bg-white/10 text-white font-bold rounded-xl hover:bg-white/20 transition-all border border-white/20 uppercase tracking-widest text-xs backdrop-blur-md">CLI Guide</a>
+            </div>
+        </div>
+    </div>
+
+</div>

package/templates/docs/pages/mosquitto.hbs

@@ -0,0 +1,39 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Mosquitto & Event Streaming</h1>
+<p class="text-lg text-gray-600 mb-8">Architect robust, event-driven microservices using Eclipse Mosquitto for high-performance MQTT messaging.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Why MQTT?</h2>
+    <p class="mb-4 text-gray-700">MQTT is a lightweight, publish-subscribe network protocol that transports messages between devices. In the GO-DUCK ecosystem, we use <strong>Eclipse Mosquitto</strong> as our primary message broker for ultra-low latency event streaming and internal service notifications.</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">The Messaging Package</h2>
+    <p class="mb-4">GO-DUCK generates a clean <code>messaging</code> package that abstracts the MQTT client (Eclipse Paho). It handles reconnect strategies, certificate-based TLS (optional), and asynchronous publishing.</p>
+    
+    <div class="bg-purple-50 border-l-4 border-purple-500 p-4 mb-6 rounded-r">
+        <p class="text-purple-900"><strong>Audit Streaming:</strong> By default, if <code>@Audited</code> is used in GDL, GO-DUCK streams all entity change events to the MQTT topic <code>audit/logs/{{appName}}</code> for real-time consumption by external analytics or notification engines.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6 text-xl">Publishing an Event</h3>
+    <pre><code class="language-go">import "{{appName}}/messaging"
+
+// Publishing a custom JSON event
+event := map[string]interface{}{"event": "user_signed_up", "email": "dev@goduck.io"}
+messaging.Publish("events/users", event)</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Local Development</h2>
+    <p class="mb-4">Your <code>docker-compose.yml</code> includes a pre-configured Mosquitto image. You can use any MQTT client (like MQTT.fx or mosquitto_pub/sub) to listen to your service events.</p>
+    <pre><code class="language-bash"># Subscribe to all audit events locally
+mosquitto_sub -h localhost -p 1883 -t "audit/logs/#" -v</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">External Resources</h2>
+    <ul class="space-y-2">
+        <li><a href="https://mosquitto.org/documentation/" target="_blank" class="text-indigo-600 hover:underline">Mosquitto Official Documentation &rarr;</a></li>
+        <li><a href="https://mqtt.org/getting-started/" target="_blank" class="text-indigo-600 hover:underline">Getting Started with MQTT &rarr;</a></li>
+        <li><a href="https://github.com/eclipse/paho.mqtt.golang" target="_blank" class="text-indigo-600 hover:underline">Eclipse Paho Go Client &rarr;</a></li>
+    </ul>
+</section>

package/templates/docs/pages/multitenancy.hbs

@@ -1,83 +1,151 @@
-<div class="mb-10 text-center lg:text-left border-b border-slate-200 pb-8">
-    <div class="inline-flex items-center px-3 py-1 rounded-full bg-blue-100 text-blue-700 text-xs font-semibold tracking-wide uppercase mb-4">
-        Enterprise Architecture
+<div class="prose prose-slate max-w-none">
+    <!-- Marketing Hero -->
+    <div class="flex items-center space-x-3 mb-8 text-blue-700">
+        <div class="p-4 bg-gradient-to-br from-blue-600 to-indigo-800 rounded-2xl shadow-lg shadow-blue-100">
+            <svg class="w-8 h-8 text-white" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4" />
+            </svg>
+        </div>
+        <h1 class="text-5xl font-black text-slate-900 m-0 tracking-tight leading-tight">The Federated Masterclass</h1>
     </div>
-    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">Dynamic Multi-Tenancy</h1>
-    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">Secure, high-performance database-per-tenant isolation with real-time connection hot-swapping.</p>
-</div>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-blue-100 text-blue-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 11H5m14 0a2 2 0 012 2v6a2 2 0 01-2 2H5a2 2 0 01-2-2v-6a2 2 0 012-2m14 0V9a2 2 0 00-2-2M5 11V9a2 2 0 012-2m0 0V5a2 2 0 012-2h6a2 2 0 012 2v2M7 7h10"></path></svg>
-        </span>
-        The Dual-DB Architecture
-    </h2>
-    <p class="mb-6 text-slate-600 leading-relaxed">GO-DUCK separates management logic from customer data. Your application maintains a persistent connection to a <strong>Master Database</strong> while dynamically "Relocating" per-request traffic to isolated <strong>Tenant Databases</strong>.</p>
+    <p class="text-2xl text-slate-500 font-medium mb-12 leading-relaxed">
+        Go beyond simple multi-tenancy. Orchestrate a global empire of data silos with real-time synchronization and parallel read aggregation.
+    </p>
 
-    <div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-8">
-        <div class="p-6 rounded-2xl border border-slate-200 bg-white shadow-sm">
-            <div class="w-12 h-12 bg-indigo-100 rounded-xl flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-indigo-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"></path></svg>
+    <!-- The Scenario: The Global dealership -->
+    <section class="mb-20">
+        <div class="bg-slate-900 rounded-[3rem] p-12 text-white shadow-2xl relative overflow-hidden">
+            <div class="absolute top-0 right-0 p-12 opacity-10">
+                <svg class="w-64 h-64" fill="currentColor" viewBox="0 0 24 24"><path d="M12 2L4.5 20.29l.71.71L12 18l6.79 3 .71-.71z"/></svg>
+            </div>
+            <div class="relative z-10">
+                <h2 class="text-4xl font-black mb-6 text-blue-400">Deep Dive: The Dealership Scenario</h2>
+                <p class="text-xl text-slate-300 mb-8 leading-relaxed">
+                    Imagine a car—<strong>Car ABC</strong>—owned by <strong>Customer X</strong>. Customer X regularly visits <strong>Dealership A (Home)</strong>, but today they are 1,000 miles away and visit <strong>Dealership B (Guest)</strong> for an emergency repair.
+                </p>
+                <div class="grid grid-cols-1 md:grid-cols-2 gap-8">
+                    <div class="bg-slate-800/50 p-8 rounded-3xl border border-white/10">
+                        <h4 class="text-blue-300 font-bold mb-4">Without Federation</h4>
+                        <p class="text-sm text-slate-400">Dealership B creates a record. Dealership A knows nothing about it. When the car returns home, the service history is fragmented. The "Single Source of Truth" is broken.</p>
+                    </div>
+                    <div class="bg-blue-600/20 p-8 rounded-3xl border border-blue-500/30">
+                        <h4 class="text-green-400 font-bold mb-4">With GO-DUCK Federation</h4>
+                        <p class="text-sm text-slate-200">Dealership B saves the record. GO-DUCK automatically broadcasts this to Dealership A in the background. Both databases now hold the complete, unified history of the car.</p>
+                    </div>
+                </div>
             </div>
-            <h3 class="text-xl font-bold text-slate-900 mb-2">Master Registry</h3>
-            <p class="text-slate-600 text-sm leading-relaxed">The <code>tenant_roles</code> table in the Master DB acts as the "Grand Concierge," mapping authenticated user roles to physical database names at runtime.</p>
         </div>
-        <div class="p-6 rounded-2xl border border-slate-200 bg-white shadow-sm">
-            <div class="w-12 h-12 bg-emerald-100 rounded-xl flex items-center justify-center mb-4">
-                <svg class="w-6 h-6 text-emerald-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path></svg>
+    </section>
+
+    <!-- Annotation Logic -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight italic underline decoration-blue-600 underline-offset-8">Architectural Control: The Annotations</h2>
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-12">
+            <div class="space-y-6">
+                <h3 class="text-2xl font-bold text-slate-800">1. Standard Multi-Tenancy</h3>
+                <div class="bg-slate-100 p-6 rounded-2xl border border-slate-200">
+                    <code class="text-blue-700 font-mono text-sm">entity DealershipSettings { ... }</code>
+                </div>
+                <p class="text-slate-600 text-sm">
+                    <strong>Behavior:</strong> Stored in the tenant's primary database only. No synchronization. High performance, zero overhead. 
+                    <br><br>
+                    <strong>Use Case:</strong> Data that belongs to a specific site, like internal employee lists or site colors.
+                </p>
+            </div>
+            <div class="space-y-6">
+                <h3 class="text-2xl font-bold text-blue-700">2. Federated Multi-Tenancy</h3>
+                <div class="bg-blue-50 p-6 rounded-2xl border border-blue-100">
+                    <code class="text-blue-700 font-mono text-sm">@Federated entity ServiceHistory { ... }</code>
+                </div>
+                <p class="text-slate-600 text-sm">
+                    <strong>Behavior:</strong> Triggers the <strong>Saga/Outbox Engine</strong>. Writes are broadcast to all authorized silos. Reads are aggregated in parallel.
+                    <br><br>
+                    <strong>Use Case:</strong> Critical data that must be "Everywhere," like car health, global inventory, or customer profiles.
+                </p>
             </div>
-            <h3 class="text-xl font-bold text-slate-900 mb-2">Hot-Swapping Pools</h3>
-            <p class="text-slate-600 text-sm leading-relaxed">The <code>TenantDBManager</code> uses lazy loading to open and cache connection pools for tenants only when they are active, ensuring minimal resource overhead.</p>
         </div>
-    </div>
-</section>
+    </section>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-rose-100 text-rose-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 00-2 2zm10-10V7a4 4 0 00-8 0v4h8z"></path></svg>
-        </span>
-        Security & Anti-Spoofing
-    </h2>
-    <p class="mb-6 text-slate-600 leading-relaxed">Header-based tenancy (<code>X-Tenant-ID</code>) is convenient but dangerous. GO-DUCK solves this by cryptographically validating the tenant context against the JWT.</p>
-    
-    <div class="bg-slate-900 rounded-2xl p-6 shadow-xl mb-6">
-        <h4 class="text-emerald-400 font-mono text-sm mb-4">// Internal Verification Loop</h4>
-        <pre class="text-slate-300 font-mono text-sm leading-relaxed">
-1. Extract Roles from signed Keycloak JWT
-2. Lookup authorized DB in Master mapping table
-3. Compare against X-Tenant-ID header
-4. If Mismatch: Return 403 Forbidden (Security Breach)
-5. If Match: Activate Dynamic Connection Pool
-        </pre>
-    </div>
-</section>
+    <!-- TRIPLE-IDENTITY REGISTRY -->
+    <section class="mb-20">
+        <h2 class="text-3xl font-black text-slate-900 mb-8 tracking-tight italic underline decoration-blue-600 underline-offset-8">Triple-Identity Registry: Opaque Decoupling</h2>
+        <p class="text-slate-600 mb-8 leading-relaxed">
+            To prevent <strong>ID Enumeration</strong> and protect physical infrastructure paths, GO-DUCK implements a sophisticated 3-layer identity registry. This ensures that guessable database names are never leaked to the client.
+        </p>
 
-<section class="mb-12">
-    <h2 class="text-2xl font-bold text-slate-800 mb-6 flex items-center">
-        <span class="w-8 h-8 rounded-lg bg-amber-100 text-amber-600 flex items-center justify-center mr-3 text-sm">
-            <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6V4m0 2a2 2 0 100 4m0-4a2 2 0 110 4m-6 8a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4m6 6v10m6-2a2 2 0 100-4m0 4a2 2 0 110-4m0 4v2m0-6V4"></path></svg>
-        </span>
-        Tenant Provisioning API
-    </h2>
-    <p class="mb-6 text-slate-600 leading-relaxed">Adding a new customer is a single atomic operation. Use the management API to provision a side-by-side database instantly.</p>
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-8">
+            <div class="p-8 bg-white border border-slate-200 rounded-[2.5rem] shadow-sm relative overflow-hidden group">
+                <div class="w-12 h-12 bg-blue-100 text-blue-600 rounded-xl flex items-center justify-center font-black mb-6">1</div>
+                <h4 class="text-lg font-black text-slate-900 mb-3">Identity Layer</h4>
+                <p class="text-sm text-slate-500 italic">Keycloak Realm Role (e.g. <code>dealer_tokyo</code>). This is the source of truth for authorization.</p>
+            </div>
+            <div class="p-8 bg-white border border-slate-200 rounded-[2.5rem] shadow-sm relative overflow-hidden group">
+                <div class="w-12 h-12 bg-indigo-100 text-indigo-600 rounded-xl flex items-center justify-center font-black mb-6">2</div>
+                <h4 class="text-lg font-black text-slate-900 mb-3">Opaque Layer</h4>
+                <p class="text-sm text-slate-500 italic">Randomly generated UUID (e.g. <code>bc72-a180...</code>) exposed via the <code>X-Tenant-ID</code> header.</p>
+            </div>
+            <div class="p-8 bg-white border border-slate-200 rounded-[2.5rem] shadow-sm relative overflow-hidden group">
+                <div class="w-12 h-12 bg-emerald-100 text-emerald-600 rounded-xl flex items-center justify-center font-black mb-6">3</div>
+                <h4 class="text-lg font-black text-slate-900 mb-3">Physical Layer</h4>
+                <p class="text-sm text-slate-500 italic">The actual database name (e.g. <code>dealership_silo_japan_prod</code>). Only the server knows this link.</p>
+            </div>
+        </div>
+    </section>
 
-    <div class="bg-[#1e1e1e] rounded-xl overflow-hidden shadow-lg mb-4">
-        <div class="bg-[#2d2d2d] px-4 py-2 border-b border-[#404040] flex items-center">
-            <span class="px-2 py-0.5 rounded bg-emerald-500/20 text-emerald-400 text-[10px] font-bold mr-3">POST</span>
-            <span class="text-xs text-slate-300 font-mono">/management/db/create</span>
+    <!-- The Dual-Path Secret -->
+    <section class="mb-20">
+        <div class="bg-gradient-to-br from-blue-700 to-indigo-900 rounded-[3rem] p-12 text-white shadow-2xl">
+            <h2 class="text-4xl font-black mb-6">The Dual-Path Orchestrator</h2>
+            <p class="text-lg text-blue-100 mb-10 leading-relaxed">
+                GO-DUCK doesn't force you into one model. Our generated middleware and controllers detect your GDL annotations and switch behavior in real-time.
+            </p>
+            
+            <div class="space-y-8">
+                <div class="flex items-start space-x-6">
+                    <div class="w-12 h-12 bg-white/10 rounded-xl flex items-center justify-center flex-shrink-0 font-black text-xl">01</div>
+                    <div>
+                        <h4 class="text-xl font-bold text-white mb-2">Silo-Connection-Cache</h4>
+                        <p class="text-blue-100/70 text-sm">Prevents connection exhaustion across 100+ silos using a singleton-based cache. DB/Mongo clients are lazily initialized and kept warm.</p>
+                    </div>
+                </div>
+                <div class="flex items-start space-x-6">
+                    <div class="w-12 h-12 bg-white/10 rounded-xl flex items-center justify-center flex-shrink-0 font-black text-xl">02</div>
+                    <div>
+                        <h4 class="text-xl font-bold text-white mb-2">Parallel Read Harvest</h4>
+                        <p class="text-blue-100/70 text-sm">When you query a <code>@Federated</code> entity, GO-DUCK launches simultaneous Go-routines to every database you own, stitching the global picture together in milliseconds.</p>
+                    </div>
+                </div>
+                <div class="flex items-start space-x-6">
+                    <div class="w-12 h-12 bg-white/10 rounded-xl flex items-center justify-center flex-shrink-0 font-black text-xl">03</div>
+                    <div>
+                        <h4 class="text-xl font-bold text-white mb-2">Transactional Atomic Broadcast</h4>
+                        <p class="text-blue-100/70 text-sm">A write to one silo is a write to all. Using the Outbox pattern, we guarantee that even if Dealership A is offline, Dealership B's updates will eventually arrive safely.</p>
+                    </div>
+                </div>
+                <div class="flex items-start space-x-6">
+                    <div class="w-12 h-12 bg-white/10 rounded-xl flex items-center justify-center flex-shrink-0 font-black text-xl">04</div>
+                    <div>
+                        <h4 class="text-xl font-bold text-white mb-2">Precision Harvesting</h4>
+                        <p class="text-blue-100/70 text-sm">Pass a comma-separated list of UUIDs in the <code>X-Tenant-ID</code> header. The Harvester reduces its fan-out to ONLY these silos for surgical efficiency.</p>
+                    </div>
+                </div>
+            </div>
         </div>
-        <div class="p-5 text-sm font-mono text-slate-300">
-            {
-                "role": "ROLE_ACME_CORP",
-                "db_name": "acme_isolated_db"
-            }
+    </section>
+
+    <!-- Summary FAQ -->
+    <section class="mb-10">
+        <h3 class="text-2xl font-black text-slate-800 mb-6">Elite FAQ</h3>
+        <div class="space-y-4">
+            <div class="p-6 bg-white border border-slate-200 rounded-2xl shadow-sm">
+                <p class="text-slate-900 font-bold mb-2 small italic">What if I assigned multiple DBs to a role but forgot @Federated?</p>
+                <p class="text-slate-500 text-sm leading-relaxed">GO-DUCK will only use your <strong>Primary/Default</strong> database. It will not harvest data from the other assigned silos. You must use the annotation to unlock aggregation.</p>
+            </div>
+            <div class="p-6 bg-white border border-slate-200 rounded-2xl shadow-sm">
+                <p class="text-slate-900 font-bold mb-2 small italic">Is there a performance hit for @Federated?</p>
+                <p class="text-slate-500 text-sm leading-relaxed">Reads use parallel goroutines, making them extremely fast even across silos. Writes include one extra row in the Outbox table—a small price for global consistency.</p>
+            </div>
         </div>
-    </div>
-    <ul class="space-y-3 text-slate-600 text-sm">
-        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Executing physical <code>CREATE DATABASE</code></li>
-        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Mapping role to DB in <code>tenant_roles</code> Master table</li>
-        <li class="flex items-center"><svg class="w-4 h-4 text-emerald-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"></path></svg> Triggering automated Liquibase migrations on new DB</li>
-    </ul>
-</section>
+    </section>
+</div>

package/templates/docs/pages/otel.hbs

@@ -0,0 +1,40 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">OpenTelemetry (OTel) & Jaeger</h1>
+<p class="text-lg text-gray-600 mb-8">Master the art of distributed tracing to debug complex inter-service communications in real-time.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">What is OpenTelemetry?</h2>
+    <p class="mb-4 text-gray-700">OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, generate, collect, and export telemetry data (metrics, logs, and traces). GO-DUCK implements a <strong>"Full-Stack Tracing"</strong> strategy.</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">The Trace Pipeline</h2>
+    <p class="mb-4">Trace context is automatically propagated across your entire stack:</p>
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-4 mb-6 text-center">
+        <div class="p-4 bg-gray-50 border rounded font-semibold text-indigo-700">HTTP Router (Gin)</div>
+        <div class="p-4 bg-gray-50 border rounded font-semibold text-indigo-700">Service/Controller</div>
+        <div class="p-4 bg-gray-50 border rounded font-semibold text-indigo-700">Database (GORM)</div>
+    </div>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900">Each database query is automatically tagged with the <code>trace_id</code> of the incoming HTTP request. This allows you to identify exactly which REST call caused a slow SQL query.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6 text-xl">The OTel Collector</h3>
+    <p class="mb-4">GO-DUCK apps don't speak directly to tracing backends. Instead, they export via gRPC to an <strong>otel-collector</strong> sidecar. This collector acts as a buffer and can fan-out data to Jaeger, Datadog, or Honeycomb simultaneously.</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Visualizing with Jaeger</h2>
+    <p class="mb-4 text-gray-700">In local development, GO-DUCK spins up a Jaeger instance. It provides a web-based UI to search and visualize your traces.</p>
+    <pre><code class="language-bash"># Open Jaeger UI locally
+open http://localhost:16686</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">External Resources</h2>
+    <ul class="space-y-2">
+        <li><a href="https://opentelemetry.io/docs/" target="_blank" class="text-indigo-600 hover:underline">OpenTelemetry Official Docs &rarr;</a></li>
+        <li><a href="https://www.jaegertracing.io/docs/" target="_blank" class="text-indigo-600 hover:underline">Jaeger Tracing Documentation &rarr;</a></li>
+        <li><a href="https://opentelemetry.io/docs/collector/" target="_blank" class="text-indigo-600 hover:underline">OTel Collector Guide &rarr;</a></li>
+    </ul>
+</section>

package/templates/docs/pages/realtime.hbs

@@ -13,31 +13,57 @@
     <pre><code class="language-javascript">const token = "eyJhbGciOi..."; // Valid Keycloak Access Token
 
 // Phase 1: Authentication happens precisely on the handshake (WSS Handshake via query param)
-const ws = new WebSocket(\`ws://localhost:8080/ws?token=\${token}\`);
+const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);
 
 ws.onopen = () => {
-  // Phase 2: Send HMAC-SHA256 Encrypted / Signed Messages!
+  // Phase 2: Send HMAC-SHA256 Signed Messages
+  // The Signature is the HMAC-SHA256 of (Method + Path + Payload) using your API Key
   ws.send(JSON.stringify({
     TraceID: "uuid-v4-frontend-req",
     Method: "GET",
     Path: "/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s",
     Payload: "{}",
-    Signature: "2d7a221f7dbb2..." // Signature ensures Message Integrity
+    Signature: "2d7a221f7dbb2..." 
   }));
 };
 
 ws.onmessage = (event) => console.log("Received via WS:", event.data);</code></pre>
+
+    <div class="mt-8 p-6 bg-slate-900 rounded-2xl border border-slate-700">
+        <h4 class="text-white font-bold mb-4 flex items-center">
+            <svg class="w-5 h-5 mr-2 text-emerald-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"></path></svg>
+            Message Integrity (HMAC-SHA256)
+        </h4>
+        <p class="text-sm text-slate-400 mb-4">To prevent man-in-the-middle tampering on full-duplex streams, GO-DUCK requires every WebSocket envelope to be digitally signed.</p>
+        <div class="grid grid-cols-1 md:grid-cols-2 gap-4 text-xs font-mono">
+            <div class="p-3 bg-slate-800 rounded-lg text-slate-300">
+                <span class="text-emerald-400 font-bold block mb-1">Algorithm</span>
+                HMAC-SHA256
+            </div>
+            <div class="p-3 bg-slate-800 rounded-lg text-slate-300">
+                <span class="text-emerald-400 font-bold block mb-1">Signed Data</span>
+                method + path + payload
+            </div>
+        </div>
+    </div>
 </section>
 
 <section class="mb-10">
-    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">2. Asynchronous MQTT Streaming</h2>
-    <p class="mb-4">Rather than relying entirely on synchronous API calls, every successful <code>CREATE / UPDATE / DELETE</code> on any GDL generated model emits an event to the unified MQTT broker configured in the `docker-compose.yml`.</p>
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">2. Unified Messaging Hub (MQTT & NATS)</h2>
+    <p class="mb-4">GO-DUCK features a <strong>Multi-Broker Messaging Hub</strong>. Every successful <code>CREATE / UPDATE / DELETE</code> on any model is simultaneously broadcast to both brokers if enabled.</p>
     
-    <h3 class="font-semibold mb-2">How to listen for specific webhooks</h3>
-    <pre><code class="language-bash"># mosquitto_sub listening to any mutation globally inside the microservice
-mosquitto_sub -h localhost -p 1883 -t "go-duck/events/#" -u dev_user -P dev_password
-
-# To listen ONLY when the {{capitalize (defaultStr (lookup entities "0.name") "Entity")}} object gets created
-mosquitto_sub -h localhost -p 1883 -t "go-duck/events/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}/CREATE" -u dev_user -P dev_password
-</code></pre>
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mb-8">
+        <div class="bg-gray-50 p-6 rounded-xl border border-gray-200">
+            <h4 class="font-bold text-blue-600 mb-2 font-mono">MQTT (Real-time UI)</h4>
+            <p class="text-sm text-gray-600 mb-4">Topic Pattern: <code>go-duck/events/{entity}/{action}</code></p>
+            <pre class="text-xs bg-slate-900 text-white p-3 rounded"><code># Listen to Car Deletions
+mosquitto_sub -t "go-duck/events/car/DELETE"</code></pre>
+        </div>
+        <div class="bg-gray-50 p-6 rounded-xl border border-gray-200">
+            <h4 class="font-bold text-green-600 mb-2 font-mono">NATS (High-Perf CQRS)</h4>
+            <p class="text-sm text-gray-600 mb-4">Subject Pattern: <code>go.duck.events.{entity}.{action}</code></p>
+            <pre class="text-xs bg-slate-900 text-white p-3 rounded"><code># Listen to any Car mutations
+nats sub "go.duck.events.car.>"</code></pre>
+        </div>
+    </div>
 </section>

package/templates/docs/pages/redis.hbs

@@ -0,0 +1,40 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Redis: Distributed Caching & Beyond</h1>
+<p class="text-lg text-gray-600 mb-8">Optimize your microservice performance with blitz-fast distributed caching using Redis.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Cache Architecture</h2>
+    <p class="mb-4 text-gray-700">GO-DUCK implements a <strong>"Cache-Aside"</strong> strategy. This ensures that your application remains resilient: if Redis is down, the application automatically falls back to the database without crashing, thanks to our integrated <strong>Circuit Breakers</strong> (via Sony/Gobreaker).</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Multi-Tenant Isolation</h2>
+    <p class="mb-4">Standard caching in a multi-tenant app is dangerous. GO-DUCK solves this by **Tenant-Prefixing** every key automatically. Your cache keys look like <code>tenant_abc:User:123</code>, preventing data leaks across tenants.</p>
+    
+    <div class="bg-red-50 border-l-4 border-red-500 p-4 mb-6 rounded-r">
+        <p class="text-red-900"><strong>Automatic Invalidation:</strong> Our repository layer handles cache invalidation. When you update or delete an entity via the REST/gRPC API, the corresponding Redis key is purged instantly to maintain data consistency.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6 text-xl">Direct Cache Usage</h3>
+    <pre><code class="language-go">import "{{appName}}/cache"
+
+// Store a value for 10 minutes
+cache.Set(ctx, "my-key", myStruct, 10 * time.Minute)
+
+// Retrieve and deserialize
+var target MyStruct
+err := cache.Get(ctx, "my-key", &target)</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Resilience with Redis</h2>
+    <p class="mb-4 text-gray-700">All Redis calls are wrapped in a <strong>Circuit Breaker</strong>. If Redis experiences high latency or connection resets, the circuit opens, and your Go application skips the cache layers to protect the system from cascading failure.</p>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">External Resources</h2>
+    <ul class="space-y-2">
+        <li><a href="https://redis.io/documentation" target="_blank" class="text-indigo-600 hover:underline">Redis Official Documentation &rarr;</a></li>
+        <li><a href="https://github.com/go-redis/redis" target="_blank" class="text-indigo-600 hover:underline">Go-Redis Client Library &rarr;</a></li>
+        <li><a href="https://redis.com/blog/cache-aside-pattern-explained/" target="_blank" class="text-indigo-600 hover:underline">The Cache-Aside Pattern &rarr;</a></li>
+    </ul>
+</section>