spxkth 1.0.1

package/README.md

@@ -0,0 +1,26 @@
+# spxkth
+
+A modular, domain-agnostic Node.js backend framework with universal UI themes.
+
+## Installation
+
+```bash
+npm install -g spxkth
+```
+
+## Features
+
+- **Domain-Agnostic Backend**: Automatically registers routes and controllers for any business domain.
+- **Universal Themes**: Build your entire frontend using only 4 highly-configurable themes (Dashboard, List, Form, Detail).
+- **RESTful Standards**: Enforced CRUD patterns for predictable development.
+- **CLI Support**: Run `spxkth` to start your framework-powered server.
+
+## Quick Start
+
+1. Install the package globally.
+2. Run `spxkth` in your project directory.
+3. Access the API at `http://localhost:3000/api`.
+
+## License
+
+MIT © spxkth

package/config/db.js

@@ -0,0 +1,20 @@
+import mysql from 'mysql2/promise';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+export const dbConfig = {
+  host: process.env.DB_HOST || 'localhost',
+  user: process.env.DB_USER || 'root',
+  password: process.env.DB_PASSWORD || '',
+  database: process.env.DB_NAME || 'spxkth_db',
+};
+
+const pool = mysql.createPool(dbConfig);
+
+// Standardized query wrapper to match the required await db.query pattern
+export const db = {
+  query: (sql, params) => pool.execute(sql, params)
+};
+
+export default db;

package/controllers/reportsController.js

@@ -0,0 +1,33 @@
+import pool from "../config/db.js";
+
+export const getInventoryReport = async (req, res) => {
+  try {
+    const [rows] = await pool.execute("SELECT name, quantity, price, (quantity * price) as total_value FROM spare_parts");
+    res.status(200).json({
+      message: "Inventory report generated",
+      data: rows,
+    });
+  } catch (error) {
+    console.error("Error in getInventoryReport:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const getSystemStats = async (req, res) => {
+  try {
+    // Mock stats for demonstration
+    const stats = {
+      totalUsers: 150,
+      activeSessions: 12,
+      databaseSize: "45MB",
+      uptime: process.uptime(),
+    };
+    res.status(200).json({
+      message: "System stats retrieved",
+      data: stats,
+    });
+  } catch (error) {
+    console.error("Error in getSystemStats:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};

package/controllers/sparePartsController.js

@@ -0,0 +1,77 @@
+import { db } from "../config/db.js";
+
+export const createSparePart = async (req, res) => {
+  try {
+    const { name, description, quantity, price } = req.body;
+    const [result] = await db.query(
+      "INSERT INTO spare_parts (name, description, quantity, price) VALUES (?, ?, ?, ?)",
+      [name, description, quantity, price]
+    );
+    res.status(201).json({
+      message: "Spare part created successfully",
+      data: { id: result.insertId, name, description, quantity, price },
+    });
+  } catch (error) {
+    console.error("Error in createSparePart:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const listSpareParts = async (req, res) => {
+  try {
+    const [rows] = await db.query("SELECT * FROM spare_parts");
+    res.status(200).json({
+      message: "Spare parts retrieved successfully",
+      data: rows,
+    });
+  } catch (error) {
+    console.error("Error in listSpareParts:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const getSparePart = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const [rows] = await db.query("SELECT * FROM spare_parts WHERE id = ?", [id]);
+    if (rows.length === 0) {
+      return res.status(404).json({ error: "Spare part not found" });
+    }
+    res.status(200).json({
+      message: "Spare part retrieved successfully",
+      data: rows[0],
+    });
+  } catch (error) {
+    console.error("Error in getSparePart:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const updateSparePart = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const { name, description, quantity, price } = req.body;
+    await db.query(
+      "UPDATE spare_parts SET name = ?, description = ?, quantity = ?, price = ? WHERE id = ?",
+      [name, description, quantity, price, id]
+    );
+    res.status(200).json({
+      message: "Spare part updated successfully",
+      data: { id, name, description, quantity, price },
+    });
+  } catch (error) {
+    console.error("Error in updateSparePart:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const deleteSparePart = async (req, res) => {
+  try {
+    const { id } = req.params;
+    await db.query("DELETE FROM spare_parts WHERE id = ?", [id]);
+    res.status(200).json({ message: "Spare part deleted successfully" });
+  } catch (error) {
+    console.error("Error in deleteSparePart:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};

package/controllers/usersController.js

@@ -0,0 +1,79 @@
+import { db } from "../config/db.js";
+import bcrypt from "bcryptjs";
+
+export const createUser = async (req, res) => {
+  try {
+    const { username, email, password, role } = req.body;
+    const hashedPassword = await bcrypt.hash(password, 10);
+    const [result] = await db.query(
+      "INSERT INTO users (username, email, password, role) VALUES (?, ?, ?, ?)",
+      [username, email, hashedPassword, role || 'user']
+    );
+    res.status(201).json({
+      message: "User created successfully",
+      data: { id: result.insertId, username, email, role },
+    });
+  } catch (error) {
+    console.error("Error in createUser:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const listUsers = async (req, res) => {
+  try {
+    const [rows] = await db.query("SELECT id, username, email, role FROM users");
+    res.status(200).json({
+      message: "Users retrieved successfully",
+      data: rows,
+    });
+  } catch (error) {
+    console.error("Error in listUsers:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const getUser = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const [rows] = await db.query("SELECT id, username, email, role FROM users WHERE id = ?", [id]);
+    if (rows.length === 0) {
+      return res.status(404).json({ error: "User not found" });
+    }
+    res.status(200).json({
+      message: "User retrieved successfully",
+      data: rows[0],
+    });
+  } catch (error) {
+    console.error("Error in getUser:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const updateUser = async (req, res) => {
+  try {
+    const { id } = req.params;
+    const { username, email, role } = req.body;
+    await db.query(
+      "UPDATE users SET username = ?, email = ?, role = ? WHERE id = ?",
+      [username, email, role, id]
+    );
+    res.status(200).json({
+      message: "User updated successfully",
+      data: { id, username, email, role },
+    });
+  } catch (error) {
+    console.error("Error in updateUser:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};
+
+export const deleteUser = async (req, res) => {
+  try {
+    const { id } = req.params;
+    await db.query("DELETE FROM users WHERE id = ?", [id]);
+    res.status(200).json({ message: "User deleted successfully" });
+  } catch (error) {
+    console.error("Error in deleteUser:", error);
+    res.status(500).json({ error: "Internal server error" });
+  }
+};

package/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import express from "express";
+import dotenv from "dotenv";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { loggingMiddleware, errorHandler } from "./middlewares/index.js";
+
+dotenv.config();
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Global Middlewares
+app.use(express.json());
+app.use(loggingMiddleware);
+
+/**
+ * Dynamic Route Loader
+ * Automatically registers all route files from the /routes directory
+ */
+const registerRoutes = async () => {
+  const routesPath = path.join(__dirname, "routes");
+  const files = fs.readdirSync(routesPath);
+
+  for (const file of files) {
+    if (file.endsWith(".js")) {
+      const routeName = file.split(".")[0];
+      const routePath = pathToFileURL(path.join(routesPath, file)).href;
+      const { default: router } = await import(routePath);
+      
+      if (router) {
+        app.use(`/api/${routeName}`, router);
+        console.log(`Registered domain: ${routeName} -> /api/${routeName}`);
+      }
+    }
+  }
+};
+
+// Health check
+app.get("/health", (req, res) => {
+  res.json({ status: "ok", service: "spxkth-framework" });
+});
+
+const startServer = async () => {
+  try {
+    await registerRoutes();
+    
+    // Error Handling Middleware (must be last)
+    app.use(errorHandler);
+
+    if (import.meta.url === pathToFileURL(__filename).href || process.argv[1]?.endsWith('spxkth')) {
+      app.listen(PORT, () => {
+        console.log(`Spxkth framework started on port ${PORT}`);
+        console.log(`API available at http://localhost:${PORT}/api`);
+      });
+    }
+  } catch (error) {
+    console.error("Failed to start Spxkth framework:", error);
+    process.exit(1);
+  }
+};
+
+startServer();
+
+export default app;

package/middlewares/index.js

@@ -0,0 +1,47 @@
+import jwt from "jsonwebtoken";
+import dotenv from "dotenv";
+import { db } from "../config/db.js";
+
+dotenv.config();
+
+const JWT_SECRET = process.env.JWT_SECRET || "your-secret-key";
+
+/**
+ * Standardized Auth Middleware
+ * Checks session/token, queries DB for user, and attaches to req.user
+ */
+export const authMiddleware = async (req, res, next) => {
+  try {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return res.status(401).json({ error: "Unauthorized: No token provided" });
+    }
+
+    const token = authHeader.split(" ")[1];
+    const decoded = jwt.verify(token, JWT_SECRET);
+
+    // Standardized DB check for user
+    const [rows] = await db.query("SELECT id, username, email, role FROM users WHERE id = ?", [decoded.id]);
+    
+    if (rows.length === 0) {
+      return res.status(401).json({ error: "Unauthorized: User no longer exists" });
+    }
+
+    req.user = rows[0];
+    next();
+  } catch (error) {
+    console.error("Auth Middleware Error:", error.message);
+    return res.status(403).json({ error: "Forbidden: Invalid or expired token" });
+  }
+};
+
+export const loggingMiddleware = (req, res, next) => {
+  const timestamp = new Date().toISOString();
+  console.log(`[${timestamp}] ${req.method} ${req.url}`);
+  next();
+};
+
+export const errorHandler = (err, req, res, next) => {
+  console.error("Global Error Handler:", err);
+  res.status(500).json({ error: "Internal server error" });
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "spxkth",
+  "version": "1.0.1",
+  "description": "A modular, domain-agnostic Node.js backend framework with universal UI themes.",
+  "author": "spxkth",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "type": "module",
+  "bin": {
+    "spxkth": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js"
+  },
+  "dependencies": {
+    "express": "^4.18.2",
+    "mysql2": "^3.6.0",
+    "dotenv": "^16.3.1",
+    "bcryptjs": "^2.4.3",
+    "jsonwebtoken": "^9.0.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.1.6",
+    "@types/node": "^20.4.5",
+    "@types/express": "^4.17.17"
+  }
+}

package/routes/reports.js

@@ -0,0 +1,10 @@
+import express from "express";
+import { getInventoryReport, getSystemStats } from "../controllers/reportsController.js";
+import { authMiddleware } from "../middlewares/index.js";
+
+const router = express.Router();
+
+router.get("/inventory", authMiddleware, getInventoryReport);
+router.get("/stats", authMiddleware, getSystemStats);
+
+export default router;

package/routes/spareParts.js

@@ -0,0 +1,20 @@
+import express from "express";
+import {
+  createSparePart,
+  listSpareParts,
+  getSparePart,
+  updateSparePart,
+  deleteSparePart,
+} from "../controllers/sparePartsController.js";
+import { authMiddleware } from "../middlewares/index.js";
+
+const router = express.Router();
+
+// RESTful Route Pattern
+router.post("/", authMiddleware, createSparePart);
+router.get("/", authMiddleware, listSpareParts);
+router.get("/:id", authMiddleware, getSparePart);
+router.put("/:id", authMiddleware, updateSparePart);
+router.delete("/:id", authMiddleware, deleteSparePart);
+
+export default router;

package/routes/users.js

@@ -0,0 +1,20 @@
+import express from "express";
+import {
+  createUser,
+  listUsers,
+  getUser,
+  updateUser,
+  deleteUser,
+} from "../controllers/usersController.js";
+import { authMiddleware } from "../middlewares/index.js";
+
+const router = express.Router();
+
+// RESTful Route Pattern
+router.post("/", authMiddleware, createUser);
+router.get("/", authMiddleware, listUsers);
+router.get("/:id", authMiddleware, getUser);
+router.put("/:id", authMiddleware, updateUser);
+router.delete("/:id", authMiddleware, deleteUser);
+
+export default router;

package/themes/DashboardTheme.jsx

@@ -0,0 +1,45 @@
+import React from "react";
+import ThemeWrapper from "./ThemeWrapper";
+
+/**
+ * Universal Dashboard Theme
+ * @param {Object} props.config - { title, description, stats: [], widgets: [], quickLinks, relatedRoutes, relatedTables }
+ */
+const DashboardTheme = ({ config }) => {
+  const { title, description, stats = [], widgets = [], ...wrapperProps } = config;
+
+  return (
+    <ThemeWrapper title={title} description={description} {...wrapperProps}>
+      <div className="space-y-8">
+        {/* Stats Row */}
+        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
+          {stats.map((stat, idx) => (
+            <div key={idx} className="p-6 bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700">
+              <p className="text-sm font-medium text-gray-500 dark:text-gray-400">{stat.label}</p>
+              <h3 className="text-2xl font-bold mt-1">{stat.value}</h3>
+              {stat.trend && (
+                <p className={`text-xs mt-2 ${stat.trend > 0 ? 'text-green-500' : 'text-red-500'}`}>
+                  {stat.trend > 0 ? '↑' : '↓'} {Math.abs(stat.trend)}% from last month
+                </p>
+              )}
+            </div>
+          ))}
+        </div>
+
+        {/* Widgets Grid */}
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+          {widgets.map((widget, idx) => (
+            <div key={idx} className="p-6 bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 min-h-[300px]">
+              <h3 className="text-lg font-bold mb-4">{widget.title}</h3>
+              <div className="flex items-center justify-center h-full text-gray-400 italic">
+                {widget.content || "[Chart/Widget Placeholder]"}
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </ThemeWrapper>
+  );
+};
+
+export default DashboardTheme;

package/themes/DetailTheme.jsx

@@ -0,0 +1,55 @@
+import React from "react";
+import ThemeWrapper from "./ThemeWrapper";
+
+/**
+ * Universal Detail Theme
+ * @param {Object} props.config - { title, description, sections: [], actions: [], quickLinks, relatedRoutes, relatedTables }
+ */
+const DetailTheme = ({ config }) => {
+  const { title, description, sections = [], actions = [], ...wrapperProps } = config;
+
+  return (
+    <ThemeWrapper title={title} description={description} {...wrapperProps}>
+      <div className="space-y-6">
+        {/* Action Bar */}
+        <div className="flex justify-end gap-3">
+          {actions.map((action, idx) => (
+            <button 
+              key={idx} 
+              className={`px-5 py-2 rounded-lg text-sm font-bold transition-all ${
+                action.primary 
+                  ? 'bg-[var(--color-primary)] text-white shadow-md' 
+                  : 'bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700'
+              }`}
+            >
+              {action.label}
+            </button>
+          ))}
+        </div>
+
+        {/* Details Content */}
+        <div className="grid grid-cols-1 gap-6">
+          {sections.map((section, sIdx) => (
+            <div key={sIdx} className="bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 overflow-hidden">
+              <div className="px-6 py-4 border-b border-gray-100 dark:border-gray-700 bg-gray-50/50 dark:bg-gray-900/30">
+                <h3 className="text-lg font-bold">{section.title}</h3>
+              </div>
+              <div className="p-6">
+                <dl className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-y-6 gap-x-8">
+                  {section.items.map((item, iIdx) => (
+                    <div key={iIdx} className="space-y-1">
+                      <dt className="text-xs font-bold text-gray-500 uppercase tracking-wide">{item.label}</dt>
+                      <dd className="text-sm font-medium text-gray-900 dark:text-gray-100">{item.value || "-"}</dd>
+                    </div>
+                  ))}
+                </dl>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </ThemeWrapper>
+  );
+};
+
+export default DetailTheme;

package/themes/FormTheme.jsx

@@ -0,0 +1,58 @@
+import React from "react";
+import ThemeWrapper from "./ThemeWrapper";
+
+/**
+ * Universal Form Theme
+ * @param {Object} props.config - { title, description, fields: [], submitLabel, quickLinks, relatedRoutes, relatedTables }
+ */
+const FormTheme = ({ config }) => {
+  const { title, description, fields = [], submitLabel = "Save Changes", ...wrapperProps } = config;
+
+  return (
+    <ThemeWrapper title={title} description={description} {...wrapperProps}>
+      <div className="max-w-2xl bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 p-8">
+        <form className="space-y-6" onSubmit={(e) => e.preventDefault()}>
+          <div className="grid grid-cols-1 gap-6">
+            {fields.map((field, idx) => (
+              <div key={idx} className="space-y-2">
+                <label className="block text-sm font-bold text-gray-700 dark:text-gray-300">
+                  {field.label} {field.required && <span className="text-red-500">*</span>}
+                </label>
+                {field.type === "textarea" ? (
+                  <textarea 
+                    placeholder={field.placeholder}
+                    className="w-full px-4 py-3 bg-gray-50 dark:bg-gray-900 border border-gray-200 dark:border-gray-700 rounded-xl focus:ring-2 focus:ring-[var(--color-primary)] outline-none min-h-[120px]"
+                  />
+                ) : field.type === "select" ? (
+                  <select className="w-full px-4 py-3 bg-gray-50 dark:bg-gray-900 border border-gray-200 dark:border-gray-700 rounded-xl focus:ring-2 focus:ring-[var(--color-primary)] outline-none">
+                    {field.options?.map((opt, oIdx) => (
+                      <option key={oIdx} value={opt.value}>{opt.label}</option>
+                    ))}
+                  </select>
+                ) : (
+                  <input 
+                    type={field.type || "text"}
+                    placeholder={field.placeholder}
+                    className="w-full px-4 py-3 bg-gray-50 dark:bg-gray-900 border border-gray-200 dark:border-gray-700 rounded-xl focus:ring-2 focus:ring-[var(--color-primary)] outline-none"
+                  />
+                )}
+                {field.helpText && <p className="text-xs text-gray-500">{field.helpText}</p>}
+              </div>
+            ))}
+          </div>
+
+          <div className="pt-4 flex gap-4">
+            <button type="submit" className="px-8 py-3 bg-[var(--color-primary)] text-white font-bold rounded-xl shadow-lg hover:brightness-110 transition-all">
+              {submitLabel}
+            </button>
+            <button type="button" className="px-8 py-3 bg-gray-100 dark:bg-gray-700 text-gray-700 dark:text-gray-200 font-bold rounded-xl hover:bg-gray-200 transition-all">
+              Cancel
+            </button>
+          </div>
+        </form>
+      </div>
+    </ThemeWrapper>
+  );
+};
+
+export default FormTheme;

package/themes/ListTheme.jsx

@@ -0,0 +1,75 @@
+import React from "react";
+import ThemeWrapper from "./ThemeWrapper";
+
+/**
+ * Universal List Theme
+ * @param {Object} props.config - { title, description, columns: [], data: [], actions: [], quickLinks, relatedRoutes, relatedTables }
+ */
+const ListTheme = ({ config }) => {
+  const { title, description, columns = [], data = [], actions = [], ...wrapperProps } = config;
+
+  return (
+    <ThemeWrapper title={title} description={description} {...wrapperProps}>
+      <div className="bg-white dark:bg-gray-800 rounded-2xl shadow-sm border border-gray-100 dark:border-gray-700 overflow-hidden">
+        {/* Table Toolbar */}
+        <div className="p-4 border-b border-gray-100 dark:border-gray-700 flex justify-between items-center">
+          <input 
+            type="text" 
+            placeholder="Search..." 
+            className="px-4 py-2 bg-gray-50 dark:bg-gray-900 border border-gray-200 dark:border-gray-700 rounded-lg text-sm w-64"
+          />
+          <div className="flex gap-2">
+            <button className="px-4 py-2 text-sm font-medium bg-gray-100 dark:bg-gray-700 rounded-lg">Filter</button>
+            <button className="px-4 py-2 text-sm font-medium bg-[var(--color-primary)] text-white rounded-lg">Export</button>
+          </div>
+        </div>
+
+        {/* Responsive Table */}
+        <div className="overflow-x-auto">
+          <table className="w-full text-left border-collapse">
+            <thead>
+              <tr className="bg-gray-50 dark:bg-gray-900/50">
+                {columns.map((col, idx) => (
+                  <th key={idx} className="px-6 py-4 text-xs font-bold text-gray-500 uppercase tracking-wider">
+                    {col.header}
+                  </th>
+                ))}
+                {actions.length > 0 && <th className="px-6 py-4 text-xs font-bold text-gray-500 uppercase tracking-wider text-right">Actions</th>}
+              </tr>
+            </thead>
+            <tbody className="divide-y divide-gray-100 dark:divide-gray-700">
+              {data.length > 0 ? data.map((row, rowIdx) => (
+                <tr key={rowIdx} className="hover:bg-gray-50 dark:hover:bg-gray-900/30 transition-colors">
+                  {columns.map((col, colIdx) => (
+                    <td key={colIdx} className="px-6 py-4 text-sm">
+                      {row[col.key] || "-"}
+                    </td>
+                  ))}
+                  {actions.length > 0 && (
+                    <td className="px-6 py-4 text-sm text-right">
+                      <div className="flex justify-end gap-3">
+                        {actions.map((action, actIdx) => (
+                          <button key={actIdx} className="text-[var(--color-primary)] hover:underline font-medium">
+                            {action.label}
+                          </button>
+                        ))}
+                      </div>
+                    </td>
+                  )}
+                </tr>
+              )) : (
+                <tr>
+                  <td colSpan={columns.length + (actions.length > 0 ? 1 : 0)} className="px-6 py-12 text-center text-gray-400 italic">
+                    No records found.
+                  </td>
+                </tr>
+              )}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </ThemeWrapper>
+  );
+};
+
+export default ListTheme;

package/themes/ThemeWrapper.jsx

@@ -0,0 +1,102 @@
+import React from "react";
+import { Link } from "react-router-dom";
+
+/**
+ * Universal Theme Wrapper Component
+ * 
+ * @param {Object} props
+ * @param {string} props.title - Page title
+ * @param {string} props.description - Page description
+ * @param {Array} props.quickLinks - [{ label, to }]
+ * @param {Array} props.relatedRoutes - [{ method, path, description }]
+ * @param {Array} props.relatedTables - [{ name, purpose }]
+ * @param {React.ReactNode} props.children - Main content of the theme
+ */
+const ThemeWrapper = ({ 
+  title, 
+  description, 
+  quickLinks = [], 
+  relatedRoutes = [], 
+  relatedTables = [], 
+  children 
+}) => {
+  return (
+    <section className="p-8 space-y-8 bg-[var(--color-surface)] min-h-screen font-sans text-gray-900 dark:text-gray-100">
+      {/* Header Section */}
+      <header className="space-y-2">
+        <h1 className="text-4xl font-extrabold tracking-tight text-[var(--color-primary)]">{title}</h1>
+        <p className="text-lg text-gray-600 dark:text-gray-400 max-w-3xl">{description}</p>
+      </header>
+
+      {/* Quick Links Section */}
+      {quickLinks.length > 0 && (
+        <nav className="flex flex-wrap gap-3">
+          {quickLinks.map((link, index) => (
+            <Link
+              key={index}
+              to={link.to}
+              className="px-5 py-2.5 bg-[var(--color-primary)] text-white rounded-full text-sm font-semibold shadow-sm hover:brightness-110 transition-all active:scale-95"
+            >
+              {link.label}
+            </Link>
+          ))}
+        </nav>
+      )}
+
+      {/* Main Content Area */}
+      <main className="w-full">
+        {children}
+      </main>
+
+      {/* Metadata Grid */}
+      <footer className="grid grid-cols-1 md:grid-cols-2 gap-8 pt-8 border-t border-gray-200 dark:border-gray-800">
+        {/* Related Routes */}
+        <div className="space-y-4">
+          <h2 className="text-xl font-bold flex items-center gap-2">
+            <span className="w-1.5 h-6 bg-blue-500 rounded-full"></span>
+            Developer Routes
+          </h2>
+          <div className="grid gap-3">
+            {relatedRoutes.length > 0 ? (
+              relatedRoutes.map((route, index) => (
+                <div key={index} className="p-4 bg-gray-50 dark:bg-gray-900/50 rounded-xl border border-gray-100 dark:border-gray-800">
+                  <div className="flex items-center gap-3 mb-1">
+                    <span className="text-[10px] font-black px-2 py-0.5 bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-400 rounded-md uppercase">
+                      {route.method}
+                    </span>
+                    <code className="text-xs font-mono text-gray-700 dark:text-gray-300">{route.path}</code>
+                  </div>
+                  <p className="text-xs text-gray-500 dark:text-gray-400">{route.description}</p>
+                </div>
+              ))
+            ) : (
+              <p className="text-sm text-gray-400 italic">No associated routes.</p>
+            )}
+          </div>
+        </div>
+
+        {/* Related Tables */}
+        <div className="space-y-4">
+          <h2 className="text-xl font-bold flex items-center gap-2">
+            <span className="w-1.5 h-6 bg-purple-500 rounded-full"></span>
+            Data Sources
+          </h2>
+          <div className="grid gap-3">
+            {relatedTables.length > 0 ? (
+              relatedTables.map((table, index) => (
+                <div key={index} className="p-4 bg-gray-50 dark:bg-gray-900/50 rounded-xl border border-gray-100 dark:border-gray-800">
+                  <h3 className="text-sm font-bold text-gray-800 dark:text-gray-200">{table.name}</h3>
+                  <p className="text-xs text-gray-500 dark:text-gray-400">{table.purpose}</p>
+                </div>
+              ))
+            ) : (
+              <p className="text-sm text-gray-400 italic">No associated tables.</p>
+            )}
+          </div>
+        </div>
+      </footer>
+    </section>
+  );
+};
+
+export default ThemeWrapper;

package/themes/index.js

@@ -0,0 +1,5 @@
+export { default as DashboardTheme } from "./DashboardTheme.jsx";
+export { default as ListTheme } from "./ListTheme.jsx";
+export { default as FormTheme } from "./FormTheme.jsx";
+export { default as DetailTheme } from "./DetailTheme.jsx";
+export { default as ThemeWrapper } from "./ThemeWrapper.jsx";