go-duck-cli 1.0.0

package/parser/gdl.js

@@ -0,0 +1,162 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * GO-DUCK GDL Parser
+ *
+ * Supported field syntax:
+ *   fieldName  Type  [required]  [unique]  [text]
+ *
+ * Supported types:
+ *   String, Text, Integer, Long, Float, BigDecimal, Boolean, LocalDate, Instant, JSON, JSONB
+ *
+ * Type overrides in GDL:
+ *   - `Text` maps to TEXT in DB and string in Go
+ *   - `String(512)` maps to VARCHAR(512) in DB
+ *
+ * Examples:
+ *   email    String  required  unique
+ *   bio      Text
+ *   name     String  required
+ */
+
+export const parseGDL = async (filePath) => {
+    const content = await fs.readFile(filePath, 'utf8');
+    const entities = [];
+    const relationships = [];
+    const enums = [];
+
+    // Parse enum blocks
+    const enumRegex = /enum\s+(\w+)\s*\{([\s\S]*?)\}/g;
+    let match;
+    while ((match = enumRegex.exec(content)) !== null) {
+        const name = match[1];
+        const values = match[2].split(',').map(v => v.trim().replace(/['"]/g, '')).filter(v => v.length > 0);
+        enums.push({ name, values });
+    }
+
+    // Parse entity blocks
+    const entityRegex = /(@\w+\s+)?entity\s+(\w+)\s*\{([\s\S]*?)\}/g;
+    while ((match = entityRegex.exec(content)) !== null) {
+        const annotation = match[1]?.trim();
+        const name = match[2];
+        const fieldBlock = match[3];
+
+        if (name === 'relationship' || name === 'enum') continue;
+
+        const fields = [];
+        const fieldLines = fieldBlock.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+
+        for (const line of fieldLines) {
+            const parts = line.split(/\s+/);
+            if (parts.length < 2) continue;
+
+            const fieldName = parts[0];
+            let rawType = parts[1];
+
+            // Support String(N) for custom VARCHAR sizes
+            let varcharSize = 255;
+            const sizeMatch = rawType.match(/^String\((\d+)\)$/);
+            if (sizeMatch) {
+                varcharSize = parseInt(sizeMatch[1], 10);
+                rawType = 'String';
+            }
+
+            const required = line.includes('required');
+            const unique = line.includes('unique');
+            const isText = rawType === 'Text';
+
+            // Check if type is an Enum
+            const isEnum = enums.some(e => e.name === rawType);
+
+            fields.push({
+                name: fieldName,
+                type: isText ? 'Text' : rawType,
+                required,
+                unique,
+                isEnum,
+                varcharSize: rawType === 'String' ? varcharSize : null,
+            });
+        }
+
+        entities.push({ name, annotation, fields });
+    }
+
+    // Parse relationship blocks
+    const relRegex = /relationship\s+(\w+)\s*\{([\s\S]*?)\n\}/g;
+    while ((match = relRegex.exec(content)) !== null) {
+        const type = match[1];
+        const relBlock = match[2];
+        const relLines = relBlock.split('\n').map(l => l.trim()).filter(l => l.length > 0);
+
+        for (const line of relLines) {
+            const relParts = line.split(/\s+to\s+/);
+            if (relParts.length !== 2) continue;
+
+            const parseRelPart = (p) => {
+                const m = p.match(/(\w+)\s*\{\s*(\w+)\s*\}/);
+                return m ? { entity: m[1], field: m[2] } : null;
+            };
+
+            // Support required FK: "required" keyword anywhere in the line
+            const fkRequired = line.includes('required');
+
+            const from = parseRelPart(relParts[0]);
+            const to = parseRelPart(relParts[1]);
+
+            if (from && to) {
+                relationships.push({ type, from, to, required: fkRequired });
+            }
+        }
+    }
+
+    return { entities, relationships, enums };
+};
+
+/**
+ * Maps GDL type to Go type
+ */
+export const toGoType = (type, enums = []) => {
+    const isEnum = enums.some(e => e.name === type);
+    if (isEnum) return type;
+
+    const map = {
+        String: 'string',
+        Text: 'string',
+        Integer: 'int',
+        Long: 'int64',
+        Float: 'float64',
+        BigDecimal: 'float64',
+        Boolean: 'bool',
+        LocalDate: 'time.Time',
+        Instant: 'time.Time',
+        JSON: 'datatypes.JSON',
+        JSONB: 'datatypes.JSON',
+    };
+    return map[type] || 'interface{}';
+};
+
+/**
+ * Maps GDL type to Liquibase/SQL type
+ */
+export const toLiquibaseType = (field, enums = []) => {
+    if (field.type === 'Text') return 'TEXT';
+    if (field.type === 'String' && field.varcharSize) return `VARCHAR(${field.varcharSize})`;
+    
+    // Enums are stored as VARCHAR with a check constraint or just as strings
+    if (field.isEnum) return 'VARCHAR(50)';
+
+    const map = {
+        String: 'VARCHAR(255)',
+        Integer: 'INT',
+        Long: 'BIGINT',
+        Float: 'DECIMAL',
+        BigDecimal: 'DECIMAL',
+        Boolean: 'BOOLEAN',
+        LocalDate: 'DATE',
+        Instant: 'TIMESTAMP',
+        JSON: 'JSON',
+        JSONB: 'JSONB',
+    };
+    return map[field.type] || 'VARCHAR(255)';
+};

package/templates/application.yml.hbs

@@ -0,0 +1,18 @@
+spring:
+  profiles:
+    active: @spring.profiles.active@
+  datasource:
+    url: jdbc:postgresql://localhost:5432/{{name}}
+    username: {{security.keycloak-client-id}}
+    password: {{security.keycloak-secret}}
+    driver-class-name: org.postgresql.Driver
+
+keycloak:
+  auth-server-url: {{security.keycloak-host}}
+  realm: {{security.keycloak-realm}}
+  resource: {{security.keycloak-client-id}}
+  credentials:
+    secret: {{security.keycloak-secret}}
+
+multitenancy:
+  enabled: {{multitenancy.enabled}}

package/templates/docs/index.html.hbs

@@ -0,0 +1,226 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{appName}} - Developer Guide</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/atom-one-dark.min.css">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+    <script>hljs.highlightAll();</script>
+    <style>
+        html { scroll-behavior: smooth; }
+        .sidebar { height: calc(100vh - 4rem); }
+        .content-section { margin-bottom: 4rem; padding-top: 4rem; margin-top: -4rem; }
+    </style>
+</head>
+<body class="bg-gray-50 text-gray-800 font-sans antialiased">
+    <!-- Navbar -->
+    <nav class="bg-indigo-600 text-white shadow-lg fixed w-full z-10 top-0 h-16 flex items-center px-6">
+        <div class="text-xl font-bold">{{appName}} <span class="text-indigo-200 text-sm font-normal">Developer Guide</span></div>
+    </nav>
+
+    <div class="flex max-w-8xl mx-auto pt-16">
+        <!-- Sidebar -->
+        <aside class="w-64 fixed sidebar overflow-y-auto bg-white border-r border-gray-200 p-6 hidden md:block">
+            <h3 class="font-bold text-gray-400 uppercase text-xs tracking-wider mb-4">Table of Contents</h3>
+            <ul class="space-y-2">
+                <li><a href="#quick-start" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors">Quick Start</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">1. Core & Generic Layers</span></li>
+                <li><a href="#rest-api" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">REST APIs & Search</a></li>
+                <li><a href="#audit-metering" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">Audit & Metering</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">2. Real-Time & Kratos</span></li>
+                <li><a href="#websockets" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">WebSockets (REST-over-WS)</a></li>
+                <li><a href="#mqtt" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">MQTT Event Streaming</a></li>
+                <li><a href="#grpc-kratos" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">Kratos gRPC APIs</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">3. GraphQL</span></li>
+                <li><a href="#graphql" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">GraphQL Integration</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">4. Resilience & Security</span></li>
+                <li><a href="#resilience-cache" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">Caching & Circuit Breakers</a></li>
+                <li><a href="#security" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">Keycloak OIDC & Multi-tenancy</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">5. Observability</span></li>
+                <li><a href="#observability" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">OTel & Datadog</a></li>
+                <li class="pt-2 pb-1"><span class="font-semibold text-gray-800">6. Migrations</span></li>
+                <li><a href="#liquibase" class="text-gray-600 hover:text-indigo-600 hover:font-medium transition-colors pl-4 block">Liquibase & GDL</a></li>
+            </ul>
+        </aside>
+
+        <!-- Main Content -->
+        <main class="flex-1 md:ml-64 p-8 lg:p-12 max-w-5xl">
+            <h1 class="text-4xl font-extrabold text-gray-900 mb-4">{{appName}} API & Integration Guide</h1>
+            <p class="text-lg text-gray-600 mb-8">Welcome to the developer documentation for your GO-DUCK generated microservice. This guide covers how to connect, authenticate, and integrate with all the implemented features (The 200% Milestone).</p>
+
+            <!-- Quick Start -->
+            <section id="quick-start" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Quick Start</h2>
+                <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> Most APIs are secured by Keycloak JWT. You will need a valid token to access them.</p>
+                </div>
+                <h3 class="font-semibold mb-2">Running the application:</h3>
+                <pre><code class="language-bash"># Start local infrastructure (DB, Redis, MQTT, Keycloak, Jaeger/OTel)
+docker-compose up -d
+
+# Run the Go app (starts on port 8080 by default)
+go run main.go</code></pre>
+            </section>
+
+            <!-- REST & Search -->
+            <section id="rest-api" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">1. REST APIs & Generic Search</h2>
+                <p class="mb-4">The application provides standard RESTful CRUD endpoints for all generated entities (e.g., {{#if entities.length}}{{entities.[0].name}}{{else}}Entity{{/if}}).</p>
+                
+                <h3 class="font-semibold mb-2">Standard CRUD:</h3>
+                <pre><code class="language-http">GET /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}?page=1&pageSize=10
+POST /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}
+PUT /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}/:id
+DELETE /api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}/:id</code></pre>
+
+                <h3 class="font-semibold mb-2 mt-6">PostgREST-like Generic Search:</h3>
+                <p class="mb-2">We expose a dynamic search endpoint allowing powerful querying directly from the frontend.</p>
+                <pre><code class="language-bash">curl -X GET "http://localhost:8080/api/rpc/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}your_table{{/if}}?name=eq.John&age=gt.18" \
+  -H "Authorization: Bearer YOUR_JWT" \
+  -H "X-Tenant-ID: tenant_1"</code></pre>
+                <p class="text-sm text-gray-500 mt-2">Supported operators: <code>eq, neq, gt, gte, lt, lte, like, ilike</code></p>
+            </section>
+
+            <!-- Audit & Metering -->
+            <section id="audit-metering" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Audit & Metering</h2>
+                <p class="mb-4">Entity mutations are automatically tracked via the <code>AuditMiddleware</code>. Usage limits per-tenant can be managed via the Metering API.</p>
+                <pre><code class="language-bash"># View Audit Logs
+curl -X GET http://localhost:8080/api/audit -H "Authorization: Bearer YOUR_JWT"
+
+# View Usage for Current Tenant
+curl -X GET http://localhost:8080/api/metering/usage -H "Authorization: Bearer YOUR_JWT" -H "X-Tenant-ID: my_tenant"</code></pre>
+            </section>
+
+            <!-- WebSockets -->
+            <section id="websockets" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">2. WebSockets (REST-over-WS)</h2>
+                <p class="mb-4">A high-performance WebSocket dispatcher is available at <code>/ws</code>. It supports JWT authentication during connection and requires HMAC-SHA256 signatures for message integrity.</p>
+                
+                <h3 class="font-semibold mb-2">Connecting via JS:</h3>
+                <pre><code class="language-javascript">const token = 'YOUR_JWT_TOKEN';
+// Pass token as query param for auth
+const ws = new WebSocket(`ws://localhost:8080/ws?token=${token}`);
+
+ws.onopen = () => {
+  // Sending a signed Traced Envelope
+  ws.send(JSON.stringify({
+    TraceID: "trace-123",
+    Method: "GET",
+    Path: "/api/{{#if entities.length}}{{toLowerCase entities.[0].name}}s{{else}}entities{{/if}}",
+    Payload: "{}",
+    Signature: "hmac_sha256_hash_of_payload" // Verified on server
+  }));
+};
+
+ws.onmessage = (event) => console.log("Received:", event.data);</code></pre>
+            </section>
+
+            <!-- MQTT -->
+            <section id="mqtt" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">MQTT Event Streaming</h2>
+                <p class="mb-4">Successful CRUD operations (Create, Update, Delete) are published as JSON payloads to the MQTT broker. This is perfect for webhooks, async processing, or triggering other microservices.</p>
+                <pre><code class="language-bash"># Using mosquitto_sub to listen to events
+mosquitto_sub -h localhost -p 1883 -t "go-duck/events/#" -u dev_user -P dev_password</code></pre>
+                <p class="text-sm mt-2">Example topic: <code>go-duck/events/{{#if entities.length}}{{toLowerCase entities.[0].name}}{{else}}entity{{/if}}/CREATE</code></p>
+            </section>
+
+            <!-- Kratos gRPC -->
+            <section id="grpc-kratos" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Kratos Secured gRPC APIs</h2>
+                <p class="mb-4">The application runs a Kratos gRPC server on <code>port 9000</code> by default, sharing the internal repository with Gin. It validates Keycloak JWTs via Kratos middleware.</p>
+                <h3 class="font-semibold mb-2">Calling the gRPC Service (Go Client Example):</h3>
+                <pre><code class="language-go">import (
+    "context"
+    "google.golang.org/grpc"
+    "golang.org/x/oauth2"
+    "google.golang.org/grpc/credentials/oauth"
+    pb "{{appName}}/api/v1"
+)
+
+// The JWT must be generated using the Keycloak secret configured in the app
+token := oauth.TokenSource{TokenSource: oauth2.StaticTokenSource(&oauth2.Token{AccessToken: "YOUR_JWT"})}
+
+conn, err := grpc.Dial("localhost:9000", grpc.WithInsecure(), grpc.WithPerRPCCredentials(token))
+client := pb.New{{#if entities.length}}{{capitalize entities.[0].name}}{{else}}Entity{{/if}}ServiceClient(conn)
+
+// Execute Call
+res, err := client.Get{{#if entities.length}}{{capitalize entities.[0].name}}{{else}}Entity{{/if}}(context.Background(), &pb.Get{{#if entities.length}}{{capitalize entities.[0].name}}{{else}}Entity{{/if}}Request{Id: 1})
+</code></pre>
+            </section>
+
+            <!-- GraphQL -->
+            <section id="graphql" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">3. GraphQL Integration</h2>
+                <p class="mb-4">A single unified GraphQL endpoint is available at <code>POST /graphql</code>. It integrates with GORM for efficient queries.</p>
+                <h3 class="font-semibold mb-2">Example Query:</h3>
+                <pre><code class="language-graphql">query {
+  get{{#if entities.length}}{{capitalize entities.[0].name}}{{else}}Entity{{/if}}(id: 1) {
+    id
+    {{#if entities.length}}
+      {{#if entities.[0].fields.length}}
+        {{entities.[0].fields.[0].name}}
+      {{/if}}
+    {{/if}}
+  }
+}</code></pre>
+                <h3 class="font-semibold mb-2 mt-4">Example Request via Fetch:</h3>
+                <pre><code class="language-javascript">fetch('http://localhost:8080/graphql', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query: 'query { list{{#if entities.length}}{{capitalize entities.[0].name}}s{{else}}Entities{{/if}} { id } }' })
+}).then(res => res.json()).then(console.log);</code></pre>
+            </section>
+
+            <!-- Caching & Circuit Breakers -->
+            <section id="resilience-cache" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">4. Resilience & Caching</h2>
+                <h3 class="font-semibold mb-2">Distributed Redis Caching</h3>
+                <p class="mb-4">The application uses Cache-Aside logic built on top of Redis. The <code>cache.GetOrSet</code> function handles tenant-prefixed caching to prevent data spillage between tenants.</p>
+                
+                <h3 class="font-semibold mb-2">Circuit Breakers (Sony/Gobreaker)</h3>
+                <p class="mb-4">Failing network calls (like to the Database or Redis) are wrapped in Circuit Breakers. If the failure threshold is crossed, the circuit "opens" and immediately fails fast to prevent cascading failures.</p>
+            </section>
+
+            <!-- Security & Multi-tenancy -->
+            <section id="security" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Security, OIDC & Multi-tenancy</h2>
+                <p class="mb-4">All `/api` endpoints are protected by <code>JWTMiddleware</code>.</p>
+                <ul class="list-disc pl-6 space-y-2 mb-4">
+                    <li>Tokens are verified against the Keycloak Secret (defined in <code>application.yml</code>).</li>
+                    <li><code>TenantMiddleware</code> reads the <code>X-Tenant-ID</code> header and dynamically routes the GORM connection to the tenant's specific database schema (if Multi-tenancy is fully implemented) or injects the Tenant ID into the request context.</li>
+                    <li>Rate Limiting protects burst traffic (configurable in YAML).</li>
+                </ul>
+            </section>
+
+            <!-- Observability -->
+            <section id="observability" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">5. Observability (OTel & Datadog)</h2>
+                <p class="mb-4">The application uses OpenTelemetry for full-stack tracing (HTTP -> Gin Controller -> GORM DB Plugin -> PostgREST search).</p>
+                <ul class="list-disc pl-6 space-y-2 mb-4">
+                    <li>Traces are exported over gRPC to the local <code>otel-collector</code> on port <code>4317</code>.</li>
+                    <li>You can visualize these traces locally via Jaeger (<code>http://localhost:16686</code>).</li>
+                    <li>Datadog logging is implemented in the <code>logger</code> package and can be enabled via <code>application-prod.yml</code>.</li>
+                </ul>
+            </section>
+
+            <!-- Liquibase & GDL -->
+            <section id="liquibase" class="content-section">
+                <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">6. Advanced Migrations & GDL</h2>
+                <p class="mb-4">Running <code>go-duck import-gdl</code> calculates stateful differences using the `.go-duck/` snapshot folder. It generates atomic, timestamped Liquibase XML changelogs in <code>migrations/liquibase/changelogs/</code>.</p>
+                <ul class="list-disc pl-6 space-y-2">
+                    <li>The application auto-generates <code>master.xml</code> dynamically without "ghost" references.</li>
+                    <li>Includes smart nullability and automatic indexing for Foreign Keys.</li>
+                    <li><strong>Needle Support:</strong> We inject `// go-duck-needle-*` markers in <code>main.go</code> and <code>grpc.go</code> for safe evolutionary code additions without destroying manual updates.</li>
+                </ul>
+            </section>
+
+            <footer class="mt-12 pt-6 border-t border-gray-200 text-center text-gray-500 text-sm pb-12">
+                Generated with ❤️ by GO-DUCK CLI
+            </footer>
+        </main>
+    </div>
+</body>
+</html>

package/templates/docs/layout.hbs

@@ -0,0 +1,106 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{appName}} - {{title}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet">
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/vs2015.min.css">
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
+    <script>
+        tailwind.config = {
+            theme: {
+                extend: {
+                    fontFamily: { sans: ['Inter', 'sans-serif'] },
+                }
+            }
+        }
+    </script>
+    <script>hljs.highlightAll();</script>
+    <style>
+        .gradient-text { background: linear-gradient(90deg, #818cf8, #c084fc); -webkit-background-clip: text; -webkit-text-fill-color: transparent; }
+        ::-webkit-scrollbar { width: 6px; }
+        ::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 4px; }
+    </style>
+</head>
+<body class="bg-slate-50 text-slate-800 font-sans antialiased selection:bg-indigo-300 selection:text-indigo-900">
+    <!-- Navbar -->
+    <nav class="bg-slate-900/95 backdrop-blur-md shadow-lg fixed w-full z-30 top-0 h-16 flex items-center px-6 border-b border-slate-800">
+        <div class="flex items-center">
+            <img src="logo.png" alt="GO-DUCK Logo" class="h-10 w-auto mr-4 rounded-lg shadow-sm">
+            <div class="text-xl font-bold text-white tracking-tight">GO-DUCK <span class="text-indigo-300 text-xs font-semibold ml-2 inline-flex items-center px-2 py-0.5 rounded-full bg-indigo-500/20 border border-indigo-500/30 uppercase tracking-wider hidden sm:inline-flex">Developer Guide</span></div>
+        </div>
+    </nav>
+
+    <div class="flex max-w-[90rem] mx-auto pt-16">
+        <!-- Sidebar -->
+        <aside class="w-72 fixed h-[calc(100vh-4rem)] overflow-y-auto bg-slate-50 border-r border-slate-200 p-6 hidden lg:block scroll-smooth">
+            <h3 class="font-bold text-slate-400 uppercase text-[10px] tracking-widest mb-4 flex items-center">
+                <svg class="w-3 h-3 mr-1.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h7"></path></svg>
+                Table of Contents
+            </h3>
+            <ul class="space-y-1 text-sm font-medium text-slate-600">
+                <li><a href="index.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'index')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Home & Quick Start</a></li>
+                
+                <li class="pt-5 pb-1 px-3"><span class="font-bold text-slate-900 uppercase text-[10px] tracking-widest">1. Core Concepts</span></li>
+                <li><a href="gdl.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'gdl')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">GDL & Framework</a></li>
+                <li><a href="cli.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'cli')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">CLI & Code Injection</a></li>
+                
+                <li class="pt-5 pb-1 px-3"><span class="font-bold text-slate-900 uppercase text-[10px] tracking-widest">2. API Endpoints</span></li>
+                <li><a href="rest.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'rest')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">REST & Generic Search</a></li>
+                <li><a href="graphql.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'graphql')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">GraphQL Integration</a></li>
+                <li><a href="grpc.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'grpc')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Secured gRPC (Kratos)</a></li>
+                
+                <li class="pt-5 pb-1 px-3"><span class="font-bold text-slate-900 uppercase text-[10px] tracking-widest">3. Real-Time & Audit</span></li>
+                <li><a href="realtime.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'realtime')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">WebSockets & MQTT</a></li>
+                <li><a href="audit.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'audit')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Audit & Metering</a></li>
+                
+                <li class="pt-5 pb-1 px-3"><span class="font-bold text-slate-900 uppercase text-[10px] tracking-widest">4. Infrastructure</span></li>
+                <li><a href="security.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'security')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Security & Resilience</a></li>
+                <li><a href="observability.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'observability')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Observability</a></li>
+                
+                <li class="pt-5 pb-1 px-3"><span class="font-bold text-slate-900 uppercase text-[10px] tracking-widest">5. References</span></li>
+                <li><a href="integrations.html" class="flex items-center px-3 py-2 rounded-lg transition-all duration-200 {{#if (eq activePage 'integrations')}}bg-white shadow-sm ring-1 ring-slate-200 text-indigo-700{{else}}hover:bg-slate-200/50 hover:text-slate-900{{/if}}">Client Integrations</a></li>
+            </ul>
+        </aside>
+
+        <main class="flex-1 lg:ml-72 p-6 md:p-10 max-w-4xl xl:max-w-5xl">
+            <!-- White Content Card -->
+            <div class="bg-white rounded-2xl shadow-sm border border-slate-200 p-8 md:p-12 mb-10 relative overflow-hidden">
+                <!-- Background Decoration -->
+                <div class="absolute top-0 right-0 w-64 h-64 bg-slate-50 rounded-bl-full -z-0"></div>
+                
+                <!-- Content injected here (raised z-index) -->
+                <div class="relative z-10">
+                    {{{body}}}
+                </div>
+            </div>
+            
+            <footer class="mt-8 text-center text-slate-400 text-sm mb-8 flex justify-center items-center space-x-2">
+                <span>Generated with</span>
+                <span class="text-lg">🦆</span>
+                <span>by <strong>GO-DUCK CLI</strong></span>
+            </footer>
+        </main>
+    </div>
+    <!-- Lightbox Overlay -->
+    <div id="lightbox" class="fixed inset-0 bg-slate-900/90 backdrop-blur-sm z-[100] hidden flex items-center justify-center p-4 md:p-10 cursor-zoom-out" onclick="this.classList.add('hidden')">
+        <div class="relative max-w-5xl w-full h-full flex items-center justify-center">
+            <img id="lightbox-img" src="" alt="Enlarged View" class="max-w-full max-h-full object-contain rounded-xl shadow-2xl transition-all duration-300">
+            <button class="absolute top-0 right-0 m-4 text-white hover:text-indigo-300 transition-colors">
+                <svg class="w-8 h-8" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12"></path></svg>
+            </button>
+        </div>
+    </div>
+
+    <script>
+        function openLightbox(src) {
+            const lb = document.getElementById('lightbox');
+            const img = document.getElementById('lightbox-img');
+            img.src = src;
+            lb.classList.remove('hidden');
+        }
+    </script>
+</body>
+</html>

package/templates/docs/pages/audit.hbs

@@ -0,0 +1,39 @@
+<h1 class="text-4xl font-extrabold text-gray-900 mb-4">Audit Trails & Tenant Metering</h1>
+<p class="text-lg text-gray-600 mb-8">Maintain strict compliance and automatically track API consumption rates for multi-tenant applications.</p>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">The `@Audited` Engine (Dual Layer)</h2>
+    <p class="mb-4">By tagging an entity with <code>@Audited</code> inside your <code>GDL</code> file, GO-DUCK injects an advanced two-tier auditing strategy automatically into your microservice.</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> All Audit Logs are automatically driven completely via Keycloak JWT Token Extraction!</p>
+    </div>
+
+    <h3 class="font-semibold mb-2 mt-6">Layer 1: Inline Entity Columns</h3>
+    <p class="mb-4 text-gray-700">Instead of generic <code>created_at</code> and <code>updated_at</code> timestamps, an <code>@Audited</code> object inherently gains these columns directly on the database row:</p>
+    <ul class="list-disc pl-6 space-y-2 mb-4 text-gray-700 font-mono text-sm bg-gray-100 p-4 rounded">
+        <li>created_by (String - e.g., "John Doe")</li>
+        <li>created_date (TIMESTAMP)</li>
+        <li>last_modified_by (String - e.g., "Jane Doe")</li>
+        <li>last_modified_date (TIMESTAMP)</li>
+        <li>last_modified_user_id (String - Global Auth Provider UUID)</li>
+    </ul>
+
+    <h3 class="font-semibold mb-2 mt-8">Layer 2: The Central `audit_log` Tracker Table</h3>
+    <p class="mb-4 text-gray-700">A global <code>audit_log</code> timeline is maintained across your database. For every mutable Action (CREATE, UPDATE, DELETE), the middleware diffs the pre-mutation HTTP object and the post-mutation object. It stores the explicit JSON payload changes asynchronously!</p>
+    <pre><code class="language-bash"># Quickly view all changes securely over REST 
+curl -X GET "http://localhost:8080/api/audit?entityName={{capitalize (defaultStr (lookup entities "0.name") "Entity")}}" \
+  -H "Authorization: Bearer YOUR_JWT"
+</code></pre>
+</section>
+
+<section class="mb-10">
+    <h2 class="text-2xl font-bold text-gray-800 mb-4 border-b pb-2">Multi-Tenant Metering</h2>
+    <p class="mb-4">API consumption tracking is inherently built in. When fully enabled, this records usage hits explicitly tracked against the <code>X-Tenant-ID</code> attached to the requests over time. This metric is ideal for setting up a usage-based billing logic or preventing internal abuse.</p>
+    
+    <pre><code class="language-bash"># The Tenant retrieves their own API request footprints:
+curl -X GET "http://localhost:8080/api/metering/usage" \
+  -H "Authorization: Bearer YOUR_JWT" \
+  -H "X-Tenant-ID: tenant_B_stripe"
+</code></pre>
+</section>