@seip/blue-bird 0.6.4 → 0.7.1

package/.env_example

@@ -3,24 +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"
 
-# HTML Meta / SEO Configuration
-TITLE_META="Blue Bird"
-DESCRIPTION_META="Example description meta"
-KEYWORDS_META="Example keywords meta"
-AUTHOR_META="Blue Bird"
-LANGMETA="en"
-
 # 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

@@ -4,11 +4,12 @@ This document serves as the primary manual for any AI Agent interacting with the
 
 ## 1. Core Architecture
 
-Blue Bird is a framework built on **Express** for backend and **HTML/Tailwind CSS/JS** for frontend rendering. It saves developers from repetitive configuration, validation, security, JWT authentication, HTML rendering with caching, and automatic HTML minification and compression out of the box.
+Blue Bird is a framework built on **Express** for backend and **Astro** (v7.0) for frontend rendering. It saves developers from repetitive configuration, validation, security, JWT authentication, and database environment configuration out of the box.
 
-- **Backend (`backend/`)**: Initializes the server using `App` from `core/app.js` and invokes routing from `backend/routes/`.
-- **Frontend (`frontend/`)**: Static HTML views (`.html`) and static assets. Static files go in `frontend/public/`.
-- **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Template`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
+- **Entrypoint (`index.js`)**: Initializes the server using `App` from `core/app.js` and registers the routes.
+- **Backend (`backend/`)**: Application routes and logic (e.g. `backend/routes/`).
+- **Frontend (`frontend/`)**: Astro project files. Source pages go in `frontend/src/pages/` and static/public assets go in `frontend/public/`.
+- **Core (`core/`)**: The framework core. Contains wrapper classes such as `Router`, `Validator`, `Auth`, `Cache`, etc. **DO NOT MODIFY** the core unless explicitly requested, as it could break other apps.
 
 ## 2. Routing (Router)
 
@@ -26,121 +27,55 @@ routerApi.get("/users", (req, res) => {
 export default routerApi;
 ```
 
-**For the Frontend (HTML Rendering / SEO):**
-Blue Bird renders HTML templates directly using its `Template` class.
+Astro routes (pages) are handled automatically by Astro's file-based routing inside the `frontend/src/pages/` directory.
 
-```javascript
-import Router from "@seip/blue-bird/core/router.js";
-import Template from "@seip/blue-bird/core/template.js";
+## 3. Astro Node Middleware Integration
 
-const router = new Router("/", { seo: true });
+Blue Bird integrates Astro as a middleware handler. This is configured in the main `App` constructor:
 
-router.get("/", (req, res) => {
-  return Template.render(res, "index", {
-    metaTags: {
-      titleMeta: "Home",
-      descriptionMeta: "Welcome to my site",
-    },
-  });
-});
+```javascript
+import App from "@seip/blue-bird/core/app.js";
+import routerApi from "./backend/routes/api.js";
 
-router.get("/about", (req, res) => {
-  return Template.render(res, "about", {
-    metaTags: {
-      titleMeta: "About Us",
-      descriptionMeta: "Learn more about us",
-    },
-  });
+const app = new App({
+  routes: [routerApi],
+  astro: true, // Enables Astro SSR/SSG middleware mode
 });
-```
-
-**SEO (Sitemap & Robots.txt):**
-When a `Router` is created with `{ seo: true }`, all `GET` routes registered on it are automatically included in the generated `/sitemap.xml` and `/robots.txt`.
 
-```javascript
-const router = new Router("/", { seo: true });
+app.run();
 ```
 
-- **Automatic Sitemap:** Dynamic `sitemap.xml` with all routes from `seo: true` routers.
-- **Robots.txt:** Auto-served pointing to the generated sitemap.
-
-## 3. HTML View Rendering (Template)
-
-The `Template` class renders HTML files directly from the `frontend/` directory. It resolves placeholders in the HTML files (using double curly braces `{{variable}}`) populated by the options, metaTags, and application configurations.
+### Config Options
 
-### Standard Placeholders
-
-The renderer automatically replaces the following standard tags:
-
-- `{{lang}}` or `{{langHtml}}`: Active language code (defaults to `"en"`).
-- `{{title}}` or `{{titleMeta}}`: Page title.
-- `{{canonicalUrl}}`: Canonical page link.
-- `{{description}}` or `{{descriptionMeta}}`: Meta description text.
-- `{{keywords}}` or `{{keywordsMeta}}`: Meta keywords.
-- `{{author}}` or `{{authorMeta}}`: Meta author.
-- `{{classBody}}`: CSS class for the body wrapper.
-- `{{headOptions}}`: SEO Open Graph, Twitter cards, and hot reload scripts.
-- `{{linkStyles}}`: Dynamic stylesheet `<link>` tags.
-- `{{scriptsHead}}`: Script tags loaded in the `<head>`.
-- `{{scriptsBody}}`: Script tags loaded in the `<body>`.
-
-Additionally, any top-level key inside `options` or `metaTags` (e.g. `{{username}}`) will be dynamically replaced in the HTML template string.
-
-### Basic Rendering
+Astro middleware options can be customized by passing a configuration object:
 
 ```javascript
-import Template from "@seip/blue-bird/core/template.js";
-
-router.get("/", (req, res) => {
-  return Template.render(res, "index", {
-    metaTags: {
-      titleMeta: "Home",
-      descriptionMeta: "Welcome",
-      keywordsMeta: "home, welcome",
-      authorMeta: "Blue Bird",
-    },
-  });
+const app = new App({
+  astro: {
+    server: true, // Enables Astro SSR handler middleware
+    serverEntry: "./frontend/dist/server/entry.mjs", // Path to server build entrypoint
+    client: false, // Set to true to serve Astro client static assets
+    clientDir: "./frontend/dist/client", // Path to client static build folder
+    base: "/" // Base route mount path
+  }
 });
 ```
 
-### Caching and Minification Options
+To use Astro as Express middleware, ensure your Astro configuration uses the node adapter in middleware mode:
 
 ```javascript
-Template.render(res, "index", {
-  cache: 60 /** Cache TTL in seconds. Default: 60 (only active when DEBUG=false) */,
-  minify: true /** Automatically compress whitespace and remove comments. Default: true */,
-  cacheKey: "home" /** Optional custom cache key */,
-  metaTags: { titleMeta: "Home" },
+// frontend/astro.config.mjs
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',
+  adapter: node({
+    mode: 'middleware',
+  }),
 });
 ```
 
-**Cache behavior:**
-
-- `DEBUG=true` → Cache is always bypassed (reads from disk every time).
-- `DEBUG=false` + `cache` > 0 → Output HTML is cached in memory for the specified duration in seconds.
-- `DEBUG=false` + `cache: false` (or 0) → Bypasses caching entirely.
-
-### Cache Management
-
-```javascript
-import Template from "@seip/blue-bird/core/template.js";
-
-Template.clearCache();
-Template.clearCache("home");
-Template.getCacheKeys();
-```
-
-### Hot Reload (Development)
-
-When `DEBUG=true` in `.env`, Blue Bird automatically:
-
-1. Injects a hot-reload script into every rendered template.
-2. Watches `frontend/` for `.html`, `.css`, and `.js` file changes.
-3. Notifies connected browsers via Server-Sent Events (SSE) to reload.
-4. Clears the template cache on file changes.
-
-No configuration needed — it works automatically in debug mode.
-
 ## 4. Data Validation (Validator)
 
 Incoming request data must be validated using `core/validate.js`, which automatically returns HTTP 400 JSON responses on error.
@@ -154,10 +89,6 @@ const userSchema = {
   bio: { required: false },
 };
 
-const postSchema = {
-  contentHtml: { required: true, xss: false },
-};
-
 const validateUser = new Validator(userSchema, "en");
 
 routerApi.post("/users", validateUser.middleware(), (req, res) => {
@@ -179,21 +110,6 @@ import Auth from "@seip/blue-bird/core/auth.js";
 router.get("/profile", Auth.protect(), (req, res) => {
   res.json({ user: req.user });
 });
-
-router.get("/dashboard", Auth.protect({ redirect: "/login" }), (req, res) => {
-  Template.render(res, "dashboard");
-});
-
-router.get(
-  "/admin",
-  Auth.protect({
-    cookieKey: "admin_session",
-    key: "admin",
-  }),
-  (req, res) => {
-    res.json({ admin: req.admin });
-  },
-);
 ```
 
 ### Login and Logout
@@ -211,16 +127,11 @@ router.post("/logout", async (req, res) => {
   await Auth.logout(res);
   res.json({ message: "Logged out" });
 });
-
-await Auth.login(res, user, "my_session", {
-  expiresIn: "7d",
-  cookie: { httpOnly: true, secure: true },
-});
 ```
 
 ## 6. Performance Caching (Cache)
 
-If a route involves heavy processing or database queries, utilize the `Cache` middleware. It automatically caches both REST API JSON payloads (overriding `res.json`) and HTML/EJS rendered views (overriding `res.send`).
+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";
@@ -228,12 +139,10 @@ import Cache from "@seip/blue-bird/core/cache.js";
 router.get("/stats", Cache.middleware(60), (req, res) => {
   res.json({ ok: true });
 });
-
-router.get("/dashboard", Cache.middleware(120), (req, res) => {
-  Template.render(res, "dashboard");
-});
 ```
 
+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:
@@ -241,55 +150,42 @@ Helmet is **not applied globally** by default. Apply it per-router where needed:
 ```javascript
 import App from "@seip/blue-bird/core/app.js";
 
-const webRouter = new Router("/web");
-webRouter.use(App.helmet());
-webRouter.use(App.helmet({ contentSecurityPolicy: false }));
+const apiRouter = new Router("/api");
+apiRouter.use(App.helmet());
 ```
 
 ## 8. Docker Compose CLI
 
 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 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.
-
-## 9. Hybrid SPA & Preact Integration
-
-Blue Bird includes a high-performance Hybrid SPA rendering feature.
-1. **Server Detection**: `Template.render` intercepts SPA requests (header `X-blueBird-SPA: true` or query `?source=frontend`). It returns a parsed JSON payload with `meta`, `body` (only content inside `#blueBird-spa-content`), and `css` stylesheets.
-2. **SPA Direct Caching**: SPA requests are cached separately (key `spa:<template>`). The server strips security headers (CSP, Frame-Options, Content-Type-Options) to reduce JSON payload bytes.
-3. **Preact Islands**: Use import maps to render dynamic reactive zones. Simply add scripts of type `module` inside `#blueBird-spa-content`, and they will automatically execute and render on each navigation.
-
-```html
-<script type="importmap">
-    {
-        "imports": {
-            "preact": "https://esm.sh/preact@10.19.2",
-            "preact/hooks": "https://esm.sh/preact@10.19.2/hooks",
-            "htm/preact": "https://esm.sh/htm@3.1.1/preact"
-        }
-    }
-</script>
-```
+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.
 
-## 10. AI Development Guidelines
+## 9. AI Development Guidelines
 
-1. **Frontend**: Use static HTML templates inside `frontend/` (e.g. `.html` files). Standard static files belong in `frontend/public/`.
+1. **Frontend**: Use Astro pages inside `frontend/src/pages/` (e.g. `.astro` files). Static/public assets belong in `frontend/public/`.
 2. **JSON Responses**: API endpoints should return standardized responses formatted as `{ message: "..." }` or `{ data: ... }`.
 3. **Magic Imports**: Stick to pure relative imports or well-configured aliases (imports natively resolve from `@seip/blue-bird/...` or relative directories like `../../`).
-4. **SEO**: Create routers with `{ seo: true }` to auto-include routes in sitemap.xml and robots.txt.
-5. **Caching & Minification**: Cache pages using `Template.render` options or route-level `Cache.middleware()`. All HTML outputs are automatically minified.
-6. **No inline comments**: Only use JSDoc for documentation.
+4. **No inline comments**: Only use JSDoc for documentation.
 
 _This file can be retrieved by intelligent agents reading its absolute physical path during reasoning._

package/README.md

@@ -9,23 +9,19 @@
 
 ---
 
-## 🌟 Introduction / Introducción
+## Introduction
 
-**Blue Bird** is a powerful, opinionated framework built on **Express**. It's designed to help developers build fast, scalable applications and APIs with everything pre-configured: data validation, security middlewares, GCM-encrypted JWT authentication, raw HTML template rendering with fast in-memory caching, automatic HTML minification, SEO management, hot-reload, and CLI/Docker developer workflows out of the box.
-
-**Blue Bird** es un framework potente basado en **Express**. Está diseñado para ayudar a los desarrolladores a construir aplicaciones rápidas, APIs escalables y todo pre-configurado: validación de datos, middlewares de seguridad, autenticación JWT encriptada con GCM, renderizado de plantillas HTML crudo con caché ultra rápida en memoria, minificación HTML automática, gestión de SEO, hot-reload y flujos de trabajo con Docker y CLI integrados.
+Blue Bird is a powerful, opinionated framework built on Express for backend routing and APIs, integrated with Astro (v7.0) for high-performance frontend rendering. It features pre-configured data validation, security middlewares, GCM-encrypted JWT authentication, and CLI/Docker developer workflows out of the box.
 
 ---
 
 ## 🚀 Key Features / Características Clave
 
-- ⚡ **All-In-One**: Pre-configured Express server with JSON, URL encoding, Cookies, and CORS.
-- 🚀 **Fast Rendering**: Raw HTML template rendering (`Template.render`) with in-memory caching (configurable TTL).
-- 🧹 **Automatic Minification**: Compresses whitespace and strips HTML comments automatically in production.
-- 🔐 **Premium Security**: AES-256-GCM encrypted JWT cookie auth, secure route filters, and built-in Helmet configurator.
-- 📁 **File Uploads**: Easy Multer-based single/multiple file storage handling.
-- 🔄 **SSE Hot Reload**: Automated browser hot-reloading in development (`DEBUG=true`) on file changes.
-- 🐳 **Docker & PM2 Devops**: Pre-built Docker Compose/Dockerfile templates and CLI tools for zero-config dev and VPS production.
+- All-In-One: Pre-configured Express server with JSON, URL encoding, Cookies, and CORS.
+- Astro Frontend: Native integration with Astro (v7.0) for server-side rendering (SSR), static site generation (SSG), and middleware mode.
+- Premium Security: AES-256-GCM encrypted JWT cookie auth, secure route filters, and built-in Helmet configurator.
+- File Uploads: Easy Multer-based single/multiple file storage handling.
+- Docker & PM2 Devops: Pre-built Docker Compose/Dockerfile templates and CLI tools for zero-config dev and VPS production.
 
 ---
 
@@ -58,20 +54,21 @@ npm run dev
 ```
 project/
 ├── backend/
-│   ├── routes/              # Express route files
-│   │   ├── api.js           # REST API routes
-│   │   └── frontend.js      # Frontend HTML template routes
-│   └── index.js             # App startup and initialization
+│   └── routes/              # Express route files
+│       └── api.js           # REST API routes
 ├── frontend/
-│   ├── templates/           # Raw HTML template pages (.html)
-│   │   ├── index.html
-│   │   └── about.html
-│   └── public/              # Static assets (css, js, img, fonts)
-│       └── js/
-│           └── tailwind.js  # Local Tailwind compiler
+│   ├── src/
+│   │   └── pages/           # Astro routes and pages (.astro)
+│   │       ├── index.astro
+│   │       └── about.astro
+│   ├── public/              # Static assets mapped to root of Astro build
+│   │   └── css/
+│   │       └── app.css      # Css files
+│   └── astro.config.mjs     # Astro configuration file
 ├── docker/
-│   └── Dockerfile           # Optimized production multi-stage build file
+│   └── Dockerfile           # Optimized production build file
 ├── docker-compose.yml       # Dev/Prod container configurations
+├── index.js                 # App startup and initialization entrypoint
 ├── AGENTS.md                # AI coding assistant guidebook
 └── .env                     # App configuration (git-ignored)
 ```
@@ -80,7 +77,7 @@ project/
 
 ## 📖 Core Modules Documentation / Documentación de Módulos
 
-### 1. Routing & SEO (`Router`)
+### 1. Routing (`Router`)
 
 Do not use Express' native router. Always use Blue Bird's wrapper class:
 
@@ -94,61 +91,41 @@ routerApi.get("/users", (req, res) => {
 export default routerApi;
 ```
 
-**For the Frontend (HTML Rendering / SEO):**
-Instantiate a router with `{ seo: true }`. All registered GET routes are automatically added to the dynamic sitemap at `/sitemap.xml` and `/robots.txt`.
-
-```javascript
-const router = new Router("/", { seo: true });
-router.get("/", (req, res) => {
-  return Template.render(res, "index", {
-    metaTags: {
-      titleMeta: "Home",
-      descriptionMeta: "Welcome to Blue Bird Framework",
-    },
-  });
-});
-```
-
 ---
 
-### 2. HTML Template Rendering (`Template`)
-
-Renders raw HTML files from `frontend/templates/`. Replaces double-curly placeholders `{{variable}}` with matching values from options, metaTags, or system env.
+### 2. Astro Node Middleware Integration
 
-#### Standard Placeholders
+Blue Bird supports Astro (v7.0) Node middleware mode. Astro handles frontend SSR, routing, static assets, and layouts, while Express handles API endpoints and server logic.
 
-- `{{lang}}`: Selected/active language code.
-- `{{title}}` or `{{titleMeta}}`: Page HTML title.
-- `{{canonicalUrl}}`: Canonical page URL for crawlers.
-- `{{description}}`: Meta description.
-- `{{keywords}}`: Meta keywords.
-- `{{author}}`: Meta author.
+To enable Astro integration:
 
 ```javascript
-import Template from "@seip/blue-bird/core/template.js";
-
-router.get("/about", (req, res) => {
-  return Template.render(res, "about", {
-    cache: 60, // Cache TTL in seconds (only when DEBUG=false)
-    minify: true, // Automatically minifies whitespace and strips comments
-    metaTags: {
-      titleMeta: "About Us",
-      descriptionMeta: "Learn more about us",
-    },
-  });
+import App from "@seip/blue-bird/core/app.js";
+import routerApi from "./backend/routes/api.js";
+
+const app = new App({
+  routes: [routerApi],
+  astro: true, // Enables Astro middleware mode
 });
+
+app.run();
 ```
 
-#### Cache Controls
+#### Advanced Config Options
 
-- `DEBUG=true` -> Cache is always bypassed.
-- `DEBUG=false` -> Cached in-memory for TTL duration.
-- Programmatic management:
-  ```javascript
-  Template.clearCache(); // Clear all cache
-  Template.clearCache("about"); // Clear specific cache key
-  Template.getCacheKeys(); // Returns active cache keys
-  ```
+You can pass a configuration object instead of a boolean value:
+
+```javascript
+const app = new App({
+  astro: {
+    server: true, // Mounts Astro SSR handler
+    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
+  },
+});
+```
 
 ---
 
@@ -224,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`)
@@ -251,12 +230,15 @@ 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 prune`**: Safely clears orphaned volumes, dangling build caches, and images.
 
@@ -266,9 +248,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
@@ -278,9 +267,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
@@ -288,7 +277,7 @@ To deploy in a standard Linux environment using PM2 process manager:
    ```
 2. Start the application under PM2:
    ```bash
-   pm2 start backend/index.js --name "bluebird-app"
+   pm2 start index.js --name "bluebird-app" --node-args="--env-file=.env" -i max
    ```
 3. Monitor status:
    ```bash
@@ -298,67 +287,6 @@ To deploy in a standard Linux environment using PM2 process manager:
 
 ---
 
----
-
-## ⚡ Hybrid SPA & Preact Integration
-
-Blue Bird natively integrates high-performance Hybrid Single Page Application (SPA) support:
-* **Server-Side:** The `Template` class intercepts SPA requests and returns only the `#blueBird-spa-content` section wrapped in an optimized JSON payload. These requests feature cleaned headers (removing strict CSP/Frame rules to minimize footprint) and are cached independently in RAM.
-* **Client-Side (`blue-bird.js`):** The SPA engine intercepts local anchor link click events, plays animated *fadeOut* and *fadeIn* transitions using Anime.js, updates metadata, and injects the new HTML fragments.
-
-### Preact Integration (Reactive Component Structure)
-
-You can inject rich interactivity by adding Preact and HTM via Import Maps directly, without any build steps or bundlers:
-
-#### 1. Load the Import Map in your HTML head:
-```html
-<head>
-    <!-- ... -->
-    <script type="importmap">
-        {
-            "imports": {
-                "preact": "https://esm.sh/preact@10.19.2",
-                "preact/hooks": "https://esm.sh/preact@10.19.2/hooks",
-                "htm/preact": "https://esm.sh/htm@3.1.1/preact"
-            }
-        }
-    </script>
-    <script src="/js/blue-bird.js"></script>
-</head>
-```
-
-#### 2. Declare the component inside the `#blueBird-spa-content` container:
-```html
-<main id="blueBird-spa-content">
-    <div id="counter-app"></div>
-
-    <script type="module">
-        import { render } from 'preact';
-        import { useState } from 'preact/hooks';
-        import { html } from 'htm/preact';
-
-        function Counter() {
-            const [count, setCount] = useState(0);
-            return html`
-                <div class="p-6 bg-slate-900 border border-white/10 rounded-2xl">
-                    <h2 class="text-lg font-bold">Preact Counter</h2>
-                    <p class="text-3xl text-blue-400 font-extrabold my-2">${count}</p>
-                    <button class="px-4 py-2 bg-blue-600 rounded-lg text-white font-semibold" onClick=${() => setCount(count + 1)}>
-                        Increment
-                    </button>
-                </div>
-            `;
-        }
-
-        render(html`<${Counter} />`, document.getElementById('counter-app'));
-    </script>
-</main>
-```
-
-When navigating between pages using the SPA engine, any scripts of type `module` inside the page body will automatically execute in the DOM, mounting and updating your Preact "interactivity islands".
-
----
-
 ## 📄 License / Licencia
 
 Distributed under the **MIT License**. See `LICENSE` for more information.