nibula 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to Nibula are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- **Node.js backend** as an alternative to PHP, living side by side in
+  `src/backend/`: `_core/index.js` front controller (which is also the HTTP
+  server), `Response` and `RateLimiter` modules, a `mysql2` pool singleton
+  `Database.js`, `example.config.js`, and a `package.json` for the backend's
+  own dependencies. Same REST API as PHP: routing, `X-Api-Key` auth, CORS and
+  file-based rate limiting are identical.
+- **Backend choice at scaffold time**: `nib new` now asks whether to use Node.js
+  or PHP, in addition to language and CSS framework.
+- `backend/backend-node.service.example` — a ready-to-adapt **systemd** unit for
+  keeping the Node backend running on a server.
+- `config.js` is generated from `example.config.js` at scaffold time (mirroring
+  the existing `config.php` generation).
+- Deployment docs now cover running the Node backend with **`screen`** (quick /
+  small setups) and **systemd** (production), plus environment variables.
+
+### Changed
+- **Composer is now required only when the PHP backend is chosen.** If you pick
+  Node, `composer install` is skipped entirely and the backend's npm
+  dependencies (`mysql2`) are installed instead.
+- `.htaccess`, `web.config` and `nginx.conf` now cover **both** backends. On
+  nginx, `/api` goes to Node and automatically falls back to the PHP front
+  controller when Node is unreachable. On Apache/IIS the active backend is
+  selected by configuration (documented), since per-directory configs can't
+  health-check an upstream.
+- `.gitignore` now also ignores `src/backend/config.js`,
+  `src/backend/node_modules/` and `src/backend/cache/`.
+- Documentation (`README.md`, `docs/Backend.md`, `docs/Deploy.md`) updated:
+  backend examples now use JavaScript/Node as the reference, with the equivalent
+  PHP shown alongside and a note that PHP behaves identically.
+
+### Notes
+- Both backends are always scaffolded, so you can switch later without
+  re-creating the project. The PHP front controller only serves `.php` endpoint
+  files and the Node one only `.js`, so they coexist without conflict.
+
+## [1.0.2]
+
+- Previous release (PHP backend only).
+
+[1.1.0]: https://github.com/Rhaastrake/Nibula/releases/tag/v1.1.0
+[1.0.2]: https://github.com/Rhaastrake/Nibula/releases/tag/v1.0.2

package/README.md

@@ -16,11 +16,12 @@ Building a website from scratch involves a lot of moving parts: templating, buil
 - 🖱️ **A helpful CLI** — create a page with one command instead of hand-writing ten separate files
 - ⚙️ **Server configs handled for you** — `.htaccess` and `web.config` are generated automatically, and an `nginx.conf` is provided so that anyone comfortable with nginx already has what they need to run the site outside of shared hosting
 - 🎨 **Pick your CSS framework** — choose from 4 pre-installed options (or none), and switch later in a few guided steps
+- 🔌 **Pick your backend** — Node.js or PHP, chosen at creation; **Composer is only needed for PHP**
 - 🧩 **Your own modules** — add your own CSS and JS/TS modules freely and easily
 - 🪶 **Lightweight by default** — SCSS frameworks can be filtered so you ship only what you actually use
 - 🌍 **Open source** — free to use, free to modify, free to share
 
-![Version](https://img.shields.io/badge/version-1.0.2-blue)
+![Version](https://img.shields.io/badge/version-1.1.1-blue)
 ![License](https://img.shields.io/badge/license-Apache--2.0-blue)
 ![Eleventy](https://img.shields.io/badge/11ty-v3.1.2-black)
 
@@ -35,7 +36,7 @@ Either way, the project structure stays the same, so you can start easy and leve
 
 ## Backend included
 
-Essential server-side functionality comes built in — no extra setup required. Backend support will soon let you **choose between PHP, Node, and Python**, so the project can grow with you.
+Essential server-side functionality comes built in — no extra setup required. At project creation you **choose your backend: Node.js or PHP** (Python is planned). Both expose the **same REST API** — same routing, `X-Api-Key` auth, CORS and rate limiting — so you can even switch later without rewriting your endpoints. See [docs/Backend.md](docs/Backend.md) for details.
 
 ## Customizable, but with sensible defaults
 
@@ -43,8 +44,8 @@ Nibula ships with a clean, opinionated layout so beginners are never lost. But i
 
 ## Prerequisites
 
-* **Node.js**: v18.0.0 or higher
-* **Composer**: latest stable version
+* **Node.js**: v18.0.0 or higher — **always required** (the Nibula CLI, the build, and the optional Node backend all run on Node)
+* **Composer**: **only required if you choose the PHP backend**, to install its PHP dependencies. If you pick the **Node** backend, Composer is never used — you can skip installing it entirely.
 * *Optional:* the **Better Nunjucks** VS Code extension by Ed Heltzel
 
 ## Installation
@@ -65,7 +66,7 @@ From the folder where you keep your websites, run:
 nib new your-project
 ```
 
-The scaffolder is interactive: you choose the language (JavaScript/TypeScript) and the CSS framework, and all dependencies are installed automatically.
+The scaffolder is interactive: you choose the **language** (JavaScript/TypeScript), the **CSS framework**, and the **backend** (Node.js or PHP). All dependencies are installed automatically — and if you pick **Node**, the PHP/Composer step is skipped, so you don't need Composer at all.
 
 Then start the dev server and visit `localhost:8080`:
 
@@ -99,7 +100,20 @@ nib cli
 
 See [docs/Assistant CLI.md](docs/Assistant%20CLI.md) for details.
 
+## Deploying
+
+Nibula builds a static site into your `out` folder, which you upload to a web
+server. Which backend you chose affects deployment:
+
+- **PHP** runs on ordinary shared hosting (Apache/IIS) or a VPS with PHP-FPM — no process to keep alive.
+- **Node** runs as a long-running service on a VPS; the web server reverse-proxies `/api` to it.
+
+The shipped `.htaccess`, `web.config` and `nginx.conf` cover **both** backends.
+See [docs/Deploy.md](docs/Deploy.md) for the full guide, including how to start
+the Node service on your server.
+
 ## Roadmap
 
 * [ ] Add support for multiple themes
-* [ ] Backend integration choice — switch between PHP, Python, or Node
+* [x] Backend integration choice — pick **PHP or Node.js** at creation (Python planned)
+* [ ] Extend documentation with advanced usage examples

package/bin/create.js

@@ -28,10 +28,15 @@ const FRAMEWORK = Object.freeze({
     NONE:       'none',
 });
 
+const BACKEND = Object.freeze({
+    NODE: 'node',
+    PHP:  'php',
+});
+
 // ── CHOICES ──────────────────────────────────────────────────────────────────
 
 const LANGUAGE_CHOICES = [
-    { label: 'JavaScript (recomened)', value: LANGUAGE.JAVASCRIPT },
+    { label: 'JavaScript (recomended)', value: LANGUAGE.JAVASCRIPT },
     { label: 'TypeScript',           value: LANGUAGE.TYPESCRIPT },
 ];
 
@@ -43,6 +48,17 @@ const FRAMEWORK_CHOICES = [
     { label: 'None',                value: FRAMEWORK.NONE       },
 ];
 
+const BACKEND_CHOICES = [
+    { label: 'Node.js (index.js — no PHP, no Composer)', value: BACKEND.NODE },
+    { label: 'PHP (index.php — Composer dependencies)',  value: BACKEND.PHP  },
+];
+
+// Runtime dependency added to the ROOT package.json when the Node backend is
+// chosen, so it lands in the root node_modules (never in src/backend).
+const NODE_BACKEND_DEPENDENCIES = {
+    mysql2: '^3.11.0',
+};
+
 // ── COPY CONFIG ───────────────────────────────────────────────────────────────
 
 const MANDATORY_COPY = [
@@ -62,6 +78,14 @@ const CREATE_DIRS = [
     'src/frontend/_routes',
 ];
 
+// Backend files that belong to exactly one backend, matched by basename.
+// Everything else (migrations, .htaccess, web.config, README, ...) is shared.
+const NODE_ONLY_FILES = new Set(['package.json', 'backend-node.service.example']);
+const PHP_ONLY_FILES  = new Set(['composer.json', 'composer.lock']);
+const PHP_ONLY_DIRS   = new Set(['vendor']);
+// Runtime artifacts that must never be copied from the template, either way.
+const BACKEND_SKIP_DIRS = new Set(['node_modules', 'cache', '.git']);
+
 // ── FRAMEWORK CONFIG ──────────────────────────────────────────────────────────
 
 const ALL_FRAMEWORKS = Object.values(FRAMEWORK).filter(f => f !== FRAMEWORK.NONE);
@@ -117,6 +141,8 @@ node_modules/
 src/backend/_core/vendor/
 out/
 src/backend/config.php
+src/backend/config.js
+src/backend/cache/
 `;
 
 
@@ -185,6 +211,48 @@ function copyRecursive(src, dest, exclude = []) {
     }
 }
 
+/**
+ * Decide whether a backend entry belongs to the chosen backend.
+ * Returns false for entries that must be SKIPPED.
+ */
+function backendEntryKept(basename, isDir, backend) {
+    // Never copy runtime artifacts from the template.
+    if (isDir && BACKEND_SKIP_DIRS.has(basename)) return false;
+
+    if (backend === BACKEND.NODE) {
+        // Node project: drop every PHP artifact.
+        if (basename.endsWith('.php')) return false;
+        if (PHP_ONLY_FILES.has(basename)) return false;
+        if (isDir && PHP_ONLY_DIRS.has(basename)) return false;
+        return true;
+    }
+
+    // PHP project: drop every Node artifact.
+    if (basename.endsWith('.js')) return false;
+    if (NODE_ONLY_FILES.has(basename)) return false;
+    return true;
+}
+
+/**
+ * Copy src/backend into the project keeping only the chosen backend's files.
+ * Shared files (SQL migrations, .htaccess, web.config, README, ...) are kept
+ * for both. Empty directories left behind by filtering are not created.
+ */
+function copyBackend(src, dest, backend) {
+    const stat = fs.statSync(src);
+    if (stat.isDirectory()) {
+        for (const child of fs.readdirSync(src)) {
+            const childSrc = path.join(src, child);
+            const isDir    = fs.statSync(childSrc).isDirectory();
+            if (!backendEntryKept(child, isDir, backend)) continue;
+            copyBackend(childSrc, path.join(dest, child), backend);
+        }
+    } else {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(src, dest);
+    }
+}
+
 function slashComment(content, line) {
     content = content.replace(new RegExp(`^([ \\t]*)// (${escapeRegex(line)})$`, 'gm'), '$1$2');
     return content.replace(new RegExp(`^([ \\t]*)(${escapeRegex(line)})$`, 'gm'), '$1// $2');
@@ -203,7 +271,7 @@ function njkUncomment(content, line) {
     return content.split(`{# ${line} #}`).join(line);
 }
 
-function installDependencies() {
+function installDependencies(backend) {
     const backendCore = path.join(targetDir, 'src', 'backend', '_core');
 
     log(`${color.blue}\n>> Installing Node modules...${color.reset}`);
@@ -220,6 +288,14 @@ function installDependencies() {
         return false;
     }
 
+    // Node backend: its runtime deps were added to the ROOT package.json and
+    // installed above into the root node_modules — there is no separate install
+    // inside src/backend, and Composer is never run.
+    if (backend === BACKEND.NODE) {
+        return true;
+    }
+
+    // --- PHP backend: install Composer dependencies (if present) ---
     if (!fs.existsSync(path.join(backendCore, 'composer.json'))) {
         return true;
     }
@@ -353,6 +429,7 @@ async function init() {
 
     const language  = await askChoice('Select a language',      LANGUAGE_CHOICES);
     const framework = await askChoice('Select a CSS framework', FRAMEWORK_CHOICES);
+    const backend   = await askChoice('Select a backend',       BACKEND_CHOICES);
 
     log('');
 
@@ -360,11 +437,19 @@ async function init() {
         const src  = path.join(templateDir, target);
         const dest = path.join(targetDir, target);
         if (!fs.existsSync(src)) continue;
-        const exclude = target === 'src/frontend' ? FRONTEND_EXCLUDE[language] : [];
-        copyRecursive(src, dest, exclude);
+
+        if (target === 'src/backend') {
+            // Copy only the chosen backend's files (the other backend is omitted).
+            copyBackend(src, dest, backend);
+        } else {
+            const exclude = target === 'src/frontend' ? FRONTEND_EXCLUDE[language] : [];
+            copyRecursive(src, dest, exclude);
+        }
         logAdd(target);
     }
 
+    // Generate the local config only for the chosen backend. The other backend's
+    // example file was not copied, so its guard below is simply skipped.
     const configDest    = path.join(targetDir, 'src/backend/config.php');
     const configExample = path.join(targetDir, 'src/backend/example.config.php');
     if (!fs.existsSync(configDest) && fs.existsSync(configExample)) {
@@ -372,7 +457,24 @@ async function init() {
         logAdd('src/backend/config.php');
     }
 
+    const configJsDest    = path.join(targetDir, 'src/backend/config.js');
+    const configJsExample = path.join(targetDir, 'src/backend/example.config.js');
+    if (!fs.existsSync(configJsDest) && fs.existsSync(configJsExample)) {
+        fs.copyFileSync(configJsExample, configJsDest);
+        logAdd('src/backend/config.js');
+    }
+
+    // Build the project package.json. Clone the shared dependency maps so we
+    // never mutate the PROJECT_PACKAGE constant.
     const pkg = { ...PROJECT_PACKAGE };
+    pkg.dependencies    = { ...PROJECT_PACKAGE.dependencies };
+    pkg.devDependencies = { ...PROJECT_PACKAGE.devDependencies };
+
+    // Node backend deps live in the ROOT node_modules — add them to root deps
+    // so `npm install` installs them there (never in src/backend).
+    if (backend === BACKEND.NODE) {
+        pkg.dependencies = { ...pkg.dependencies, ...NODE_BACKEND_DEPENDENCIES };
+    }
 
     if (language === LANGUAGE.TYPESCRIPT) {
         const tsSrc  = path.join(templateDir, 'tsconfig.json');
@@ -395,7 +497,7 @@ async function init() {
     applyFramework(framework);
     applyLanguage(language);
 
-    installDependencies();
+    installDependencies(backend);
 
     log(`\n${color.green}>> Done!${color.reset}`);
     log(`${color.yellow}\nNow run:\n${color.reset}`);

package/docs/Backend.md

@@ -1,46 +1,98 @@
 # Backend
 
-> **PHP requirement** — the backend runs only on servers with PHP support:
-> - **Apache** (shared hosting, VPS) ✅
-> - **Nginx** + PHP-FPM (VPS) ✅
-> - **IIS** + FastCGI (Windows Server) ✅
-> - **Static hosting** (Netlify, Vercel, GitHub Pages, Cloudflare Pages) ❌
-
-The backend is a PHP REST API located in `src/backend/`, copied to the output directory automatically at build time.
+Nibula ships **two interchangeable backends** in `src/backend/` — a **PHP** one
+and a **Node.js** one. You pick which to use when you scaffold a project
+(`nib new`). Both provide the same REST API: same routing, same `Response`
+envelope, same `X-Api-Key` auth, same CORS model, same file-based rate limiter.
+Only the language differs.
+
+> **Server requirement** — where each backend can run:
+>
+> | Host | PHP | Node.js |
+> |---|---|---|
+> | Apache (shared hosting, VPS) | ✅ | ⚠️ needs a persistent process (VPS only) |
+> | Nginx + PHP-FPM (VPS) | ✅ | ✅ (Nginx reverse-proxies to Node) |
+> | IIS (Windows Server) | ✅ FastCGI | ✅ via ARR reverse proxy |
+> | Static hosting (Netlify, Vercel, GitHub Pages, Cloudflare Pages) | ❌ | ❌ |
+>
+> Typical shared hosting can run **PHP** but not a long-running Node process, so
+> choose PHP there. On a VPS you control, either works.
+
+The backend lives in `src/backend/` and is copied to the output directory
+automatically at build time.
+
+## Choosing a backend
+
+When you run `nib new`, the scaffolder asks three questions: language, CSS
+framework, and **backend**. Pick Node.js or PHP.
+
+- **If you pick Node**, Composer is never run — you get an npm-only setup, and
+  the backend's dependency (`mysql2`, used only if you touch the database) is
+  added to the **root** `package.json` and installed into the root `node_modules`.
+- **If you pick PHP**, Composer dependencies are installed as before, and no Node
+  backend files are added.
+
+**Only the backend you choose is copied into the project.** A Node project
+contains no PHP files; a PHP project contains no `.js` backend files. Shared,
+backend-agnostic files (SQL migrations, `.htaccess`, `web.config`) are always
+included.
 
 ## Structure
 
+The structure below shows both backends for reference; **your project will have
+only one side of each pair** (plus the shared files).
+
 ```
 src/backend/
 ├── api/
-│   └── protected/    # Endpoints requiring X-Api-Key header
 │   ├── public/       # Endpoints accessible without an API key
+│   └── protected/    # Endpoints requiring the X-Api-Key header
 ├── _core/            # Framework internals (routing, modules) — do not edit
-│   └── modules/      # Response, RateLimiter, ...
+│   ├── index.php     # PHP front controller            (PHP project)
+│   ├── index.js      # Node front controller + server   (Node project)
+│   ├── init.php / init.js
+│   └── modules/      # Response, RateLimiter
 ├── database/
-│   ├── Database.php
-│   └── migrations/
-├── example.config.php   # Template — versioned, safe to commit
-└── config.php           # Your local config, generated on setup — never commit this
+│   ├── Database.php  # PDO singleton                    (PHP project)
+│   ├── Database.js   # mysql2 pool singleton            (Node project)
+│   └── migrations/   # shared
+├── package.json          # Node project only — backend deps + start script
+├── example.config.php    # PHP project only  — versioned template
+├── example.config.js     # Node project only — versioned template
+├── config.php            # PHP project only  — generated on setup, never commit
+└── config.js             # Node project only — generated on setup, never commit
 ```
 
-> A scaffolded project contains **both** files. `config.php` is generated automatically by `nib new` (a copy of the example) and is git-ignored, so your secrets stay local and are never pushed. `example.config.php` is kept and versioned: it's the file that ends up on GitHub, acting as a secret-free reference so anyone cloning the project knows which keys to set. If `config.php` is ever missing (e.g. after a fresh clone), just copy `example.config.php` to `config.php`.
+> `config.php` / `config.js` are generated automatically by `nib new` (a copy of
+> the matching `example.config.*`) and are git-ignored, so your secrets stay
+> local. The `example.config.*` file is versioned as a secret-free reference. If
+> `config.*` is ever missing (e.g. after a fresh clone), copy the example to it.
 
-> Note: in the boilerplate repo itself, only `example.config.php` exists — `config.php` is created at scaffold time, not shipped.
+> **Where do the Node backend's dependencies live?** In the **root**
+> `node_modules`, not in `src/backend` — so your source tree stays clean (no
+> `src/backend/node_modules` locally). On the server you install them into
+> `out/backend` instead; see `docs/Deploy.md`.
 
-## Configuration
+## Key difference: how each backend runs
 
-`config.php` works like a `.env` file — it holds secrets and environment settings that stay local and out of version control.
+- **PHP** is executed **per request** by the web server through PHP-FPM (or
+  FastCGI/mod_php). There is no process to keep alive.
+- **Node** is a **long-running process** that *is* the server, listening on
+  `127.0.0.1:3000`. The web server (Nginx/Apache/IIS) **reverse-proxies** `/api`
+  to it. You start it once and keep it alive (systemd/pm2). See `docs/Deploy.md`.
 
-Fill in your values:
+## Configuration
+
+`config.php` / `config.js` work like a `.env` file — they hold secrets and
+environment settings that stay local and out of version control. Same keys in
+both, just PHP-array vs JS-object syntax.
 
 ### config.php <small>(`src/backend/`)</small>
 ```php
-// Default key for protected endpoints that don't have a specific key in CUSTOM_ENDPOINT_KEYS
+// Default key for protected endpoints without a specific key in CUSTOM_ENDPOINT_KEYS
 'GENERAL_API_KEY' => 'DEFAULT_KEY',
 
-// If you want restrict access to protected endpoints to specific clients, you can define custom keys for each endpoint
-// For subfolder endpoints, use the relative path ('subfolder/endpoint')
+// Per-endpoint keys. For subfolder endpoints use the relative path ('subfolder/endpoint')
 'CUSTOM_ENDPOINT_KEYS' => [
     'subfolder/endpoint'    => 'custom-key',
 ],
@@ -61,39 +113,100 @@ Fill in your values:
 'DB_PASS' => '',
 ```
 
+### config.js <small>(`src/backend/`)</small>
+```js
+module.exports = {
+    GENERAL_API_KEY: 'DEFAULT_KEY',
+    CUSTOM_ENDPOINT_KEYS: {
+        'subfolder/endpoint': 'custom-key',
+    },
+    GENERAL_ALLOWED_ORIGINS: ['*' /*, 'https://example.com' */],
+    CUSTOM_ENDPOINT_ORIGINS: {
+        'subfolder/endpoint': ['https://app.example.com'],
+    },
+    DB_HOST: '127.0.0.1',
+    DB_NAME: 'example_db',
+    DB_USER: 'root',
+    DB_PASS: '',
+    APP_ENV: 'production', // anything other than 'production' = verbose errors
+};
+```
+
 ### API keys
 
-`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use `CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for subfolder endpoints, use the relative path as the key.
+`GENERAL_API_KEY` is the fallback key for all protected endpoints. Use
+`CUSTOM_ENDPOINT_KEYS` to assign a different key to a specific endpoint — for
+subfolder endpoints, use the relative path as the key.
 
-> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only for server-to-server calls over HTTPS. Never embed it in frontend code, where it would be publicly visible.
+> ⚠️ The API key travels in the `X-Api-Key` header on every request. Use it only
+> for server-to-server calls over HTTPS. Never embed it in frontend code, where
+> it would be publicly visible.
 
 ### CORS (allowed origins)
 
 Cross-origin access mirrors the API-key model:
 
-- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any endpoint from a browser.
-- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint, keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
+- `GENERAL_ALLOWED_ORIGINS` — the default list of origins allowed to call any
+  endpoint from a browser.
+- `CUSTOM_ENDPOINT_ORIGINS` — overrides the default for a specific endpoint,
+  keyed by the same relative path used in `CUSTOM_ENDPOINT_KEYS`.
 
-Origins must be exact (scheme + host, no trailing slash), e.g. `https://example.com`. When a request's `Origin` is in the resolved list, it is reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty list sends no CORS header — the most restrictive setting; same-origin requests still work. Use `'*'` as the only element to allow any origin (not recommended for protected endpoints).
+Origins must be exact (scheme + host, no trailing slash), e.g.
+`https://example.com`. When a request's `Origin` is in the resolved list, it is
+reflected back in `Access-Control-Allow-Origin` (with `Vary: Origin`). An empty
+list sends no CORS header — the most restrictive setting; same-origin requests
+still work. Use `'*'` as the only element to allow any origin (not recommended
+for protected endpoints).
 
-Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if present, otherwise `GENERAL_ALLOWED_ORIGINS`.
+Resolution order for a given endpoint: `CUSTOM_ENDPOINT_ORIGINS[path]` if
+present, otherwise `GENERAL_ALLOWED_ORIGINS`.
 
 ## How routing works
 
-The file path inside `api/` maps directly to the URL. Extra URL segments become route parameters available as `$requestParams[]`.
+The file path inside `api/` maps directly to the URL. The `public`/`protected`
+folder does **not** appear in the URL — it only decides whether the `X-Api-Key`
+check applies. So `api/public/example-public` and `api/protected/example-protected`
+are both reached at `/api/<endpoint>`:
+
+- `api/public/example-public` → `/api/example-public` (no key)
+- `api/protected/example-protected` → `/api/example-protected` (requires key)
 
-Every endpoint file has access to:
+Subfolders **do** appear: `api/public/users/list` → `/api/users/list`. Extra URL
+segments become route parameters. Every endpoint has access to:
 
-| Variable | Description |
+| Variable / field | Description |
 |---|---|
-| `$method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
-| `$requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
+| `method` | HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) |
+| `requestParams` | Extra URL segments (e.g. `/api/posts/42` → `['42']`) |
+
+> If two files share the same path — one in `public/`, one in `protected/` — the
+> public one wins (it is checked first), so the endpoint ends up **without**
+> authentication. Don't duplicate names across the two folders.
+
+> **About the examples below** — the code samples use **JavaScript (the Node
+> backend)** as the reference. That's just the example language: if you chose the
+> **PHP** backend it works exactly the same way, with the same variables, the
+> same `Response` helper and the same behaviour — only the syntax differs. Each
+> section shows the JS version first, with the equivalent PHP right after.
 
 ## Creating a public endpoint
 
-Create a `.php` file anywhere inside `api/public/`
+Create a file anywhere inside `api/public/`.
+
+### `api/public/example.js` (Node — reference)
+```js
+module.exports = ({ method, requestParams, Response }) => {
+    if (method !== 'GET') Response.error('Method not allowed', 405);
+    const id = requestParams[0] ? parseInt(requestParams[0], 10) : null;
+    Response.success({ id });
+};
+```
+
+The Node handler receives a context object: `method`, `requestParams`,
+`Response` (`.success` / `.error` / `.noContent`), plus `query`, `body` (parsed
+JSON), `rawBody`, `headers`, `config`, `req`, `res`.
 
-### api/public/example.php
+The same endpoint in PHP — identical logic, PHP syntax:
 ```php
 <?php
 declare(strict_types=1);
@@ -111,9 +224,18 @@ Response::success(['id' => $id]);
 
 ## Creating a protected endpoint
 
-Create a `.php` file inside `api/protected/`. The API key check happens automatically before your file runs.
+Create a file inside `api/protected/`. The API-key check happens automatically
+before your file runs.
+
+### `api/protected/example.js` (Node — reference)
+```js
+module.exports = ({ method, Response }) => {
+    if (method !== 'GET') Response.error('Method not allowed', 405);
+    Response.success({ visits: 1024 });
+};
+```
 
-### api/protected/example.php
+The same endpoint in PHP:
 ```php
 <?php
 declare(strict_types=1);
@@ -127,25 +249,48 @@ if ($method !== 'GET') {
 Response::success(['visits' => 1024]);
 ```
 
-To assign a dedicated key, add it to `config.php`:
+To assign a dedicated key, add it to your config:
 
+```js
+CUSTOM_ENDPOINT_KEYS: { 'endpoint': 'custom-key' }          // config.js
+```
 ```php
-'CUSTOM_ENDPOINT_KEYS' => [
-    'endpoint' => 'custom-key',
-],
+'CUSTOM_ENDPOINT_KEYS' => [ 'endpoint' => 'custom-key' ],   // config.php
 ```
 
 ## The Response helper
 
+Identical envelope in both backends — JS shown as reference, PHP works the same:
+
+```js
+Response.success(data, code);            // default 200
+Response.error(message, code, details);  // default 400
+Response.noContent();                    // 204
+```
 ```php
 Response::success($data, $code);            // default 200
 Response::error($message, $code, $details); // default 400
-Response::noContent();                      // 204
+Response::noContent();                       // 204
 ```
 
+Response shapes:
+- success → `{ "status": "success", "data": ... }`
+- error → `{ "status": "error", "message": "...", "code": ... }` (+ optional `details`)
+
+## Database
+
+Both backends expose a connection singleton reading the same config.
+
+- **Node** (reference) — `database/Database.js`, a `mysql2` pool singleton:
+  `const pool = Database.getInstance(); const [rows] = await pool.execute(sql, params);`
+  The `mysql2` driver is installed at scaffold time when you choose Node (it is
+  loaded lazily, so the backend also boots fine without a database).
+- **PHP** — `database/Database.php`, a PDO singleton:
+  `$pdo = Database::getInstance();`
+
 ## Pre-built endpoints
 
 | Route | Method | Description |
 |---|---|---|
-| `/api/public/example-public` | `GET` | Example endpoint that doesn't require any key |
-| `/api/protected/example-protected` | `GET` | Example endpoint that requires X-API-KEY |
+| `/api/example-public` | `GET` | Example endpoint that doesn't require any key |
+| `/api/example-protected` | `GET` | Example endpoint that requires `X-Api-Key` |