@seip/blue-bird 0.7.0 → 0.7.2

package/.env_example

@@ -3,18 +3,23 @@ DEBUG=true
 PORT=3000
 HOST="localhost"
 APP_URL="http://localhost"
-STATIC_PATH="frontend/public"
 VERSION="1.0.0"
-BLUEBIRD_PROJECT_NAME="bluebird"
 
-#Docker /Swagger config
+# Docker / Swagger Config
 TITLE="Blue-Bird"
 DESCRIPTION="Description project"
 
-
 # Security Configuration
 JWT_SECRET="JWT_SECRET"
 
+# Redis Configuration
+REDIS_HOST="localhost"
+REDIS_PORT=6379
+REDIS_PASSWORD=""
+
+# PM2 Clustering Instances (integer or 'max')
+PM2_INSTANCES=1
+
 # Database Configuration (Used only for local development outside Docker)
 # SQLite (Default)
 DATABASE_URL="file:./dev.db"

package/AGENTS.md

@@ -131,7 +131,7 @@ router.post("/logout", async (req, res) => {
 
 ## 6. Performance Caching (Cache)
 
-If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON payload.
+If an Express route involves heavy processing or database queries, utilize the `Cache` middleware to cache the REST API JSON or HTML payload.
 
 ```javascript
 import Cache from "@seip/blue-bird/core/cache.js";
@@ -141,6 +141,8 @@ router.get("/stats", Cache.middleware(60), (req, res) => {
 });
 ```
 
+The Cache module integrates with Redis when `REDIS_HOST` is configured in the environment. If Redis is unavailable or fails, it transparently falls back to an in-memory cache system without interrupting requests.
+
 ## 7. Security (Helmet)
 
 Helmet is **not applied globally** by default. Apply it per-router where needed:
@@ -156,19 +158,29 @@ apiRouter.use(App.helmet());
 
 Blue Bird features a built-in Docker Compose CLI wrapper to deploy and manage containerized development databases and production stacks.
 
+Production deployments always use Docker for orchestration, running:
+- Nginx: Serves static files directly from `frontend/dist/client/` and blocks common scanner requests (`.env`, `.git`, etc.) with fallback to Express.
+- Node.js App: Managed via PM2 in cluster mode using `PM2_INSTANCES` configuration (defaults to `1`, can be set to `max`).
+- MySQL: Database service.
+- Redis: Memory caching and session store.
+
 ```bash
 # Manage containers using blue-bird CLI
-npx blue-bird docker start          # Starts production app + mysql database
+npx blue-bird docker start          # Starts production app stack (mysql, redis, app, nginx)
 npx blue-bird docker start mysql    # Starts MySQL container only (useful for local development)
+npx blue-bird docker start redis    # Starts Redis container only
+npx blue-bird docker start dbs      # Starts both database containers (MySQL + Redis)
 npx blue-bird docker stop           # Stops all running containers
 npx blue-bird docker build          # Builds/rebuilds application image
 npx blue-bird docker ps             # Shows status of active containers
 npx blue-bird docker logs           # Tails Node.js app container logs
+npx blue-bird docker pm2 [args]     # Runs PM2 commands inside the app container (e.g. status, monit)
 npx blue-bird docker mysql          # Runs interactive MySQL client terminal inside the container
+npx blue-bird docker redis          # Runs interactive Redis client terminal inside the container
 npx blue-bird docker prune          # Cleans unused volumes, dangling images, and BuildKit caches
 ```
 
-The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts.
+The container names and virtual networks are namespaced by the `TITLE` environment variable parsed from `.env` to prevent resource collisions on VPS hosts. Alternatively, PM2 and other services can be run manually in standalone server environments.
 
 ## 9. AI Development Guidelines
 
@@ -177,4 +189,21 @@ The container names and virtual networks are namespaced by the `TITLE` environme
 3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
 4. **No inline comments**: Only use JSDoc for documentation.
 
+## 10. Database Module (database.js)
+
+Blue Bird provides a unified wrapper class for MySQL databases via `mysql2` connections pool with automatic retries and built-in query caching:
+
+```javascript
+import connection from "@seip/blue-bird/core/database.js";
+
+// Basic SELECT query returning single row
+const user = await connection.query("SELECT * FROM users WHERE id = ?", [1], "return_row");
+
+// Query caching in Redis (stores results in Redis for 60 seconds)
+const stats = await connection.query("SELECT COUNT(*) as cnt FROM logs", [], { cache: 60 });
+
+// INSERT query returns insertId directly
+const newUserId = await connection.query("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+```
+
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -62,8 +62,8 @@ project/
 │   │       ├── index.astro
 │   │       └── about.astro
 │   ├── public/              # Static assets mapped to root of Astro build
-│   │   └── js/
-│   │       └── tailwind.js  # Local Tailwind compiler
+│   │   └── css/
+│   │       └── app.css      # Css files
 │   └── astro.config.mjs     # Astro configuration file
 ├── docker/
 │   └── Dockerfile           # Optimized production build file
@@ -122,8 +122,8 @@ const app = new App({
     serverEntry: "./frontend/dist/server/entry.mjs", // Path to compiled Astro server entrypoint
     client: false, // Set to true to serve static files from client build
     clientDir: "./frontend/dist/client", // Path to Astro client static assets
-    base: "/" // Mount base path
-  }
+    base: "/", // Mount base path
+  },
 });
 ```
 
@@ -201,6 +201,8 @@ router.get("/stats", Cache.middleware(60), (req, res) => {
 });
 ```
 
+Integrates with Redis if `REDIS_HOST` is defined in the environment. Falls back to an in-memory cache automatically if Redis is not configured or not running.
+
 ---
 
 ### 6. Security Headers (`Helmet`)
@@ -216,6 +218,25 @@ webRouter.use(App.helmet());
 
 ---
 
+### 7. Database wrapper (`Database`)
+
+MySQL database client connection pool configuration featuring automated retry loops, query formatting utilities, and Redis query caching.
+
+```javascript
+import connection from "@seip/blue-bird/core/database.js";
+
+// Fetch single row from a SELECT query
+const user = await connection.query("SELECT * FROM users WHERE email = ?", ["test@example.com"], "return_row");
+
+// Fetch rows with 60 seconds Redis caching enabled
+const stats = await connection.query("SELECT COUNT(*) as count FROM access_logs", [], { cache: 60 });
+
+// INSERT queries return the last insert ID directly
+const newId = await connection.query("INSERT INTO users (name) VALUES (?)", ["John"]);
+```
+
+---
+
 ## 🐳 Docker CLI Workflow
 
 Blue Bird comes with a built-in Docker CLI wrapper that handles both local development database bootstrapping and full-stack VPS production deployments.
@@ -228,13 +249,17 @@ npx blue-bird docker <command> [options]
 
 ### Supported Actions:
 
-- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + MySQL).
+- **`npx blue-bird docker start`**: Boots the production stack (Node.js App + Nginx + MySQL + Redis).
 - **`npx blue-bird docker start mysql`**: Boots the MySQL container only (great for local HTTP development).
+- **`npx blue-bird docker start redis`**: Boots the Redis container only.
+- **`npx blue-bird docker start dbs`**: Boots both database containers (MySQL + Redis).
 - **`npx blue-bird docker stop`**: Stops all active containers.
 - **`npx blue-bird docker build [--no-cache]`**: Builds or updates the Node.js production image.
 - **`npx blue-bird docker ps`**: Lists running project containers and ports.
 - **`npx blue-bird docker logs [app|mysql]`**: Tails logs for the specified container.
+- **`npx blue-bird docker pm2 [args]`**: Runs PM2 commands inside the Node.js application container (e.g. `status`, `monit`, `reload all`).
 - **`npx blue-bird docker db`**: Connects into the container's interactive MySQL shell using credentials from `.env`.
+- **`npx blue-bird docker redis`**: Connects into the container's interactive Redis CLI terminal.
 - **`npx blue-bird docker prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 
 ---
@@ -243,9 +268,16 @@ npx blue-bird docker <command> [options]
 
 You can deploy Blue Bird applications to production using two main workflows:
 
-### A. Docker Container Stack (Recommended)
+### A. Docker Container Stack (Highly Recommended)
+
+Using the built-in Docker stack is the recommended deployment method because it sets up a complete, hardened production environment automatically:
+- **Nginx Reverse Proxy:** Captures traffic on port 3000 (or custom PORT), serves Astro client-side assets directly from the filesystem to offload the Node.js server, and proxies the rest to Express.
+- **PM2 Clustering:** Launches Node.js in cluster mode inside the container, utilizing all available CPU cores based on `PM2_INSTANCES` configuration (defaulting to 1).
+- **Security Mitigation:** Nginx blocks common malicious scanners (e.g. `/.env`, `/.git`, `/wp-admin`) instantly using a 444 status code and implements a `10r/s` request rate-limit.
+- **Services Stack:** MySQL and Redis are configured in the same bridge network automatically.
 
-1. Configure `.env` with production keys,DEBUG=false and your custom `TITLE`.
+To deploy via Docker:
+1. Configure `.env` with production keys, `DEBUG=false` and your custom `TITLE`.
 2. Build the production image:
    ```bash
    npx blue-bird docker build
@@ -255,9 +287,9 @@ You can deploy Blue Bird applications to production using two main workflows:
    npx blue-bird docker start prod
    ```
 
-### B. Standard PM2 / Node.js Runtime
+### B. Standard Standalone PM2 / Node.js Runtime
 
-To deploy in a standard Linux environment using PM2 process manager:
+If you choose to run outside of Docker, you must set up the reverse proxy and databases manually. To deploy in a standard Linux environment using PM2:
 
 1. Install PM2 globally:
    ```bash
@@ -265,7 +297,7 @@ To deploy in a standard Linux environment using PM2 process manager:
    ```
 2. Start the application under PM2:
    ```bash
-   pm2 start index.js --name "bluebird-app"
+   pm2 start index.js --name "bluebird-app" --node-args="--env-file=.env" -i max
    ```
 3. Monitor status:
    ```bash

package/backend/logs/2026-07-14/info.log

@@ -0,0 +1,48 @@
+ 2026-07-14 22:04:34 -::1 -[GET] / 
+ 2026-07-14 22:04:38 -::1 -[GET] /about 
+ 2026-07-14 22:04:38 -::1 -[GET] /about 
+ 2026-07-14 22:04:39 -::1 -[GET] / 
+ 2026-07-14 22:04:39 -::1 -[GET] / 
+ 2026-07-14 22:06:26 -::1 -[GET] /api/users 
+ 2026-07-14 22:08:02 -::1 -[GET] /api/users 
+ 2026-07-14 22:08:05 -::1 -[GET] /api/ 
+ 2026-07-14 22:42:04 -::1 -[GET] /api/auth_generate 
+ 2026-07-14 22:42:05 -::1 -[GET] /api/auth_generate 
+ 2026-07-14 22:42:10 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:12 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:21 -::1 -[GET] /api/auth_logout 
+ 2026-07-14 22:42:24 -::1 -[GET] /api/auth_verify 
+ 2026-07-14 22:42:28 -::1 -[GET] / 
+ 2026-07-14 22:42:28 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:29 -::1 -[GET] / 
+ 2026-07-14 22:42:29 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:30 -::1 -[GET] /about 
+ 2026-07-14 22:42:31 -::1 -[GET] /about 
+ 2026-07-14 22:42:32 -::1 -[GET] / 
+ 2026-07-14 22:42:32 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:32 -::1 -[GET] / 
+ 2026-07-14 22:42:32 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:33 -::1 -[GET] /about 
+ 2026-07-14 22:42:35 -::1 -[GET] / 
+ 2026-07-14 22:42:35 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:42:37 -::1 -[GET] /about 
+ 2026-07-14 22:42:38 -::1 -[GET] / 
+ 2026-07-14 22:42:38 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:54 -::1 -[GET] / 
+ 2026-07-14 22:48:54 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:56 -::1 -[GET] /about 
+ 2026-07-14 22:48:58 -::1 -[GET] /about 
+ 2026-07-14 22:48:59 -::1 -[GET] / 
+ 2026-07-14 22:48:59 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:48:59 -::1 -[GET] / 
+ 2026-07-14 22:48:59 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:01 -::1 -[GET] /about 
+ 2026-07-14 22:49:02 -::1 -[GET] / 
+ 2026-07-14 22:49:02 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:03 -::1 -[GET] /about 
+ 2026-07-14 22:49:04 -::1 -[GET] / 
+ 2026-07-14 22:49:04 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:05 -::1 -[GET] /about 
+ 2026-07-14 22:49:07 -::1 -[GET] / 
+ 2026-07-14 22:49:07 -::ffff:127.0.0.1 -[GET] /api/ 
+ 2026-07-14 22:49:07 -::1 -[GET] /about 

package/backend/routes/api.js

@@ -40,12 +40,12 @@ routerApi.get("/cache", Cache.middleware(), async (req, res) => {
 });
 
 routerApi.get("/auth_generate", async (req, res) => {
-  const token = await Auth.login(res, { id: 1, name: "John Doe" });
+  const token = await Auth.login(res, { id: 1, name: "John Doe" }, "auth");
   res.json({ message: "Auth successful", token });
 });
 
 routerApi.get("/auth_logout", async (req, res) => {
-  await Auth.logout(res);
+  await Auth.logout(res, "auth", {}, req);
   res.json({ message: "Auth successful" });
 });
 

package/core/auth.js

@@ -1,6 +1,7 @@
 import jwt from "jsonwebtoken";
 import crypto from "node:crypto";
 import Config from "./config.js";
+import { getRedisClient } from "./cache.js";
 
 const propsConfig = Config.props();
 const jwtSecret = propsConfig.jwtSecret;
@@ -57,11 +58,7 @@ class Auth {
    * @param {string} [expiresIn="24h"] - Expiration time.
    * @returns {string} The generated token.
    */
-  static generateToken(
-    payload,
-    secret = jwtSecret,
-    expiresIn = "24h"
-  ) {
+  static generateToken(payload, secret = jwtSecret, expiresIn = "24h") {
     if (!secret)
       throw new Error("FATAL: JWT_SECRET environment variable is not defined.");
     const encrypted = this.encrypt(payload, secret);
@@ -101,7 +98,7 @@ class Auth {
   static protect(options = {}) {
     const { redirect = null, key = "user", cookieKey = "auth" } = options;
 
-    return (req, res, next) => {
+    return async (req, res, next) => {
       const token =
         req.cookies?.[cookieKey] || req.headers.authorization?.split(" ")[1];
 
@@ -123,6 +120,32 @@ class Auth {
           : res.status(401).send();
       }
 
+      const redisClient = getRedisClient();
+      if (redisClient && decoded._sessionId) {
+        try {
+          const sessionData = await redisClient.get(
+            `session:${decoded._sessionId}`,
+          );
+          if (!sessionData) {
+            if (redirect && !isContentTypeJson) return res.redirect(redirect);
+            return isContentTypeJson
+              ? res.status(401).json({ message: "Unauthorized" })
+              : res.status(401).send();
+          }
+          req[key || "user"] = JSON.parse(sessionData);
+          return next();
+        } catch (err) {
+          console.error(
+            "[AUTH ERROR] Failed to get session data from Redis:",
+            err.message,
+          );
+          if (redirect && !isContentTypeJson) return res.redirect(redirect);
+          return isContentTypeJson
+            ? res.status(401).json({ message: "Unauthorized" })
+            : res.status(401).send();
+        }
+      }
+
       req[key || "user"] = decoded;
       next();
     };
@@ -142,8 +165,10 @@ class Auth {
    */
   static async login(res, data, key = "auth", options = {}) {
     const { expiresIn = "24h", cookie = {} } = options;
+    const sessionId = crypto.randomUUID();
+    const tokenPayload = { ...data, _sessionId: sessionId };
 
-    const token = this.generateToken(data, jwtSecret, expiresIn);
+    const token = this.generateToken(tokenPayload, jwtSecret, expiresIn);
 
     const defaultCookieOptions = {
       maxAge: 24 * 60 * 60 * 1000,
@@ -155,6 +180,34 @@ class Auth {
 
     const finalCookieOptions = { ...defaultCookieOptions, ...cookie };
 
+    const redisClient = getRedisClient();
+    if (redisClient) {
+      try {
+        let ttl = 86400;
+        if (typeof expiresIn === "string") {
+          const match = expiresIn.match(/^(\d+)([smhd])$/);
+          if (match) {
+            const val = parseInt(match[1]);
+            const unit = match[2];
+            if (unit === "s") ttl = val;
+            else if (unit === "m") ttl = val * 60;
+            else if (unit === "h") ttl = val * 3600;
+            else if (unit === "d") ttl = val * 86400;
+          }
+        } else if (typeof expiresIn === "number") {
+          ttl = expiresIn;
+        }
+        await redisClient.set(`session:${sessionId}`, JSON.stringify(data), {
+          EX: ttl,
+        });
+      } catch (err) {
+        console.error(
+          "[AUTH ERROR] Failed to store session in Redis:",
+          err.message,
+        );
+      }
+    }
+
     res.cookie(key, token, finalCookieOptions);
     return token;
   }
@@ -164,14 +217,37 @@ class Auth {
    * @param {import('express').Response} res - The response object.
    * @param {string} [key="auth"] - The key for the cookie.
    * @param {import('express').CookieOptions} [options={}] - Options for clearing the cookie.
+   * @param {import('express').Request} [req=null] - The request object.
    * @returns {Promise<boolean>} True if the cookie was cleared successfully.
    * @example
    * await Auth.logout(res);
    */
-  static async logout(res, key = "auth", options = {}) {
+  static async logout(res, key = "auth", options = {}, req = null) {
     const defaultOptions = {
       path: "/",
     };
+
+    if (req) {
+      const token =
+        req.cookies?.[key] || req.headers.authorization?.split(" ")[1];
+      if (token) {
+        const decoded = this.verifyToken(token);
+        if (decoded && decoded._sessionId) {
+          const redisClient = getRedisClient();
+          if (redisClient) {
+            try {
+              await redisClient.del(`session:${decoded._sessionId}`);
+            } catch (err) {
+              console.error(
+                "[AUTH ERROR] Failed to delete session from Redis:",
+                err.message,
+              );
+            }
+          }
+        }
+      }
+    }
+
     res.clearCookie(key, { ...defaultOptions, ...options });
     return true;
   }

package/core/cache.js

@@ -1,38 +1,101 @@
+import fs from "node:fs";
+
 const CACHE = {};
 
+let redisClient = null;
+let isRedisConnected = false;
+const redisHost = process.env.REDIS_HOST ?? false;
+const redisPort = process.env.REDIS_PORT ?? 6379;
+const redisPassword = process.env.REDIS_PASSWORD || "";
+const redisUrl = redisPassword
+  ? `redis://:${redisPassword}@${redisHost}:${redisPort}`
+  : `redis://${redisHost}:${redisPort}`;
+
+/**
+ * Initializes the Redis client connection if REDIS_HOST env is set.
+ * @returns {Promise<void>}
+ */
+async function initRedis() {
+  if (redisClient) return;
+  if (!redisHost) return;
+
+  try {
+    const { createClient } = await import("redis");
+    let host = redisHost;
+    if (host === "localhost" && fs.existsSync("/.dockerenv")) {
+      host = "redis";
+    }
+    const url = redisUrl;
+
+    redisClient = createClient({ url });
+    redisClient.on("error", () => {
+      isRedisConnected = false;
+    });
+    await redisClient.connect();
+    isRedisConnected = true;
+  } catch (err) {
+    redisClient = null;
+    isRedisConnected = false;
+  }
+}
+
+initRedis().catch(() => {});
+
 setInterval(() => {
-    const now = Date.now();
-    for (const key in CACHE) {
-        if (CACHE[key].expiry <= now) {
-            delete CACHE[key];
-        }
+  const now = Date.now();
+  for (const key in CACHE) {
+    if (CACHE[key].expiry <= now) {
+      delete CACHE[key];
     }
+  }
 }, 300000).unref();
+
 /**
- * Simple in-memory Cache class to provide middleware for Express routes.
- * Caches JSON responses based on the request URL.
+ * High-performance Caching class supporting both local memory and Redis backends.
  */
 class Cache {
   /**
-   * Middleware to cache responses.
-   * @param {number} [seconds=60] - Number of seconds to cache the response.
-   * @returns {Function} Express middleware function.
-   * @example
-   * router.get("/stats", Cache.middleware(120), (req, res) => {
-   *     res.json({ ok: true });
-   * });
+   * Express middleware to cache route JSON and HTML responses.
+   * @param {number} [seconds=60] - Expiry time in seconds.
+   * @returns {Function} Express middleware.
    */
   static middleware(seconds = 60) {
-    return (req, res, next) => {
+    return async (req, res, next) => {
       const key = req.originalUrl;
 
-      if (CACHE[key] && CACHE[key].expiry > Date.now()) {
-        const cached = CACHE[key];
-        if (cached.type === "json") {
-          return res.json(cached.data);
-        } else {
-          res.type("text/html");
-          return res.send(cached.data);
+      if (redisHost && !redisClient) {
+        await initRedis().catch(() => {});
+      }
+
+      if (isRedisConnected && redisClient) {
+        try {
+          const cachedData = await redisClient.get(key);
+          if (cachedData) {
+            const cached = JSON.parse(cachedData);
+            if (cached.type === "json") {
+              return res.json(cached.data);
+            } else {
+              res.type("text/html");
+              res.set("X-Blue-Bird-Cache", "HIT");
+              return res.send(cached.data);
+            }
+          }
+        } catch (err) {
+          isRedisConnected = false;
+        }
+      }
+
+      if (!isRedisConnected || !redisClient) {
+        if (CACHE[key] && CACHE[key].expiry > Date.now()) {
+          const cached = CACHE[key];
+          if (cached.type === "json") {
+            res.set("X-Blue-Bird-Cache", "HIT");
+            return res.json(cached.data);
+          } else {
+            res.type("text/html");
+            res.set("X-Blue-Bird-Cache", "HIT");
+            return res.send(cached.data);
+          }
         }
       }
 
@@ -40,33 +103,66 @@ class Cache {
       const originalSend = res.send.bind(res);
       let cachedInRequest = false;
 
-      res.json = (body) => {
+      res.json = async (body) => {
         if (!cachedInRequest) {
-          CACHE[key] = {
+          cachedInRequest = true;
+          const cacheObject = {
             type: "json",
             data: body,
             expiry: Date.now() + seconds * 1000,
           };
-          cachedInRequest = true;
+          if (isRedisConnected && redisClient) {
+            try {
+              await redisClient.set(key, JSON.stringify(cacheObject), {
+                EX: seconds,
+              });
+            } catch (err) {
+              CACHE[key] = cacheObject;
+            }
+          } else {
+            CACHE[key] = cacheObject;
+          }
         }
+        res.set("X-Blue-Bird-Cache", "MISS");
         return originalJson(body);
       };
 
-      res.send = (body) => {
+      res.send = async (body) => {
         if (!cachedInRequest && typeof body === "string") {
-          CACHE[key] = {
+          cachedInRequest = true;
+          const cacheObject = {
             type: "html",
             data: body,
             expiry: Date.now() + seconds * 1000,
           };
-          cachedInRequest = true;
+          if (isRedisConnected && redisClient) {
+            try {
+              await redisClient.set(key, JSON.stringify(cacheObject), {
+                EX: seconds,
+              });
+            } catch (err) {
+              CACHE[key] = cacheObject;
+            }
+          } else {
+            CACHE[key] = cacheObject;
+          }
         }
+        res.set("X-Blue-Bird-Cache", "MISS");
         return originalSend(body);
       };
 
+      res.set("X-Blue-Bird-Cache", "MISS");
       next();
     };
   }
 }
 
-export default Cache;
+/**
+ * Returns the active Redis client if connected.
+ * @returns {Object|null} The Redis client instance or null.
+ */
+export function getRedisClient() {
+  return isRedisConnected ? redisClient : null;
+}
+
+export default Cache;

package/core/cli/docker.js

@@ -58,27 +58,43 @@ async function startCommand(service) {
   checkComposeFile();
 
   if (service === "mysql" || service === "--mysql" || service === "dev") {
-    console.log(chalk.cyan("Starting MySQL container (dev mode)..."));
+    console.log(chalk.cyan("Starting MySQL container..."));
     const code = await runCmd("docker", ["compose", "up", "-d", "mysql"]);
     if (code === 0) {
-      console.log(chalk.green("MySQL started. Run your app locally with: npm run dev"));
-      console.log(chalk.blue("To also run the app in Docker (production), use: npx blue-bird docker start prod"));
+      console.log(chalk.green("MySQL started."));
     } else {
       console.error(chalk.red("Error starting MySQL."));
       process.exit(1);
     }
+  } else if (service === "redis" || service === "--redis") {
+    console.log(chalk.cyan("Starting Redis container..."));
+    const code = await runCmd("docker", ["compose", "up", "-d", "redis"]);
+    if (code === 0) {
+      console.log(chalk.green("Redis started."));
+    } else {
+      console.error(chalk.red("Error starting Redis."));
+      process.exit(1);
+    }
+  } else if (service === "dbs" || service === "databases") {
+    console.log(chalk.cyan("Starting Database containers (MySQL + Redis)..."));
+    const code = await runCmd("docker", ["compose", "up", "-d", "mysql", "redis"]);
+    if (code === 0) {
+      console.log(chalk.green("Database containers started."));
+    } else {
+      console.error(chalk.red("Error starting databases."));
+      process.exit(1);
+    }
   } else if (service === "prod" || service === "app" || service === "--app" || !service) {
-    console.log(chalk.cyan("Starting production stack (MySQL + Node.js app)..."));
+    console.log(chalk.cyan("Starting production stack (MySQL + Redis + App + Nginx)..."));
     const code = await runCmd("docker", ["compose", "--profile", "prod", "up", "-d"]);
     if (code === 0) {
       console.log(chalk.green("Production stack started."));
-      console.log(chalk.blue("View logs with: npx blue-bird docker logs"));
     } else {
       console.error(chalk.red("Error starting production stack."));
       process.exit(1);
     }
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: mysql (or --mysql), prod (or --app), or no arguments for both.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: mysql, redis, dbs, prod.`));
     process.exit(1);
   }
 }
@@ -99,13 +115,18 @@ async function stopCommand(service) {
     await runCmd("docker", ["compose", "stop", "mysql"]);
     await runCmd("docker", ["compose", "rm", "-f", "mysql"]);
     console.log(chalk.green("MySQL stopped."));
+  } else if (service === "redis" || service === "--redis") {
+    console.log(chalk.cyan("Stopping Redis..."));
+    await runCmd("docker", ["compose", "stop", "redis"]);
+    await runCmd("docker", ["compose", "rm", "-f", "redis"]);
+    console.log(chalk.green("Redis stopped."));
   } else if (service === "app" || service === "--app") {
     console.log(chalk.cyan("Stopping Node.js app container..."));
     await runCmd("docker", ["compose", "--profile", "prod", "stop", "app"]);
     await runCmd("docker", ["compose", "--profile", "prod", "rm", "-f", "app"]);
     console.log(chalk.green("App container stopped."));
   } else {
-    console.error(chalk.red(`Unknown service '${service}'. Use: all (default), mysql, app.`));
+    console.error(chalk.red(`Unknown service '${service}'. Use: all, mysql, redis, app.`));
     process.exit(1);
   }
 }
@@ -235,6 +256,30 @@ async function pruneCommand(forceOpt, allOpt) {
   await runCmd("docker", ["system", "df"]);
 }
 
+/**
+ * Executes PM2 commands inside the Node.js application container.
+ * @param {string[]} pm2Args - Arguments to pass to PM2.
+ */
+async function pm2Command(pm2Args = []) {
+  checkComposeFile();
+  const subCommand = pm2Args[0] || "status";
+  const cmdArgs = ["compose", "exec", "app", "pm2", subCommand, ...pm2Args.slice(1)];
+  const code = await runCmd("docker", cmdArgs);
+  if (code !== 0) {
+    console.error(chalk.red("Error running PM2 command. Make sure the production stack is started."));
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles interactive shell connections into the Redis container.
+ */
+async function redisCommand() {
+  checkComposeFile();
+  const cmdArgs = ["compose", "exec", "redis", "redis-cli"];
+  await runCmd("docker", cmdArgs);
+}
+
 /**
  * Entry point for Blue Bird CLI Docker subcommands.
  */
@@ -286,6 +331,12 @@ async function main() {
     case "logs":
       await logsCommand(args[1], args[2]);
       break;
+    case "pm2":
+      await pm2Command(args.slice(1));
+      break;
+    case "redis":
+      await redisCommand();
+      break;
     case "mysql":
     case "db": {
       let user, password, db, root = false;
@@ -312,7 +363,7 @@ async function main() {
     }
     default:
       console.log(chalk.yellow(`Unknown docker command: ${command}`));
-      console.log("Available commands: start, stop, build, ps, logs, mysql/db, df/disk, prune/clean");
+      console.log("Available commands: start, stop, build, ps, logs, pm2, mysql/db, redis, df/disk, prune/clean");
   }
 }
 

package/core/database.js

@@ -0,0 +1,182 @@
+import crypto from "node:crypto";
+import { getRedisClient } from "./cache.js";
+
+let mysqlPromise = null;
+try {
+  mysqlPromise = await import("mysql2/promise");
+} catch (err) {
+  console.error(
+    "[DATABASE ERROR] mysql2 package is not installed. Database wrapper is disabled.",
+  );
+}
+
+/**
+ * Database class wrapping mysql2 with reconnection retries, connection pool, and query caching.
+ */
+class Database {
+  /**
+   * Initializes config from DATABASE_URL or DB_* environment variables.
+   */
+  constructor(connectionLimit = 10, queueLimit = 0) {
+    this.pool = null;
+    this.config = {
+      host: process.env.DB_HOST || "localhost",
+      user: process.env.DB_USER || "root",
+      password: process.env.DB_PASSWORD || "root",
+      database: process.env.DB_NAME || "blue_bird",
+      port: parseInt(process.env.DB_PORT) || 3306,
+      charset: "utf8mb4",
+      waitForConnections: true,
+      connectionLimit: connectionLimit,
+      queueLimit: queueLimit,
+    };
+
+    if (
+      process.env.DATABASE_URL &&
+      process.env.DATABASE_URL.startsWith("mysql://")
+    ) {
+      try {
+        const url = new URL(process.env.DATABASE_URL);
+        this.config.host = url.hostname;
+        this.config.port = parseInt(url.port) || 3306;
+        this.config.user = url.username;
+        this.config.password = url.password;
+        this.config.database = url.pathname.substring(1);
+      } catch (err) {
+        console.error(
+          "[DATABASE ERROR] Failed to parse DATABASE_URL:",
+          err.message,
+        );
+      }
+    }
+  }
+
+  /**
+   * Creates the MySQL connection pool with 3 retry attempts on failure.
+   * @param {number} [retries=3] - Number of connection attempts.
+   * @returns {Promise<boolean>} True if connection pool was created.
+   */
+  async init(retries = 3) {
+    if (!mysqlPromise) return false;
+    if (this.pool) return true;
+
+    for (let attempt = 1; attempt <= retries; attempt++) {
+      try {
+        this.pool = mysqlPromise.createPool(this.config);
+        await this.pool.query("SELECT 1");
+        return true;
+      } catch (err) {
+        this.pool = null;
+        if (attempt === retries) {
+          console.error(
+            `[DATABASE ERROR] Connection failed after ${retries} attempts:`,
+            err.message,
+          );
+          return false;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Runs a SQL query with parameters and formatting options.
+   *
+   * @param {string} sql - SQL query string.
+   * @param {Array} [params=[]] - Query parameter array.
+   * @param {Object|string} [options={}] - Query options. Supports 'return_row', 'return_rows', and 'cache' (seconds).
+   * @returns {Promise<*>| int | boolean} Formatted query result or false on error, or insert id of insert query.
+   * @example select
+   *  const result = await connection.query("SELECT * FROM users", [], { return_row: true, cache: 60 });
+   * @example insert
+   *  const result = await connection.query("INSERT INTO users (name, email, password) VALUES (?, ?, ?)", ["John Doe", "[EMAIL_ADDRESS]", "123456"]);
+   * @example update
+   *  const result = await connection.query("UPDATE users SET name = ? WHERE id = ?", ["John Doe", 1]);
+   * @example delete
+   *  const result = await connection.query("DELETE FROM users WHERE id = ?", [1]);
+   */
+  async query(sql, params = [], options = {}) {
+    if (!mysqlPromise) return false;
+    if (!this.pool) {
+      const initialized = await this.init();
+      if (!initialized) return false;
+    }
+
+    const queryOptions =
+      typeof options === "string" ? { [options]: true } : options;
+    const cleanSql = sql.trim();
+    const isSelect = cleanSql.toLowerCase().startsWith("select");
+    const isInsert = cleanSql.toLowerCase().startsWith("insert");
+
+    const redisClient = getRedisClient();
+    let cacheKey = null;
+    const isDebug = queryOptions.debug ?? false;
+    if (isDebug) {
+      console.log("[DATABASE DEBUG] SQL:", sql);
+      console.log("[DATABASE DEBUG] PARAMS:", params);
+      console.log("[DATABASE DEBUG] OPTIONS:", options);
+    }
+
+    if (isSelect && queryOptions.cache && redisClient) {
+      const hash = crypto
+        .createHash("md5")
+        .update(cleanSql + JSON.stringify(params))
+        .digest("hex");
+      cacheKey = `db:${hash}`;
+      try {
+        if (isDebug) {
+          console.log("[DATABASE DEBUG ][Redis] CACHE KEY:", cacheKey);
+        }
+        const cached = await redisClient.get(cacheKey);
+        if (cached) {
+          if (isDebug) {
+            console.log("[DATABASE DEBUG ][Redis] CACHE HIT");
+          }
+          return JSON.parse(cached);
+        } else {
+          if (isDebug) {
+            console.log("[DATABASE DEBUG ][Redis] CACHE MISS");
+          }
+        }
+      } catch (err) {
+        console.error(
+          "[DATABASE ERROR] Failed to get cached data:",
+          err.message,
+        );
+      }
+    }
+
+    try {
+      const [results] = await this.pool.execute(cleanSql, params);
+
+      if (isSelect) {
+        const rows = Array.isArray(results) ? results : [];
+        if (cacheKey && queryOptions.cache && redisClient) {
+          await redisClient
+            .set(cacheKey, JSON.stringify(rows), {
+              EX: parseInt(queryOptions.cache),
+            })
+            .catch(() => {});
+        }
+        if (queryOptions.return_row) {
+          return rows.length > 0 ? rows[0] : null;
+        }
+        return rows;
+      }
+
+      if (isInsert) {
+        return results.insertId || results;
+      }
+
+      return results;
+    } catch (err) {
+      console.error("[DATABASE ERROR] Query execution failed:", err.message);
+      throw err;
+    }
+  }
+}
+
+const connection = new Database();
+export default connection;
+export { Database };

package/core/logger.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import Config from "./config.js";
+import { getRedisClient } from "./cache.js";
 
 const __dirname = Config.dirname();
 
@@ -52,47 +53,62 @@ class Logger {
   }
 
   /**
-   * Appends an informational message to the info.log file (non-blocking).
-   * @param {string} message - The message to log.
+   * Logs a message to the specified log file or Redis list.
+   * @private
+   * @param {string} file - The file name to log to.
+   * @param {string} level - The log level (e.g. info, error, warn, debug).
+   * @param {string} message - The log message.
    */
-  info(message) {
-    const logFile = path.join(this.nowFolder(), "info.log");
+  async _log(file, level, message) {
+    const redisClient = getRedisClient();
+    if (redisClient) {
+      try {
+        await redisClient.lPush(`bluebird:logs:${level}`, message);
+        return;
+      } catch (err) {
+        console.error(
+          `[LOGGER ERROR] Failed to write to Redis logs (${level}):`,
+          err.message,
+        );
+      }
+    }
+
+    const logFile = path.join(this.nowFolder(), file);
     fs.appendFile(logFile, `${message}\n`, (err) => {
       if (err) console.error("Logger write error:", err.message);
     });
   }
 
   /**
-   * Appends an error message to the error.log file (non-blocking).
+   * Appends an informational message.
+   * @param {string} message - The message to log.
+   */
+  info(message) {
+    this._log("info.log", "info", message);
+  }
+
+  /**
+   * Appends an error message.
    * @param {string} message - The error message to log.
    */
   error(message) {
-    const logFile = path.join(this.nowFolder(), "error.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("error.log", "error", message);
   }
 
   /**
-   * Appends a warning message to the warn.log file (non-blocking).
+   * Appends a warning message.
    * @param {string} message - The warning message to log.
    */
   warning(message) {
-    const logFile = path.join(this.nowFolder(), "warn.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("warn.log", "warn", message);
   }
 
   /**
-   * Appends a debug message to the debug.log file (non-blocking).
+   * Appends a debug message.
    * @param {string} message - The debug message to log.
    */
   debug(message) {
-    const logFile = path.join(this.nowFolder(), "debug.log");
-    fs.appendFile(logFile, `${message}\n`, (err) => {
-      if (err) console.error("Logger write error:", err.message);
-    });
+    this._log("debug.log", "debug", message);
   }
 }
 

package/docker/Dockerfile

@@ -1,25 +1,16 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Blue Bird Framework — Production Dockerfile
-# Node.js 24-alpine for lightweight, production-ready environment
-# ─────────────────────────────────────────────────────────────────────────────
 FROM node:24.7.0-alpine3.21
 
-# Set environment variables
 ENV NODE_ENV=production
 
 WORKDIR /app
 
-# Copy package files first (layer cache optimization)
 COPY package*.json ./
 
-# Install production dependencies
-RUN npm ci --omit=dev
+RUN npm ci --omit=dev && npm install -g pm2
 
-# Copy project source
 COPY . .
 
-# Expose the application port
 EXPOSE 3000
 
-# Start the application
-CMD ["npm", "start"]
+CMD ["sh", "-c", "pm2-runtime start index.js -i ${PM2_INSTANCES:-1}"]
+

package/docker/nginx.conf

@@ -0,0 +1,83 @@
+user  nginx;
+worker_processes  auto;
+
+error_log  /var/log/nginx/error.log notice;
+pid        /var/run/nginx.pid;
+
+events {
+    worker_connections  1024;
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+
+    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
+                      '$status $body_bytes_sent "$http_referer" '
+                      '"$http_user_agent" "$http_x_forwarded_for"';
+
+    access_log  /var/log/nginx/access.log  main;
+
+    sendfile        on;
+    tcp_nopush     on;
+    tcp_nodelay    on;
+    keepalive_timeout  65;
+    types_hash_max_size 2048;
+
+    gzip on;
+    gzip_disable "msie6";
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_buffers 16 8k;
+    gzip_http_version 1.1;
+    gzip_min_length 256;
+    gzip_types
+        text/plain
+        text/css
+        application/json
+        application/javascript
+        application/x-javascript
+        text/xml
+        application/xml
+        application/xml+rss
+        text/javascript
+        image/svg+xml;
+
+    limit_req_zone $binary_remote_addr zone=bluebird_limit:10m rate=10r/s;
+
+    server {
+        listen 80;
+        server_name localhost;
+        root /app/frontend/dist/client;
+
+        resolver 127.0.0.11 valid=5s;
+
+        location ~* /(\.env|\.git|wp-content|wp-admin|xmlrpc\.php) {
+            return 444;
+        }
+
+        location / {
+            try_files $uri @node_app;
+        }
+
+        location /_astro/ {
+            expires max;
+            add_header Cache-Control "public, max-age=31536000, immutable";
+            try_files $uri =404;
+        }
+
+        location @node_app {
+            limit_req zone=bluebird_limit burst=20 nodelay;
+
+            set $upstream_target http://app:3000;
+            proxy_pass $upstream_target;
+            proxy_http_version 1.1;
+            proxy_set_header Connection "";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+    }
+}

package/docker-compose.yml

@@ -1,28 +1,12 @@
-# ─────────────────────────────────────────────────────────────────────────────
-# Blue Bird Framework — Docker Compose
-#
-# DEVELOPMENT / DATABASE ONLY:
-#   npx blue-bird docker start mysql   → Only MySQL container
-#
-# PRODUCTION:
-#   npx blue-bird docker start prod    → MySQL + Node.js app container
-#   npx blue-bird docker stop          → Stop all containers
-#
-# Multi-project VPS support:
-#   Each project uses TITLE (or sanitised TITLE) to name
-#   containers and networks uniquely.
-# ─────────────────────────────────────────────────────────────────────────────
-
 services:
-  # ── Node.js App (Production only) ─────────────────────────────────────────
   app:
     build:
       context: .
       dockerfile: docker/Dockerfile
     container_name: ${TITLE:-bluebird}-app
     restart: unless-stopped
-    ports:
-      - "${PORT:-3000}:${PORT:-3000}"
+    expose:
+      - "3000"
     volumes:
       - .:/app
       - /app/node_modules
@@ -32,15 +16,36 @@ services:
       - NODE_ENV=production
       - DEBUG=false
       - DATABASE_URL=mysql://root:${DB_PASSWORD:-root}@mysql:3306/${DB_NAME:-blue_bird}
+      - REDIS_HOST=redis
+      - REDIS_PORT=6379
+      - PORT=3000
     depends_on:
       mysql:
         condition: service_healthy
+      redis:
+        condition: service_healthy
+    networks:
+      - bluebird_net
+    profiles:
+      - prod
+
+  nginx:
+    image: nginx:1.27-alpine
+    container_name: ${TITLE:-bluebird}-nginx
+    restart: unless-stopped
+    ports:
+      - "${PORT:-3000}:80"
+    volumes:
+      - .:/app:ro
+      - ./docker/nginx.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      app:
+        condition: service_started
     networks:
       - bluebird_net
     profiles:
       - prod
 
-  # ── MySQL Database ─────────────────────────────────────────────────────────
   mysql:
     image: mysql:8.0
     container_name: ${TITLE:-bluebird}-mysql
@@ -61,10 +66,28 @@ services:
     networks:
       - bluebird_net
 
+  redis:
+    image: redis:7-alpine
+    container_name: ${TITLE:-bluebird}-redis
+    restart: unless-stopped
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    networks:
+      - bluebird_net
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
 volumes:
   mysql_data:
+  redis_data:
 
 networks:
   bluebird_net:
     name: ${TITLE:-bluebird}_network
     driver: bridge
+

package/frontend/src/http/api.js

@@ -15,5 +15,10 @@ export function apiUrl(path = "", requestUrl) {
   if (!requestUrl) {
     throw new Error("apiUrl: requestUrl is required in production (pass Astro.url)");
   }
-  return new URL(`/${path}`, requestUrl).href;
+  const url = new URL(`/${path}`, requestUrl);
+  if (url.hostname === "localhost") {
+    url.hostname = "127.0.0.1";
+    url.port = port;
+  }
+  return url.href;
 }

package/frontend/src/pages/index.astro

@@ -4,11 +4,17 @@ import { apiUrl } from "../http/api";
 
 let apiData = null;
 try {
-  const response = await fetch(apiUrl("api/", Astro.url));
+  const targetUrl = apiUrl("api/", Astro.url);
+  console.log("[index.astro] request URL:", Astro.url.href);
+  console.log("[index.astro] target URL:", targetUrl);
+  const response = await fetch(targetUrl);
   apiData = await response.json();
   console.log("[index.astro] /api/ response:", apiData);
 } catch (err) {
   console.error("[index.astro] fetch error:", err.message);
+  if (err.cause) {
+    console.error("[index.astro] fetch error cause:", err.cause);
+  }
 }
 ---
 

package/index.js

@@ -16,6 +16,8 @@ const app = new App({
 
   port: process.env.PORT,
 
+  logger: true, //In production, set this to false to disable logging and stop writing to Redis
+
   astro: {
     server: true,
     serverEntry: "./frontend/dist/server/entry.mjs",

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@seip/blue-bird",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Express opinionated framework with HTML rendering, API architecture, built-in JWT auth, validation, caching, and SEO",
   "type": "module",
+  "exports": {
+    "./*": "./*"
+  },
   "bin": {
     "blue-bird": "core/cli/init.js"
   },
@@ -62,6 +65,8 @@
     "helmet": "^8.1.0",
     "jsonwebtoken": "^9.0.2",
     "multer": "^2.0.2",
+    "mysql2": "^3.22.6",
+    "redis": "^4.7.0",
     "xss": "^1.0.15"
   }
 }