go-duck-cli 1.0.0

package/templates/docs/pages/index.hbs

@@ -0,0 +1,181 @@
+<div class="mb-16 text-center lg:text-left relative">
+    <div class="flex flex-col lg:flex-row items-center justify-center lg:justify-start mb-8 gap-8">
+        <div class="relative group">
+            <div class="absolute -inset-1 bg-gradient-to-r from-indigo-500 to-purple-600 rounded-2xl blur opacity-25 group-hover:opacity-50 transition duration-1000 group-hover:duration-200"></div>
+            <img src="logo.png" alt="GO-DUCK" class="h-28 w-auto drop-shadow-2xl relative bg-white/50 backdrop-blur-sm rounded-2xl p-2 border border-white/50 animate-bounce-slow">
+        </div>
+        <div>
+            <h1 class="text-6xl lg:text-8xl font-extrabold text-slate-900 tracking-tighter leading-tight mb-2">GO-DUCK</h1>
+            <p class="text-2xl text-transparent bg-clip-text bg-gradient-to-r from-indigo-600 to-purple-600 font-bold tracking-widest uppercase">The Evolutionary Architecture Factory</p>
+        </div>
+    </div>
+    <p class="text-xl lg:text-3xl text-slate-600 max-w-4xl leading-relaxed font-light">Where high-velocity <strong>Gophers</strong> meet the versatile wisdom of the <strong>Duck</strong> to scaffold microservices that thrive in chaos.</p>
+</div>
+
+<section id="the-story" class="mb-24 relative">
+    <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"></div>
+        <div class="absolute bottom-0 left-0 w-[30rem] h-[30rem] bg-purple-50/50 rounded-full blur-[100px] -ml-32 -mb-32"></div>
+
+        <div class="relative z-10">
+            <h2 class="text-4xl font-extrabold text-slate-900 mb-6 flex items-center tracking-tight">
+                <span class="w-12 h-12 rounded-2xl bg-gradient-to-tr from-orange-400 to-rose-400 text-white flex items-center justify-center mr-5 shadow-lg animate-pulse">🦆</span>
+                The Legend of the Century
+            </h2>
+
+            <!-- Cinematic Introduction -->
+            <div class="mb-16 relative group">
+                <div class="absolute -inset-2 bg-gradient-to-r from-indigo-500 to-purple-600 rounded-[2rem] blur opacity-15 group-hover:opacity-25 transition duration-1000"></div>
+                <div class="relative bg-black rounded-[1.5rem] overflow-hidden shadow-2xl border border-white/10 aspect-video">
+                    <video controls class="w-full h-full object-cover">
+                        <source src="intro.mp4" type="video/mp4">
+                        Your browser does not support the video tag.
+                    </video>
+                    <div class="absolute bottom-0 left-0 right-0 p-6 bg-gradient-to-t from-black/80 to-transparent pointer-events-none">
+                        <span class="text-white/70 text-sm font-medium tracking-widest uppercase">Cinematic Introduction</span>
+                        <h4 class="text-white text-xl font-bold">The Trailer of the Epic</h4>
+                    </div>
+                </div>
+            </div>
+            
+            <div class="space-y-16">
+                <!-- Chapter 1 -->
+                <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center">
+                    <div class="order-2 lg:order-1">
+                        <h3 class="text-2xl font-bold text-slate-800 mb-4 font-serif italic text-indigo-700">Chapter I: The Encounter at the Crossroads</h3>
+                        <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">
+                        <img src="logo.png" alt="Partnership" class="w-64 h-64 object-contain filter drop-shadow-2xl hover:scale-105 transition-transform duration-500">
+                    </div>
+                </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>
+                        <h3 class="text-2xl font-bold text-slate-800 mb-4 font-serif italic text-fuchsia-700">Chapter II: The Refreshment of Performance</h3>
+                        <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>
+
+                <!-- Chapter 3 -->
+                <div class="grid grid-cols-1 lg:grid-cols-2 gap-12 items-center animate-fade-in-up">
+                    <div class="order-2 lg:order-1">
+                        <h3 class="text-2xl font-bold text-slate-800 mb-4 font-serif italic text-emerald-700">Chapter III: The Armor of the Divine</h3>
+                        <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>
+
+                <!-- Chapter 4 -->
+                <div class="bg-slate-50 rounded-[2rem] p-8 md:p-12 border border-slate-100 text-center max-w-4xl mx-auto shadow-inner">
+                    <h3 class="text-3xl font-extrabold text-slate-900 mb-6">Chapter IV: The GDL Genesis</h3>
+                    <p class="text-slate-600 leading-relaxed text-xl mb-8">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-6">
+                        <img src="logo.png" class="h-12 w-auto opacity-50 grayscale hover:grayscale-0 transition-all cursor-help" title="Adaptability">
+                        <img src="gin_bottle.png" class="h-12 w-auto opacity-50 grayscale hover:grayscale-0 transition-all cursor-help" title="Clarity">
+                        <img src="kratos_mark.png" class="h-12 w-auto opacity-50 grayscale hover:grayscale-0 transition-all cursor-help" title="Resilience">
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+<section id="installation" class="mb-20">
+    <div class="flex flex-col lg:flex-row gap-10">
+        <div class="lg:w-1/2">
+            <h2 class="text-3xl font-bold text-slate-800 mb-8 flex items-center tracking-tight">
+                <span class="w-10 h-10 rounded-xl bg-slate-900 text-white flex items-center justify-center mr-4 shadow-md text-sm">💾</span>
+                Global Installation
+            </h2>
+            <div class="group relative">
+                <div class="absolute -inset-1 bg-gradient-to-r from-emerald-400 to-indigo-500 rounded-2xl blur opacity-25 group-hover:opacity-40 transition duration-1000"></div>
+                <div class="relative bg-slate-900 rounded-2xl overflow-hidden shadow-2xl border border-slate-800">
+                    <div class="bg-slate-800/80 px-6 py-4 flex items-center justify-between border-b border-slate-700/50">
+                        <div class="flex items-center space-x-2">
+                            <div class="w-2.5 h-2.5 rounded-full bg-rose-500/50"></div>
+                            <div class="w-2.5 h-2.5 rounded-full bg-amber-500/50"></div>
+                            <div class="w-2.5 h-2.5 rounded-full bg-emerald-500/50"></div>
+                        </div>
+                        <span class="text-xs text-slate-500 font-mono tracking-widest uppercase">npm-registry</span>
+                    </div>
+                    <div class="p-8 font-mono text-lg">
+                        <div class="flex items-center">
+                            <span class="text-emerald-400 mr-4 select-none">❯</span>
+                            <span class="text-slate-100">npm install -g <span class="text-indigo-400">go-duck-cli</span></span>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+        <div class="lg:w-1/2 flex flex-col justify-center space-y-4 pt-10 lg:pt-0">
+            <div class="p-8 rounded-3xl bg-white border border-slate-200 shadow-sm transition-all hover:shadow-md hover:border-slate-300">
+                <h4 class="font-bold text-slate-900 mb-4 flex items-center text-lg leading-none">
+                    <svg class="w-6 h-6 text-emerald-500 mr-3" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z"></path></svg>
+                    Environment Specs
+                </h4>
+                <div class="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                    <div class="p-3 bg-slate-50 rounded-xl flex items-center"><span class="w-2 h-2 bg-indigo-500 rounded-full mr-3 shrink-0"></span><span class="text-slate-600 font-medium">Node.js 18+</span></div>
+                    <div class="p-3 bg-slate-50 rounded-xl flex items-center"><span class="w-2 h-2 bg-indigo-500 rounded-full mr-3 shrink-0"></span><span class="text-slate-600 font-medium">Go 1.21+</span></div>
+                    <div class="p-3 bg-slate-50 rounded-xl flex items-center"><span class="w-2 h-2 bg-indigo-500 rounded-full mr-3 shrink-0"></span><span class="text-slate-600 font-medium">Docker v20+</span></div>
+                    <div class="p-3 bg-slate-50 rounded-xl flex items-center"><span class="w-2 h-2 bg-indigo-500 rounded-full mr-3 shrink-0"></span><span class="text-slate-600 font-medium">Composability v2+</span></div>
+                </div>
+            </div>
+        </div>
+    </div>
+</section>
+
+<section id="quick-start" 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-indigo-100 text-indigo-600 flex items-center justify-center mr-3 text-sm">🚀</span>
+        Scaffold & Run
+    </h2>
+    
+    <div class="bg-slate-800 rounded-xl overflow-hidden shadow-lg mb-10">
+        <div class="bg-slate-900/50 px-4 py-3 border-b border-slate-700/50 flex items-center">
+            <div class="flex space-x-1.5 mr-4">
+                <div class="w-3 h-3 rounded-full bg-rose-500"></div>
+                <div class="w-3 h-3 rounded-full bg-amber-500"></div>
+                <div class="w-3 h-3 rounded-full bg-emerald-500"></div>
+            </div>
+            <span class="text-xs text-slate-400 font-mono">Scaffolding Command</span>
+        </div>
+        <div class="p-5">
+            <pre><code class="language-bash text-sm"># 1. Create a new microservice
+go-duck create -o ./my-app -c config.yaml
+
+# 2. Enter and run
+cd my-app
+docker-compose up -d
+go run main.go</code></pre>
+        </div>
+    </div>
+
+    <h2 class="text-2xl font-bold text-slate-800 mb-6 mt-12 flex items-center">
+        <span class="w-8 h-8 rounded-lg bg-purple-100 text-purple-600 flex items-center justify-center mr-3 text-sm">✨</span>
+        Features Overview
+    </h2>
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-5 mb-8">
+        <div class="p-5 rounded-2xl border border-slate-200 bg-white hover:shadow-md transition-all duration-200 group">
+            <h3 class="font-bold text-slate-900 mb-2 flex items-center"><svg class="w-5 h-5 text-indigo-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9"></path></svg>REST & Search</h3>
+            <p class="text-sm text-slate-600 leading-relaxed">Standard CRUD routes alongside a high-performance PostgREST-style RPC system.</p>
+        </div>
+        <div class="p-5 rounded-2xl border border-slate-200 bg-white hover:shadow-md transition-all duration-200 group">
+            <h3 class="font-bold text-slate-900 mb-2 flex items-center"><svg class="w-5 h-5 text-fuchsia-500 mr-2" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M14 10l-2 1m0 0l-2-1m2 1v2.5M20 7l-2 1m2-1l-2-1m2 1v2.5M14 4l-2-1-2 1M4 7l2-1M4 7l2 1M4 7v2.5M12 21l-2-1m2 1l2-1m-2 1v-2.5M6 18l-2-1v-2.5M18 18l2-1v-2.5"></path></svg>GraphQL</h3>
+            <p class="text-sm text-slate-600 leading-relaxed">A complete Graph schema integrated natively with GORM data relations.</p>
+        </div>
+    </div>
+</section>

package/templates/docs/pages/integrations.hbs

@@ -0,0 +1,83 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Frontend Integrations</h1>
+<p class="text-lg text-gray-600 mb-8">Ready-to-use snippets to wire up leading frontend frameworks to your ultra-fast API backend seamlessly.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. Angular (TypeScript)</h2>
+    <p class="mb-4">Angular natively employs RxJS `HttpInterceptor` abstractions, making connecting to your GO-DUCK APIs simple.</p>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900"><strong>Note:</strong> We bypass typical manual HTTP Auth mapping by using Angular's pre-built <code>keycloak-angular</code> ecosystem package.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">Creating a Service for {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}</h3>
+    <pre><code class="language-typescript">import { Injectable } from '@angular/core';
+import { HttpClient, HttpParams } from '@angular/common';
+import { Observable } from 'rxjs';
+
+export interface {{capitalize (defaultStr (lookup entities "0.name") "Entity")}} {
+  id: number;
+{{#if entities.length}}
+  {{#each entities.0.fields}}
+  {{name}}: any;
+  {{/each}}
+{{/if}}
+}
+
+@Injectable({ providedIn: 'root' })
+export class {{capitalize (defaultStr (lookup entities "0.name") "Entity")}}Service {
+  private apiUrl = 'http://localhost:8080/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s';
+
+  constructor(private http: HttpClient) {}
+
+  // Standard REST Fetch with Pagination Parameters
+  getAll(page: number = 1, pageSize: number = 10): Observable&lt;any&gt; {
+    let params = new HttpParams()
+        .set('page', page.toString())
+        .set('pageSize', pageSize.toString());
+    return this.http.get&lt;any&gt;(this.apiUrl, { params });
+  }
+
+  // Example: Using the powerful Generic Search RPC Engine
+  search(queryField: string, operator: string, value: string): Observable&lt;any&gt; {
+    let params = new HttpParams().set(queryField, \`\${operator}.\${value}\`);
+    return this.http.get&lt;any&gt;('http://localhost:8080/api/rpc/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}', { params });
+  }
+}
+</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">2. Flutter (Dart)</h2>
+    <p class="mb-4">Connecting a cross-platform mobile app requires managing state efficiently. Here's a raw HTTP Dart integration model you can bind to Provider, Riverpod, or BLoC patterns seamlessly over your Keycloak environment.</p>
+    
+    <pre><code class="language-dart">import 'dart:convert';
+import 'package:http/http.dart' as http;
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+class ApiProvider {
+  static const String baseUrl = "http://localhost:8080/api/{{toLowerCase (defaultStr (lookup entities "0.name") "entity")}}s";
+  final storage = const FlutterSecureStorage();
+
+  // Retrieve Keycloak Bearer token from secure storage
+  Future&lt;Map&lt;String, String&gt;&gt; _getHeaders() async {
+    String? token = await storage.read(key: 'jwt_token');
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': 'Bearer $token',
+      'X-Tenant-ID': 'default', // If using Multi-Tenancy module
+    };
+  }
+
+  // Fetch API collection
+  Future&lt;List&lt;dynamic&gt;&gt; fetch{{capitalize (defaultStr (lookup entities "0.name") "Entity")}}s() async {
+    final response = await http.get(Uri.parse(baseUrl), headers: await _getHeaders());
+    if (response.statusCode == 200) {
+      final data = json.decode(response.body);
+      return data['results']; 
+    } else {
+      throw Exception('Failed to load data. Res code: \${response.statusCode}');
+    }
+  }
+}
+</code></pre>
+</section>

package/templates/docs/pages/observability.hbs

@@ -0,0 +1,34 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Total Observability Ecosystem</h1>
+<p class="text-lg text-gray-600 mb-8">Metrics, Datadog streaming, and OpenTelemetry distributed tracing pre-configured natively inside your microservice architecture.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. OpenTelemetry Distributed Tracing (OTel)</h2>
+    <p class="mb-4">With multiple applications talking to each other, debugging an API timeout inside a black-box environment is devastating. GO-DUCK generated apps utilize full-stack <strong>OpenTelemetry</strong>.</p>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900"><strong>Note:</strong> Traces cover the entire round trip. They begin at the <code>otelgin</code> Router level, propagate securely via ctx context through your Controllers and Services, and are eventually finalized by the highly optimized <code>gorm.io/plugin/opentelemetry/tracing</code> hook at the Database execution level.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">Where to view traces?</h3>
+    <p class="mb-4">The Go application pushes these <code>otlptracegrpc</code> trace chunks asynchronously out to an <strong>otel-collector</strong> container over port <code>4317</code>.</p>
+    <pre><code class="language-bash"># The pre-packaged docker-compose spins up a Jaeger UI node 
+# Point your browser to:
+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">2. Datadog Integration (Log Consolidation)</h2>
+    <p class="mb-4">If deployed to the cloud, GO-DUCK apps are compatible with Datadog's Agent endpoints immediately. Inside the <code>application-prod.yml</code>, flip the <code>enabled: true</code> config marker and supply an API key.</p>
+    
+    <pre><code class="language-yaml"># Inside application.yml
+go-duck:
+  logging:
+    datadog:
+      enabled: true
+      api-key: "YOUR_NATIVE_DD_AGENT_API_KEY_HERE"
+      site: "datadoghq.com"
+      service: "inventory-microservice"</code></pre>
+
+    <h3 class="font-semibold mb-2 mt-6">3. System Infrastructure Metrics (Statsd)</h3>
+    <p class="mb-4 text-gray-700">The <code>logger</code> package has a sidecar implementation for Datadog's <code>statsd</code>. A developer can quickly drop custom <code>logger.Count("api.hit")</code> or <code>logger.Histogram("db.latency")</code> functions into their services to populate dashboard charts.</p>
+</section>

package/templates/docs/pages/realtime.hbs

@@ -0,0 +1,43 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">WebSockets & MQTT Event Streaming</h1>
+<p class="text-lg text-gray-600 mb-8">Execute REST requests securely over full-duplex WebSocket connections or subscribe to async CRUD event streaming.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. REST-over-WS Dispatcher</h2>
+    <p class="mb-4">Instead of traditional HTTP, you can pass highly efficient "Traced Envelopes" through our WebSocket endpoint at <code>ws://localhost:8080/ws</code>. The GO-DUCK generated engine unpacks the WS payload and routes it natively through Gin.</p>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900"><strong>Note:</strong> Token validation is done via query-param out of necessity due to websocket protocol limitations.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">Browser/JS Connection Spec</h3>
+    <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}\`);
+
+ws.onopen = () => {
+  // Phase 2: Send HMAC-SHA256 Encrypted / Signed Messages!
+  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
+  }));
+};
+
+ws.onmessage = (event) => console.log("Received via WS:", event.data);</code></pre>
+</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>
+    
+    <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>
+</section>

package/templates/docs/pages/rest.hbs

@@ -0,0 +1,149 @@
+<div class="mb-10 text-center lg:text-left border-b border-slate-200 pb-8 text-neutral-900">
+    <div class="inline-flex items-center px-3 py-1 rounded-full bg-indigo-100 text-indigo-700 text-xs font-semibold tracking-wide uppercase mb-4">
+        Communication Layer
+    </div>
+    <h1 class="text-4xl lg:text-5xl font-extrabold text-slate-900 tracking-tight leading-tight mb-4">REST & Search API</h1>
+    <p class="text-lg lg:text-xl text-slate-600 max-w-2xl leading-relaxed">High-performance, tenant-aware JSON endpoints powered by Gin Gonic and GORM.</p>
+</div>
+
+<!-- Mode Overview -->
+<div class="grid grid-cols-1 md:grid-cols-2 gap-8 mb-12">
+    <div class="bg-gradient-to-br from-indigo-600 to-indigo-800 p-8 rounded-[2rem] text-white shadow-xl shadow-indigo-200/50">
+        <h3 class="text-xl font-bold mb-3 flex items-center">
+            <svg class="w-6 h-6 mr-3" 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>
+            Entity-Specific CRUD
+        </h3>
+        <p class="text-indigo-100 text-sm leading-relaxed mb-6">Standard strongly-typed controllers for every entity. Includes built-in caching, MQTT eventing, and multi-tenancy.</p>
+        <div class="text-xs font-mono bg-white/10 p-3 rounded-xl border border-white/20">
+            GET /api/articles<br>
+            GET /api/articles/:id?eager=true
+        </div>
+    </div>
+    <div class="bg-gradient-to-br from-slate-800 to-slate-900 p-8 rounded-[2rem] text-white shadow-xl shadow-slate-300/50">
+        <h3 class="text-xl font-bold mb-3 flex items-center">
+            <svg class="w-6 h-6 mr-3 text-emerald-400" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
+            Generic Search RPC
+        </h3>
+        <p class="text-slate-300 text-sm leading-relaxed mb-6">A single, ultra-flexible engine mirroring PostgREST. Filter by any column using powerful operators WITHOUT writing code.</p>
+        <div class="text-xs font-mono bg-white/10 p-3 rounded-xl border border-white/20">
+            GET /api/rpc/articles?status=eq.PUBLISHED<br>
+            GET /api/rpc/articles?id=gt.100&order=id.desc
+        </div>
+    </div>
+</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-indigo-100 text-indigo-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="M4 6h16M4 12h16m-7 6h7"></path></svg>
+        </span>
+        Standard Controller Features
+    </h2>
+
+    <div class="space-y-8">
+        <!-- Relationship Loading -->
+        <div class="bg-white border border-slate-200 rounded-2xl p-6 shadow-sm">
+            <h4 class="font-bold text-slate-900 mb-3">📦 Eager vs. Lazy Loading</h4>
+            <p class="text-slate-600 text-sm mb-4 leading-relaxed">
+                By default, entities are loaded <strong>Lazily</strong> (IDs only for foreign keys). To perform a Join and fetch the full object graph, use the <code class="bg-slate-100 px-1 py-0.5 rounded text-indigo-600 font-mono">eager</code> parameter.
+            </p>
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+                <div class="bg-slate-50 p-4 rounded-xl">
+                    <span class="text-[10px] font-bold uppercase tracking-widest text-slate-400">Lazy (Default)</span>
+                    <p class="font-mono text-xs mt-2 text-slate-700">GET /api/article/1</p>
+                </div>
+                <div class="bg-emerald-50 p-4 rounded-xl">
+                    <span class="text-[10px] font-bold uppercase tracking-widest text-emerald-500">Eager (Joined)</span>
+                    <p class="font-mono text-xs mt-2 text-slate-700">GET /api/article/1?eager=true</p>
+                </div>
+            </div>
+        </div>
+
+        <!-- Pagination -->
+        <div class="bg-white border border-slate-200 rounded-2xl p-6 shadow-sm">
+            <h4 class="font-bold text-slate-900 mb-3">📏 Offset Pagination</h4>
+            <p class="text-slate-600 text-sm mb-4 leading-relaxed">
+                All collection endpoints support built-in pagination to keep your frontend lightning fast.
+            </p>
+            <table class="w-full text-xs text-left border-collapse">
+                <thead>
+                    <tr class="text-slate-400 border-b border-slate-100">
+                        <th class="py-2">Parameter</th>
+                        <th class="py-2">Description</th>
+                        <th class="py-2">Default</th>
+                    </tr>
+                </thead>
+                <tbody class="text-slate-700">
+                    <tr class="border-b border-slate-50"><td class="py-3 font-mono font-bold">page</td><td class="py-3">The index of the page to fetch</td><td class="py-3">0</td></tr>
+                    <tr class="border-b border-slate-50"><td class="py-3 font-mono font-bold">size</td><td class="py-3">Number of records per page</td><td class="py-3">20</td></tr>
+                </tbody>
+            </table>
+        </div>
+
+        <!-- Distributed Caching -->
+        <div class="bg-gradient-to-r from-blue-500 to-indigo-600 rounded-2xl p-6 text-white text-sm shadow-lg">
+            <div class="flex items-start">
+                <div class="bg-white/20 p-2 rounded-lg mr-4">
+                    <svg class="w-6 h-6" 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>
+                </div>
+                <div>
+                    <h4 class="font-bold mb-1">Distributed Redis Shield</h4>
+                    <p class="text-blue-50 leading-relaxed">
+                        Every <code class="bg-white/20 px-1 rounded">GetByID</code> request is automatically protected by a Redis cache layer. Mutations (Create/Update/Delete) trigger <strong>Automatic Cache Invalidation</strong> across the cluster, ensuring data consistency with zero effort.
+                    </p>
+                </div>
+            </div>
+        </div>
+    </div>
+</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-emerald-100 text-emerald-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="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"></path></svg>
+        </span>
+        Generic Search RPC Engine
+    </h2>
+    <p class="mb-6 text-slate-600 leading-relaxed text-sm">Accessed via <code class="bg-slate-100 px-1 py-0.5 rounded text-indigo-600 font-mono">/api/rpc/:tableName</code>, this engine provides a dynamic interface to your database.</p>
+    
+    <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mb-8 text-sm">
+        <div class="bg-slate-900 rounded-2xl p-6 text-slate-300 font-mono text-xs overflow-x-auto">
+            <span class="text-emerald-400"># Complex query example</span><br>
+            curl -X GET "http://localhost:8080/api/rpc/articles?status=eq.PUBLISHED&views=gt.500&order=views.desc&limit=5"
+        </div>
+        <div class="bg-slate-50 border border-slate-200 rounded-2xl p-6">
+            <h5 class="text-slate-900 font-bold mb-3">Supported Operators</h5>
+            <div class="grid grid-cols-2 gap-2 text-[11px] font-mono">
+                <div class="flex justify-between border-b pb-1"><span>eq</span><span class="text-indigo-600">Equals</span></div>
+                <div class="flex justify-between border-b pb-1"><span>neq</span><span class="text-indigo-600">Not Equals</span></div>
+                <div class="flex justify-between border-b pb-1"><span>gt / gte</span><span class="text-indigo-600">Greater Than</span></div>
+                <div class="flex justify-between border-b pb-1"><span>lt / lte</span><span class="text-indigo-600">Less Than</span></div>
+                <div class="flex justify-between border-b pb-1"><span>like</span><span class="text-indigo-600">Search (%)</span></div>
+                <div class="flex justify-between border-b pb-1"><span>ilike</span><span class="text-indigo-600">Case-Insensitive</span></div>
+                <div class="flex justify-between border-b pb-1"><span>in</span><span class="text-indigo-600">List (1,2,3)</span></div>
+            </div>
+        </div>
+    </div>
+</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 002 2zm10-10V7a4 4 0 00-8 0v4h8z"></path></svg>
+        </span>
+        Security & Context
+    </h2>
+    <div class="bg-rose-50 border border-rose-100 rounded-2xl p-6 flex items-start">
+        <div class="bg-rose-100 p-2 rounded-lg mr-4">
+            <svg class="w-6 h-6 text-rose-600" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"></path></svg>
+        </div>
+        <div>
+            <h4 class="font-bold text-rose-900 mb-1">Mandatory Headers</h4>
+            <p class="text-rose-700 text-sm leading-relaxed mb-4">Every Go-Duck API request must satisfy the Identity and Multi-Tenancy gatekeepers.</p>
+            <ul class="space-y-2 text-xs font-mono text-rose-800">
+                <li><span class="font-bold">Authorization:</span> Bearer &lt;Keycloak_JWT&gt;</li>
+                <li><span class="font-bold">X-Tenant-ID:</span> Subdomain or ID of the tenant dashboard</li>
+            </ul>
+        </div>
+    </div>
+</section>

package/templates/docs/pages/security.hbs

@@ -0,0 +1,31 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Security & Resilience</h1>
+<p class="text-lg text-gray-600 mb-8">Out-of-the-box infrastructure protecting your core microservices.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. Identity & Access Management (OIDC)</h2>
+    <p class="mb-4">GO-DUCK generated apps utilize strict Keycloak JWT Authorization. No entity router functions without traversing the <code>jwtAuthMiddleware</code> and extracting structural properties of the connected user from the signed payload utilizing the pre-configured realm secret.</p>
+    
+    <div class="bg-indigo-50 border-l-4 border-indigo-500 p-4 mb-6 rounded-r">
+        <p class="text-indigo-900"><strong>Golden Rule:</strong> In <code>application-dev.yml</code>, ensure your Keycloak Realm, ClientID, and Secret are accurately synced with the local running Docker Keycloak image.</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">2. Burst Protection (Rate Limiting)</h3>
+    <p class="mb-4">Using the standard <code>x/time/rate</code> package, a Token Bucket rate limiter is attached to the Gin Engine globally to mitigate DDOS vectors and abusive scripting.</p>
+    <pre><code class="language-yaml"># Inside your application-prod.yml
+go-duck:
+  security:
+    rate-limit:
+      rps: 150.0  # Allow up to 150 Req/Sec
+      burst: 300  # Burstable tokens
+</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">3. Sony/go-breaker (Circuit Breakers)</h2>
+    <p class="mb-4">When a Microservice starts rejecting requests globally due to a failing dependent macro-service (e.g. Redis node goes down / DB locks / MQTT broker drops), your application handles this gracefully by "tripping" an open Circuit Breaker to prevent Request Queue Pile-ups.</p>
+    
+    <pre><code class="language-go">resilience.Execute(func() (interface{}, error) {
+    // Risky Network / DB Operations wrapped automatically!
+    return s.repo.DB.First(&entity, req.Id).Error
+})</code></pre>
+</section>