vortez 5.0.0-dev.18 → 5.0.0

package/README.md

@@ -1,52 +1,310 @@
-# 🚀 Vortez
+# Vortez
+
+A lightweight, production-ready Node.js web framework for building APIs, websites, single-page applications (SPAs), and progressive web apps (PWAs). Built with TypeScript and designed for simplicity without sacrificing power.
+
+The package exports a default `Vortez` server class, plus named exports for `Router`, `Config`, `Template`, `Utilities`, `ServerError`, `Logger`, and `Beta`.
+
+[![npm version](https://img.shields.io/npm/v/vortez?style=flat-square)](https://www.npmjs.com/package/vortez)
+[![License](https://img.shields.io/npm/l/vortez?style=flat-square)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D%2016.0.0-brightgreen?style=flat-square)](https://nodejs.org/)
+
+## Features
+
+- 🚀 **Fast and Lightweight** — Minimal overhead, maximum performance
+- 📦 **Built with TypeScript** — Full type safety with compiled JavaScript output
+- 🔄 **Flexible Routing** — Pattern-based routing with wildcards and dynamic parameters
+- 🔌 **WebSocket Support** — Real-time bidirectional communication out of the box
+- 🛡️ **HTTPS/SSL Ready** — Secure connections with easy configuration
+- 🎯 **Middleware Pipeline** — Composable, snapshot-based middleware system
+- 📝 **Request/Response Helpers** — Simplified APIs for JSON, files, and text responses
+- ⚙️ **Modular Architecture** — Use what you need, extend what you want
+- 🔐 **Beta Features** — JWT authentication and email support (development version)
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+- [Getting Started](#getting-started)
+- [Configuration Files](#configuration-files)
+- [Architecture Guide](#architecture-guide)
+- [Examples Repository](#examples-repository)
+- [Core Concepts](#core-concepts)
+- [Routing Rules](#routing-rules)
+- [Server Configuration](#server-configuration)
+- [Use Cases](#use-cases)
+- [Development Features](#development-features)
 
-This project began as a **personal journey** to deeply understand how web servers work in **Node.js**.
-Throughout its development, I’ve gained **tons of new skills and insights** that I’m excited to share.
+---
+
+## Quick Start
+
+### Installation
+
+```console
+npm install vortez
+```
+
+**Development version** (with beta features):
+
+```console
+npm install vortez@dev
+```
+
+### Requirements
+
+- **Node.js** ≥ 16.0.0
+- **ES Modules** — Set `"type": "module"` in your `package.json`
+
+```json
+{
+  "name": "my-app",
+  "type": "module",
+  "main": "index.js"
+}
+```
+
+> [!IMPORTANT]
+> CommonJS support will be added in a future release. For now, ES modules are required.
+
+### Minimal Example
 
-🛠️ **Continuous Improvement:**
-I constantly refactor the code whenever I spot areas that can be polished or optimized.
+```js
+import Vortez from 'vortez';
 
-🌟 **Real-World Usage:**
-I actively use this module in my own web projects, which means I’m always finding new ideas, enhancements, and opportunities to fix bugs based on feedback.
+const server = new Vortez({ port: 3000 });
 
-💡 **Vision:**
-My goal is to make **Vortez** a tool that helps developers build **APIs**, **PWAs**, **websites**, and—thanks to the [Vizui module](https://github.com/NetFeez/Vizui)—**SPAs** with ease and confidence.
+// Define a route
+server.router.addAction('GET', '/hello', (request, response) => {
+  response.sendJson({ message: 'Hello World' });
+});
 
-Stay tuned for more updates and features! 🚀
-That’s all for now, [NetFeez](https://NetFeez.github.io) out.
+// Start the server
+await server.start();
+// Server running on http://localhost:3000
+```
 
 ---
 
-# Installation
+## Installation
 
-You can use **npm** to install Vortez:
+Vortez is available on npm:
 
-* **Stable version**
+```console
+npm install vortez
+```
 
-  ```console
-  mpm install vortez
-  ```
-* **Development version**
+For the latest development version with experimental features:
 
-  ```console
-  mpm install vortez@dev
-  ```
+```console
+npm install vortez@dev
+```
 
-> [!IMPORTANT]
-> You need to set `"type": "module"` in your `package.json` to use **Vortez**.
-> This requirement will be removed in a future version, but for now please configure it like this:
->
-> ```json
-> {
->   "name": "my-project",
->   "main": "index.js",
->   "type": "module"
-> }
-> ```
+---
+
+## Getting Started
+
+### Creating a Server
+
+```js
+import Vortez from 'vortez';
+
+const server = new Vortez();
+
+// Configure (optional)
+server.config.set('port', 3000);
+server.config.set('host', 'localhost');
+
+// Add routes
+server.router.addAction('GET', '/', (request, response) => {
+  response.sendJson({ status: 'ok' });
+});
+server.router.addFile('/favicon.ico', '/assets/icon.ico');
+
+// Start listening
+await server.start();
+```
+
+### Constructor Options
+
+```js
+const server = new Vortez({
+  host: 'localhost',      // Default: 'localhost'
+  port: 80,               // Default: 80
+  ssl: null               // Optional HTTPS configuration
+});
+```
+
+### Configuration Files
+
+You can also build a `Config` directly or load one from disk.
+
+```js
+import Vortez, { Config } from 'vortez';
+
+const config = new Config({
+  host: 'localhost',
+  port: 3000,
+  routing: {
+    algorithm: 'FIFO'
+  }
+});
+
+console.log(config.toJson());
+```
+
+```js
+import Vortez, { Config } from 'vortez';
+
+const config = await Config.Loader.load('config.json');
+// You can directly use of Vortez import
+const config = await Vortez.Config.Loader.load('config.json');
+
+const server = new Vortez(config);
+await server.start();
+```
+
+> [!NOTE]
+> Template defaults are absolute by design and point to this module's bundled `global/Template/*` files.
+> If you set `templates.error` or `templates.folder` yourself, you can still use paths relative to your own project.
+
+This workflow is also covered in the dedicated examples repository.
+
+### Architecture Guide
+
+For a comprehensive guide on Vortez's internal architecture, request lifecycle, performance considerations, and deployment patterns, see [Architecture Documentation](docs/ARCHITECTURE.md).
+
+### Examples Repository
+
+The runnable examples are being moved to a separate repository to keep this package focused.
+
+Until that repository is published, the snippets in this README remain the canonical reference.
 
 ---
 
-# Documentation
+## Core Concepts
+
+### URL Rules
+
+URL rules define how requests are matched to routes. They use patterns with special markers:
+
+| Pattern | Behavior | Example |
+|---------|----------|---------|
+| `/` | Root path | `/` |
+| `/path` | Literal segment | `/api/users` |
+| `/$param` | Dynamic parameter | `/$id` captures `123` as `id` |
+| `/*` | Wildcard (matches all sub-routes) | `/files/*` matches `/files/a/b/c` |
+| `/path/$id/sub` | Mixed patterns | `/user/$id/posts` |
+
+**Examples:**
+
+```js
+// Static routes
+server.router.addAction('GET', '/', homeHandler);
+server.router.addAction('GET', '/api/status', statusHandler);
+
+// Dynamic routes with parameters
+server.router.addAction('GET', '/api/users/$id', (request, response) => {
+  const userId = request.ruleParams.id;
+  // Handle request...
+});
+
+// Wildcard routes
+server.router.addAction('GET', '/api/*', catchAllHandler);
+server.router.addFile('/docs/*', 'public/docs/index.html');
+```
+
+### Request Object
+
+The `request` object contains information about the incoming HTTP request:
+
+```js
+server.router.addAction('GET', '/api/$action/$id', (request, response) => {
+  console.log(request.method);        // 'GET', 'POST', etc.
+  console.log(request.url);           // Full URL
+  console.log(request.ruleParams);    // { action: '...', id: '...' }
+  console.log(request.searchParams);  // Query parameters object (Record<string, string | undefined>)
+  console.log(request.headers);       // HTTP headers
+  // For body, use: const body = await request.post;
+});
+```. All methods are **async** and must be awaited:
+
+```js
+// Send JSON
+await response.sendJson({ key: 'value' });
+
+// Send HTML/text
+await response.send('Hello World');
+
+// Send file
+await response.sendFile('path/to/file.html');
+
+// Send with custom status and headers
+await response.sendJson({ id: 123 }, {
+  status: 201,
+  headers: {
+    'X-Test': 'TestHeader'
+  }
+});
+
+// The same options shape is supported by send, sendJson, sendFile and sendTemplate
+```
+
+> **Breaking Change in 5.0.0**: All response methods are now async. Update your route handlers to use `await` when calling response methods.
+});
+
+// The same options shape is supported by send, sendJson, sendFile and sendTemplate
+```
+
+### Middleware Execution Model
+
+Vortez uses a **snapshot middleware composition model**:
+
+- Global middleware registered via `router.httpMiddleware.use()` / `router.httpMiddleware.useError()`
+  and `router.wsMiddleware.use()` / `router.wsMiddleware.useError()` is captured at rule registration time
+- Middleware is not updated retroactively for existing rules
+- When mounting sub-routers, child middleware is appended after parent middleware
+
+**Key principle:** Register all global middleware first, then add routes.
+
+The `router.use()` helper merges middleware instances; individual middleware functions are added on `router.httpMiddleware` or `router.wsMiddleware`.
+
+```js
+const router = server.router;
+
+// Register middleware first
+router.httpMiddleware.use(authMiddleware);
+router.httpMiddleware.use(loggingMiddleware);
+
+// Add routes (they capture current middleware)
+router.addAction('GET', '/old', oldHandler);
+// old → [authMiddleware, loggingMiddleware]
+
+// Add more middleware
+router.httpMiddleware.use(newMiddleware);
+
+// New routes get updated middleware
+router.addAction('GET', '/new', newHandler)
+  // Add a middleware only to a single rule
+  .httpMiddleware.use(otherMiddleware); 
+// new → [authMiddleware, loggingMiddleware, newMiddleware]
+
+// Old routes still use original middleware!
+// old → [authMiddleware, loggingMiddleware]
+```
+
+**Practical example with sub-routers:**
+
+```js
+const apiRouter = new Vortez.Router();
+apiRouter.httpMiddleware.use(apiAuthMiddleware);
+apiRouter.addAction('GET', '/users', getUsersHandler);
+
+server.router.httpMiddleware.use(globalMiddleware);
+server.router.mount(apiRouter, '/api');
+// Final middleware chain: [globalMiddleware, apiAuthMiddleware]
+```
+
+---
 
 ## Static Pages
 
@@ -63,256 +321,520 @@ const server = new Vortez();
 server.router.addFolder('/source', 'source');
 server.router.addFile('/', 'source/index.html');
 
+// Set all other routes or an specific rule for the static page
+server.router.addFile('/*', 'source/index.html');
+server.router.addFile('/app/*', 'source/index.html');
+
 // Starting the server
-server.start();
+await server.start();
 ```
 
 ---
 
-## APIs and Websites
+## REST APIs
 
-You can use **actions** to execute code and send responses to the client:
+Build a complete REST API:
 
 ```js
 import Vortez from 'vortez';
 
-const server = new Vortez();
+const server = new Vortez({ port: 3000 });
 
-// Action with a static response
-server.router.addAction('GET', '/api/test', (request, response) => {
-  response.sendJson({
-    message: 'Hello World',
-    route: `[${request.method}] -> ${request.url}`
-  });
+// Users resource
+server.router.addAction('GET', '/api/users', (req, res) => {
+  res.sendJson([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+  ]);
 });
 
-// Route params and query params
-// Example route param: `/api/params/$id`
-// Example request: `http://localhost/api/params/123`
-server.router.addAction('GET', '/api/params/$id', (request, response) => {
-  response.sendJson({
-    message: 'Hello World',
-    route: `[${request.method}] -> ${request.url}`,
-    params: request.ruleParams,
-    query: request.searchParams
-  });
+server.router.addAction('GET', '/api/users/$id', (req, res) => {
+  const id = req.ruleParams.id;
+  res.sendJson({ id, name: `User ${id}` });
 });
 
-// Serving files
-server.router.addAction('GET', '/api/file', (request, response) => {
-  response.sendFile('source/index.html');
+server.router.addAction('POST', '/api/users', async (req, res) => {
+  const user = await req.post;
+  res.sendJson({ id: 123, ...user }, { status: 201 });
 });
 
-// Sending simple text
-server.router.addAction('GET', '/api/string', (request, response) => {
-  response.send('Hello World');
+server.router.addAction('PUT', '/api/users/$id', async (req, res) => {
+  const id = req.ruleParams.id;
+  const body = await req.post;
+  res.sendJson({ id, ...body });
 });
 
-// Starting the server
-server.start();
+server.router.addAction('DELETE', '/api/users/$id', (req, res) => {
+  res.send('', { status: 204 });
+});
+
+await server.start();
 ```
 
 ---
 
-## SPAs
+## Single Page Applications
 
-You can serve a single file for multiple URLs, including recursive routes:
+Serve an SPA with client-side routing:
 
 ```js
 import Vortez from 'vortez';
 
 const server = new Vortez();
 
-server.router.addFile('/', 'main.html');
-server.router.addFile('/app/*', 'main.html');
+// Serve the main app shell for all app routes
+server.router.addFile('/app', 'public/app.html');
+server.router.addFile('/app/*', 'public/app.html');
+
+// Serve static assets
 server.router.addFolder('/public', 'public');
 
-/*
-You can also add other features like actions, files, folders, etc.
-Use addWebSocket for real-time connections.
-*/
+// Optional: API routes
+server.router.addAction('GET', '/api/data', (req, res) => {
+  res.sendJson({ /* ... */ });
+});
 
-server.start();
+await server.start();
 ```
 
 ---
 
+## Routing Rules
+
+### Serving Folders
+
+Serve an entire directory and its subdirectories:
+
+```js
+server.router.addFolder('/public', 'public');
+server.router.addFolder('/docs', 'documentation');
+
+// Absolute paths are supported
+server.router.addFolder('/cdn', '/var/www/cdn');
+```
+
+> [!WARNING]
+> Never expose sensitive directories:
+> - ❌ `server.router.addFolder('/', '.')` — Exposes the entire project
+> - ❌ `server.router.addFolder('/', 'src')` — Exposes source code
+>
+> Exposed contents include:
+> - Private certificate keys
+> - Database credentials in configuration files
+> - API tokens and secrets
+> - Source code and internal structure
+
+### Serving Files
+
+Serve a single file at a specific route:
+
+```js
+server.router.addFile('/', 'public/index.html');
+server.router.addFile('/sitemap.xml', 'public/sitemap.xml');
+
+// Useful for SPAs - serve the same file for multiple routes
+server.router.addFile('/app/*', 'public/app.html');
+```
+
+### Action Routes
+
+Execute code to handle requests dynamically:
+
+```js
+// Simple JSON API
+server.router.addAction('GET', '/api/status', (request, response) => {
+  response.sendJson({ 
+    status: 'online',
+    timestamp: new Date().toISOString()
+  });
+});
+
+// With route parameters
+server.router.addAction('GET', '/api/users/$id', (request, response) => {
+  const userId = request.ruleParams.id;
+  response.sendJson({ id: userId, name: 'User ' + userId });
+});
+
+// With query parameters
+server.router.addAction('GET', '/api/search', (request, response) => {
+  const query = request.searchParams.q;
+  response.sendJson({ results: [], query });
+});
+
+// POST with body
+server.router.addAction('POST', '/api/data', async (request, response) => {
+  const body = await request.post;
+  response.sendJson({ received: body }, { status: 201 });
+});
+
+// Multiple methods
+server.router.addAction('GET', '/resource/$id', getResourceHandler);
+server.router.addAction('PUT', '/resource/$id', updateResourceHandler);
+server.router.addAction('DELETE', '/resource/$id', deleteResourceHandler);
+```
+
+### WebSocket Routes
+
+Handle real-time WebSocket connections:
+
+```js
+const connections = new Set();
+
+server.router.addWebsocket('/chat', (request, socket) => {
+  console.log('[WS] New connection from:', request.url);
+  
+  // Notify others
+  connections.forEach(conn => {
+    conn.send('A user connected');
+  });
+  connections.add(socket);
+
+  // Handle incoming messages
+  socket.on('message', (data, info) => {
+    console.log('Message:', data.toString());
+    
+    // Broadcast to all connections
+    connections.forEach(conn => {
+      if (conn !== socket) {
+        conn.send(data);
+      }
+    });
+  });
+
+  // Handle disconnection
+  socket.on('finish', () => {
+    connections.delete(socket);
+    connections.forEach(conn => {
+      conn.send('A user disconnected');
+    });
+  });
+
+  // Handle errors
+  socket.on('error', (error) => {
+    console.error('[WS-Error]:', error);
+  });
+});
+```
+
+> [!NOTE]
+> WebSocket routes use a separate namespace from HTTP routes, so you can have `/api` as both an HTTP action and a WebSocket route without conflicts.
+
+---
+
 ## Server Configuration
 
-You can configure the server using the `server.config` object:
+### Configuration Methods
+
+Configure the server using `server.config`:
 
 ```js
 import Vortez from 'vortez';
 const server = new Vortez();
 
-server.config.port = 3000;
-server.config.host = 'localhost';
-server.config.https = {
-  key: 'path/to/key.pem',
-  cert: 'path/to/cert.pem'
-};
-server.config.templates.error = 'error.html';
-server.config.templates.folder = 'folder.html';
+// Set individual values
+server.config.set('port', 3000);
+server.config.set('host', '0.0.0.0');
+
+// Set nested values
+server.config.set('ssl.cert', 'path/to/cert.pem');
+server.config.set('ssl.key', 'path/to/key.pem');
+
+// Get values
+const port = server.config.get('port');
+const algorithm = server.config.get('routing.algorithm');
 ```
 
-You can also create the server with a configuration object passed to the constructor:
+### Constructor Configuration
 
-* **Using options:**
+Pass configuration to the constructor:
 
 ```js
 const server = new Vortez({
-  port: 3000,
-  host: 'localhost',
-  ssl: null
+  host: '0.0.0.0',
+  port: 8080,
+  ssl: {
+    cert: 'path/to/cert.pem',
+    key: 'path/to/key.pem',
+    port: 443
+  }
 });
 ```
 
-* **Using the Config instance:**
+### HTTPS/SSL Configuration
+
+Enable HTTPS with SSL certificates:
 
 ```js
-const config = new Vortez.Config();
-config.port = 3000;
-config.host = 'localhost';
-config.ssl = null;
+server.config.set('ssl', {
+  cert: 'path/to/certificate.pem',
+  key: 'path/to/private-key.pem',
+  port: 443  // Optional: HTTPS port (default: 443)
+});
+```
 
-const server = new Vortez(config);
+The framework will automatically create an HTTPS server alongside the HTTP server.
+
+### Template Path Behavior
+
+- `templates.error` and `templates.folder` default to absolute module paths inside Vortez's own `global/Template` directory.
+- This is intentional so defaults work consistently regardless of where your app is executed from.
+- When you provide your own template paths, relative paths are allowed and resolved from your app/project context.
+
+### Available Configuration Keys
+
+```js
+server.config.set('host', 'localhost');           // Server hostname
+server.config.set('port', 80);                    // HTTP port
+server.config.set('ssl.cert', 'cert.pem');        // SSL certificate path
+server.config.set('ssl.key', 'key.pem');          // SSL private key path
+server.config.set('ssl.port', 443);               // HTTPS port
+server.config.set('templates.error', 'error.html');    // Error page template
+server.config.set('templates.folder', 'folder.html');  // Folder listing template
+server.config.set('routing.algorithm', 'FIFO');   // Routing algorithm ('FIFO' or 'Tree')
 ```
 
 ---
 
-## URL Rules
+## Real-World Example (ArtFolder Style)
 
-URL rules are strings used to define routes handled by the router.
+This is a complete composition pattern based on the real-world project structure used in ArtFolder,
+with separated routers for UI pages, API endpoints, and WebSocket endpoints.
 
-The main separator is `/` which indicates a new sub-route:
+```js
+import Vortez, { ServerError, Template } from 'vortez';
 
-* **`*`**: A wildcard that captures all sub-routes.
-* **`$<name>`**: A dynamic parameter you can access via `request.ruleParams`.
-* **`<string>`**: A literal segment that must match exactly.
+const config = await Vortez.Config.Loader.load('.config.json');
+const server = new Vortez(config);
 
-**Examples**:
+const clientRouter = new Vortez.Router();
+const apiRouter = new Vortez.Router();
+const socketRouter = new Vortez.Router();
+
+// -------------------------
+// Shared API middleware
+// -------------------------
+apiRouter.httpMiddleware.useError((error, request, response, next, state) => {
+  if (error instanceof ServerError) {
+    return response.sendJson({ error: error.message }, { status: error.status });
+  }
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  return response.sendJson({ error: message }, { status: 500 });
+});
 
-* `/api/*` — Matches `/api/users`, `/api/posts/comments`, etc.
-* `/user/$id` — Matches `/user/123`, capturing `123` as `id`.
-* `/blog/$category/$postId` — Matches `/blog/tech/42`, capturing `tech` as `category` and `42` as `postId`.
+apiRouter.httpMiddleware.use(async (request, response, next, state) => {
+  const page = Number(request.searchParams.page ?? '1');
+  const limit = Number(request.searchParams.limit ?? '20');
+  if (!Number.isFinite(page) || !Number.isFinite(limit)) {
+    throw new ServerError('Invalid pagination params', 400);
+  }
+  state.page = page;
+  state.limit = limit;
+  return next();
+});
 
----
+// -------------------------
+// Client router (SSR + static)
+// -------------------------
+clientRouter.addAction('GET', '/', async (request, response) => {
+  const importMap = await Template.load('assets/importmap.json', {});
+  await response.sendTemplate('assets/app.html', {
+    title: 'Art Folder',
+    style: '/client/styles/styles.css',
+    logic: '/client/logic/build/logic.js',
+    importMap
+  });
+});
 
-## Rules
+clientRouter.addAction('GET', '/app/*', async (request, response) => {
+  const importMap = await Template.load('assets/importmap.json', {});
+  await response.sendTemplate('assets/app.html', {
+    title: 'Art Folder',
+    style: '/client/styles/styles.css',
+    logic: '/client/logic/build/logic.js',
+    importMap
+  });
+});
 
-In **Vortez**, there are four types of routers:
+clientRouter.addFolder('/client', 'client');
+clientRouter.addFile('/favicon.ico', 'client/source/images/Mochis.gif');
 
-| Type                    | Description                                            |
-| ----------------------- | ------------------------------------------------------ |
-| [Folder](#folder)       | Serves a folder and its sub-folders                    |
-| [File](#file)           | Serves a single file                                   |
-| [Action](#action)       | Lets you handle requests programmatically              |
-| [WebSocket](#websocket) | Allows managing WebSocket connections on a given route |
+// -------------------------
+// API router
+// -------------------------
+apiRouter.addAction('GET', '/health', (request, response, state) => {
+  response.sendJson({ ok: true, page: state.page, limit: state.limit });
+});
 
-### Folder
+apiRouter.addAction('POST', '/echo', async (request, response) => {
+  const body = await request.post;
+  response.sendJson({ received: body }, { status: 201 });
+});
 
-Serves a folder and its sub-folders:
+apiRouter.addAction('GET', '/user/$uuid', (request, response) => {
+  response.sendJson({ userId: request.ruleParams.uuid });
+});
 
-> [!WARNING]
-> Do not share the root of your project, as this would expose **ALL** its contents:
->
-> * Private certificate keys
-> * Database passwords in server-side `.js` files
-> * Security tokens
-> * And any other sensitive data
->
-> Also:
->
-> * The entire assigned path will be exposed.
->
->   * **Example:** assigning `/src` would include all sub-routes like `/src/styles`.
+apiRouter.addAction('GET', '*', (request) => {
+  throw new ServerError(`No route found for ${request.method} -> ${request.url}`, 404);
+});
+
+// -------------------------
+// WebSocket router
+// -------------------------
+socketRouter.addWebsocket('/user/$uuid', (request, socket) => {
+  socket.sendJson({
+    type: 'welcome',
+    uuid: request.ruleParams.uuid,
+    queryUuid: request.searchParams.uuid
+  });
+
+  socket.on('message', (data) => {
+    socket.sendJson({ type: 'echo', data: data.toString('utf8') });
+  });
+});
+
+// Mount everything
+server.router.mount(clientRouter);
+server.router.mount(apiRouter, '/api');
+server.router.mount(socketRouter, '/rtc');
+
+await server.start();
+```
+
+This pattern keeps each concern isolated and mirrors how larger applications organize routes in production.
+
+---
+
+## Use Cases
+
+### Static Website
+
+Simple static site with assets:
 
 ```js
-server.router.addFolder('/my-folder', 'path/to/folder');
-server.router.addFolder('/my-folder-2', '/path/to/folder/absolute');
+import Vortez from 'vortez';
+
+const server = new Vortez();
+
+server.router.addFile('/', 'public/index.html');
+server.router.addFolder('/assets', 'public');
+
+await server.start();
 ```
 
-### File
+### Full-Stack Application
 
-Serves a single file:
+Combine API endpoints with static frontend:
 
 ```js
-server.router.addFile('/my-file', 'path/to/file');
-server.router.addFile('/my-file-2', '/path/to/file/absolute');
+import Vortez from 'vortez';
+
+const server = new Vortez();
+
+// API
+server.router.addAction('GET', '/api/posts', getPosts);
+server.router.addAction('POST', '/api/posts', createPost);
+
+// Frontend
+server.router.addFile('/', 'public/index.html');
+server.router.addFolder('/assets', 'public');
+
+await server.start();
 ```
 
-### Action
+### Single Page Application
 
-Lets you handle requests programmatically:
+Serve a client-side routed application shell:
 
 ```js
-server.router.addAction('GET', '/my-action', (request, response) => {
-  response.sendJson({
-    message: 'Hello World',
-    route: `[${request.method}] -> ${request.url}`
-  });
+import Vortez from 'vortez';
+
+const server = new Vortez();
+
+server.router.addFile('/', 'public/app.html');
+server.router.addFile('/app/*', 'public/app.html');
+server.router.addFolder('/assets', 'public');
+
+server.router.addAction('GET', '/api/status', (request, response) => {
+  response.sendJson({ status: 'ok' });
 });
+
+await server.start();
 ```
 
-### WebSocket
+### Real-Time Chat Application
 
-Allows managing WebSocket connections on a given route:
-
-> [!NOTE]
-> WebSocket URLs use a separate namespace from Files, Folders, and Actions,
-> so they won’t conflict even if they share the same route patterns.
+WebSocket-powered chat:
 
 ```js
-const connections = new Set();
-
-server.addWebSocket('/Test/WS-Chat', (request, socket) => {
-  console.log('[WS] New connection');
-  connections.forEach(user => user.Send('A user has connected.'));
-  connections.add(socket);
+import Vortez from 'vortez';
 
-  socket.on('finish', () => connections.delete(socket));
-  socket.on('error', error => console.log('[WS-Error]:', error));
+const server = new Vortez();
+const clients = new Set();
 
-  socket.on('message', (data, info) => {
-    if (info.opCode === 1) {
-      console.log('[WS] Message:', data.toString());
-      connections.forEach(user => {
-        if (user !== socket) user.Send(data.toString());
-      });
-    } else if (info.opCode === 8) {
-      connections.forEach(user => user.Send('A user has disconnected.'));
-    }
+server.router.addWebsocket('/chat', (request, socket) => {
+  clients.add(socket);
+  
+  socket.on('message', (data) => {
+    clients.forEach(client => client.send(data));
   });
+  
+  socket.on('finish', () => clients.delete(socket));
 });
+
+server.router.addFile('/', 'public/index.html');
+await server.start();
 ```
 
 ---
 
-# Development Version
+# Development Features
 
-## Currently in Development
+## Beta Features
 
-The following features are under active development:
+The development version includes experimental functionality:
 
-* **\[JsonWT]**: JSON Web Token (JWT) support.
-* **\[Mail]**: Email sending functionality.
-* **\[Server]**: Dynamic authentication system for routing.
+```console
+npm install vortez@dev
+```
 
-## Installation
+Access beta features:
 
-To install the development version:
+```js
+import { Beta } from 'vortez';
+const { Mail, JwtManager } = Beta;
 
-```console
-mpm install vortez@dev
+// JWT token management
+const jwt = new JwtManager({ alg: 'HS256', key: 'secret' });
+const token = jwt.sign({ userId: 1 });
+
+// Email functionality
+const mailer = new Mail({
+  host: 'smtp.example.com',
+  port: 587,
+  username: 'user',
+  password: 'secret',
+  email: 'user@example.com',
+  useStartTLS: true
+});
 ```
 
 > [!WARNING]
-> This version may contain bugs.
-> It includes the latest features that may not yet be fully tested.
+> Beta features are experimental and may change significantly. Use with caution in production.
 
-To access development features not yet listed in `changes.md`:
+---
+
+## Contributing
+
+Contributions are welcome! Feel free to submit issues and pull requests on the repository.
+
+## License
+
+Licensed under the terms specified in the [LICENSE](LICENSE) file.
+
+---
+
+## Support
+
+For questions, issues, or feature requests, please open an issue on the GitHub repository.
 
-```js
-import { Beta } from 'vortez';
-const { Mail, JwtManager } = Beta;
-```