@futdevpro/nts-dynamo 1.15.382 → 1.15.386

package/README.md

@@ -6,349 +6,349 @@ delivery evidence. Its aggregate operations projection exposes only state/due/ex
 It starts no timer, poller or background worker.
 
 ![Dynamo-NTS Logo](src/_assets/dynamo-nts-logo-256.png)
-
-**Dynamo-NTS** (NodeTS) is a comprehensive backend framework for building robust, secure, and scalable Node.js applications with TypeScript. Built on top of [Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) (`@futdevpro/fsm-dynamo`), it provides a structured approach to server-side development with clear separation of concerns, extensive configuration options, and production-ready implementations for common backend tasks.
-
-Dynamo-NTS uses **[Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo)** as its foundational layer, implementing the server-side components of the FSM architecture. All core interfaces, types, and utilities are provided by FSM, ensuring consistency and type safety across the entire Dynamo ecosystem.
-
-Dynamo-NTS is part of the unified **Dynamo ecosystem**, a full-stack development framework designed to accelerate the development of scalable web applications. The ecosystem consists of interconnected packages that work together seamlessly, with Dynamo-NTS serving as the backend implementation layer. The frontend counterpart is **[Dynamo NGX](https://www.npmjs.com/package/@futdevpro/ngx-dynamo)**, which uses **[Dynamo NGX Models](https://www.npmjs.com/package/@futdevpro/ngx-dynamo-models)** for type-safe model definitions.
-
-### Design Philosophy
-
-Dynamo-NTS is built with two key principles:
-
-- **Full Override Capability**: Every component, service, and class can be overridden or extended. The framework provides a solid foundation with sensible defaults, but you have complete control to customize or replace any part to fit your specific needs. This makes Dynamo-NTS highly customizable and adaptable to any project requirements.
-
-- **Complete Type Information**: All types, interfaces, and definitions are included in the compiled output. This ensures excellent readability and maintainability—everything you need is available at compile time through TypeScript's type system, providing full IntelliSense support and eliminating the need to reference external documentation during development.
-
-### Simplified System Definitions
-
-Dynamo-NTS simplifies complex system definitions by abstracting common backend infrastructure into simple parameterization. Instead of manually configuring various libraries and services, you define your application through straightforward parameter objects:
-
-- **Express Usage**: HTTP/HTTPS server setup, routing, middleware, and error handling are configured through `DyNTS_App_Params`, `DyNTS_Http_Settings`, and `DyNTS_RoutingModule` parameters (simplifies Express server initialization and route management)
-- **MongoDB/Mongoose Usage**: Database connections, models, schemas, and operations are managed through `DyNTS_DBService` and `DyNTS_DataService` with simple data model parameter definitions (simplifies Mongoose schema creation and model management)
-- **Socket.io Usage**: Real-time communication setup, event handling, and presence tracking are configured through `DyNTS_SocketServerService` parameters and the `DyNTS_AppExtended` class (simplifies Socket.io server initialization and event management)
-- **Nodemailer Usage**: Email sending with templating, attachments, and async delivery is handled through `DyNTS_EmailService` with template component definitions (simplifies Nodemailer transporter setup and email template management)
-- **OAuth2 Implementation**: Complete OAuth2.0 protocol flows including authorization codes, token exchange, and refresh tokens are managed through `DyNTS_OAuth2_Controller` and `DyNTS_OAuth2_AuthService` (simplifies complex OAuth2 flow implementation)
-- **Axios Usage**: HTTP client requests to external APIs are standardized through `DyNTS_ApiService` with `DyNTS_ApiCall_Params` configuration (simplifies Axios request setup, error handling, and response management)
-- **Discord.js / Slack / Teams Bot Development**: Platform-agnostic bot framework through `DyNTS_Bot_MessagingProvider_ServiceBase` and bot modules (simplifies Discord.js, Slack, and Teams bot development with unified interfaces)
-- **OpenAI / AI Provider Integration**: AI/LLM operations including chat, embeddings, and vector search are abstracted through `DyNTS_AI_Provider_ServiceBase` and provider implementations (simplifies OpenAI SDK usage and enables multi-provider architecture)
-- **Location Tracking**: Optional, local-only IP geolocation through `geoip-lite`; addresses are not sent to an external service or written to logs by Dynamo-NTS
-
-This parameterization approach eliminates boilerplate code and provides a consistent, type-safe interface for all backend operations. Instead of learning multiple library APIs and their configuration patterns, developers work with unified Dynamo-NTS parameter objects that handle the underlying complexity.
-
-### Content-free process diagnostics
-
-`DyNTS_App` projects bootstrap failures, unhandled promise rejections, database connection/runtime failures,
-HTTP/HTTPS server errors, routing failures and Express fallbacks through the versioned
-`dynts-safe-diagnostic/1` contract before framework-owned logging or error forwarding. The public allowlist is
-limited to `contractVersion`, `code`, `stage`, `causeType`, `fingerprint` and `status`. Raw error messages,
-stacks, rejected promises, requests and database URIs are excluded. The fingerprint is derived only from the
-allowlisted classification, never from raw failure content.
-
-Consumers can use `DyNTS_SafeDiagnostic_ControlService.project()` when they need the same deterministic
-projection without logging, `report()` for safe framework logging, and `toError()` when a content-free
-`DyFM_Error` must cross an existing error-handler boundary. See
-[`__documentations/2026-08-22-content-free-process-error-boundary.md`](./__documentations/2026-08-22-content-free-process-error-boundary.md)
-for the normative boundary and verification matrix.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [Modules Overview](#modules-overview)
-- [Usage Examples](#usage-examples)
-- [Ecosystem Integration](#ecosystem-integration)
-- [API Reference](#api-reference)
-
-## Installation
-
-Install Dynamo-NTS using pnpm (recommended) or npm:
-
-```bash
-pnpm add @futdevpro/dynamo-nts
-# or
-npm install @futdevpro/dynamo-nts
-```
-
-### Peer Dependencies
-
-Dynamo-NTS requires peer dependencies that are divided into two categories: core dependencies (required for the main module) and module-specific dependencies (required only when using specific modules).
-
-#### Core Dependencies (Required)
-
-These dependencies are required for the main Dynamo-NTS functionality:
-
-- [`@futdevpro/fsm-dynamo`](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) - The foundational package providing core interfaces and utilities (always required)
-- `express` - Web framework for Node.js (simplified through Dynamo-NTS parameterization)
-- `mongoose` - MongoDB object modeling (simplified through Dynamo-NTS data services)
-- `axios` - HTTP client (simplified through Dynamo-NTS API service)
-- `body-parser` - Request body parsing middleware
-- `dotenv` - Environment variable management
-- `rxjs` - Reactive programming library
-- `@types/express` - TypeScript types for Express
-- `@types/node` - TypeScript types for Node.js
-- `ts-node` - TypeScript execution environment
-
-Install core dependencies:
-
-```bash
-pnpm add @futdevpro/fsm-dynamo express mongoose axios body-parser dotenv rxjs @types/express @types/node ts-node
-```
-
-#### Module-Specific Dependencies (Optional)
-
-These dependencies are only required when using specific modules:
-
-- **Socket Module**: `socket.io` - Real-time communication (simplified through Dynamo-NTS socket services)
-- **Email Service**: `nodemailer` - Email sending (simplified through Dynamo-NTS email services)
-- **Usage Module**: `geoip-lite` and `@types/geoip-lite` - optional, local-only IP geolocation. The provider is loaded only when a lookup is requested. Without it, lookup methods return `null` and the rest of Dynamo-NTS remains usable. The supported secure `geoip-lite` line requires Node.js 24 or newer.
-- **Bot Module (Discord)**: `discord.js` - Discord bot development (simplified through Dynamo-NTS bot module)
-- **AI Module (OpenAI)**: `openai` - OpenAI API integration (simplified through Dynamo-NTS AI module)
-
-The GeoIP lookup itself does not transmit or log an address. Calling the Usage module can persist the
-request address and derived location in the consumer's own data store. Consumers enabling that capability
-must define the applicable lawful basis, user-facing transparency, access controls, retention and deletion.
-
-Install module-specific dependencies as needed:
-
-```bash
-# For Socket module
-pnpm add socket.io
-
-# For Email service
-pnpm add nodemailer
-
-# For Usage module
-pnpm add geoip-lite@^2.0.3 @types/geoip-lite@^1.4.4
-
-# For Bot module (Discord)
-pnpm add discord.js
-
-# For AI module (OpenAI)
-pnpm add openai
-```
-
-## Quick Start
-
-The following example demonstrates how to set up a basic Dynamo-NTS application with routing and socket support:
-
-```typescript
-import { 
-  DyNTS_AppExtended,
-  DyNTS_App_Params,
-  DyNTS_GlobalService_Settings,
-  DyNTS_Http_Settings,
-  DyNTS_RoutingModule
-} from '@futdevpro/nts-dynamo';
-import { 
-  DyNTS_SocketServerService 
-} from '@futdevpro/nts-dynamo/socket';
-import { DyFM_usageSession_dataParams } from '@futdevpro/fsm-dynamo/usage';
-import { DyFM_customData_dataParams } from '@futdevpro/fsm-dynamo/custom-data';
-import { DyNTS_getUsageRoutingModule } from '@futdevpro/nts-dynamo/usage';
-import { DyNTS_getTestRoutingModule } from '@futdevpro/nts-dynamo/test';
-
-import { AuthService } from './core-services/auth.service';
-import { Email_ServiceCollection } from './core-services/email.service-collection';
-import { User_Controller } from './routes/user/user.controller';
-import { Chat_SocketServerService } from './socket-services/chat.socket-server-service';
-
-export class App extends DyNTS_AppExtended {
-
-  getAppParams(): DyNTS_App_Params {
-    return new DyNTS_App_Params({
-      name: 'My Application',
-      version: '1.0.0',
-      dbName: 'myapp',
-      dbUri: process.env.MONGO_URL || 'mongodb://localhost:27017/myapp',
-      systemShortCodeName: 'MYAPP',
-    });
-  }
-
-  getGlobalServiceCollection(): DyNTS_GlobalService_Settings {
-    return {
-      authService: AuthService.getInstance(),
-      emailServiceCollection: Email_ServiceCollection.getInstance(),
-      dbModels: [
-        // Your data model parameters here
-        DyFM_usageSession_dataParams,
-        DyFM_customData_dataParams,
-      ],
-    };
-  }
-
-  getPortSettings(): DyNTS_Http_Settings {
-    return new DyNTS_Http_Settings({
-      httpPort: 3000,
-    });
-  }
-
-  getRoutingModules(): DyNTS_RoutingModule[] {
-    return [
-      new DyNTS_RoutingModule({
-        route: '/user',
-        controllers: [
-          User_Controller.getInstance(),
-        ],
-      }),
-      DyNTS_getTestRoutingModule(),
-      DyNTS_getUsageRoutingModule(),
-    ];
-  }
-
-  getSocketServices(): DyNTS_SocketServerService<any>[] {
-    return [
-      Chat_SocketServerService.getInstance(),
-    ];
-  }
-}
-
-// Start the application
-const app = new App();
-```
-
-## Core Concepts
-
-Dynamo-NTS uses [Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) as its foundation, implementing all server-side components defined in the FSM architecture. All types, interfaces, and base models are provided by FSM, ensuring full type safety and consistency.
-
-### Extensibility and Customization
-
-Dynamo-NTS is designed with extensibility in mind. Every component, service, and class can be overridden or extended to meet your specific requirements:
-
-- **Service Override**: All services (authentication, email, data services, etc.) can be extended or completely replaced with custom implementations
-- **Method Override**: Abstract methods in base classes allow you to customize behavior while maintaining the framework structure
-- **Configuration Override**: Global settings, route security, and application parameters can be overridden at any level
-- **Type Safety**: All overrides maintain full TypeScript type safety, with all types and interfaces available at compile time
-
-This design philosophy ensures that Dynamo-NTS provides a solid foundation while remaining fully customizable for your specific use cases.
-
-### Complete Type Information
-
-All types, interfaces, and definitions are included in the compiled output, ensuring excellent readability and maintainability. When you compile your project, you have access to:
-
-- Complete type definitions for all services, models, and interfaces
-- Full IntelliSense support in your IDE
-- Compile-time type checking for all framework components
-- Self-documenting code through TypeScript's type system
-
-This approach eliminates the need to reference external documentation during development—everything you need is available in your IDE's autocomplete and type hints.
-
-### Application Classes
-
-Dynamo-NTS provides two main application base classes that simplify Express server setup:
-
-- **`DyNTS_App`**: Basic application class for standard HTTP server applications without real-time socket support
-- **`DyNTS_AppExtended`**: Extended application class that includes built-in socket server capabilities for real-time communication (simplifies Socket.io setup)
-
-Both classes abstract away Express server configuration, requiring you to implement several abstract methods with simple parameter objects:
-
-- `getAppParams()`: Define application parameters (name, version, database name, etc.) - replaces Express app initialization
-- `getGlobalServiceCollection()`: Configure global services (authentication, email, database models) - replaces manual service registration
-- `getPortSettings()`: Configure HTTP/HTTPS ports - replaces Express server.listen() configuration
-- `getRoutingModules()`: Define API routes and controllers - replaces Express router setup
-
-### Data Services
-
-Data services provide a structured way to interact with MongoDB, simplifying Mongoose model and schema definitions:
-
-- **`DyNTS_DBService<T>`**: Low-level MongoDB service for direct database operations (simplifies Mongoose model creation)
-- **`DyNTS_DataService<T>`**: High-level data service with business logic, validation, and dependency management (simplifies MongoDB CRUD operations)
-- **`DyNTS_ArchiveDataService<T>`**: Service for managing archived data in separate collections
-
-Instead of manually creating Mongoose schemas and models, you define data models through `DyFM_DataModel_Params` (from FSM), and Dynamo-NTS handles schema generation, model creation, and connection management automatically. Data services handle CRUD operations, data validation, dependency tracking, and provide methods for searching, filtering, and managing data relationships.
-
-### Atomic MongoDB transactions
-
-`DyNTS_MongoTransaction_ControlService` is the shared Bedrock entry point for business operations that must
-commit several MongoDB writes as one unit. The callback receives the same Mongoose `ClientSession` that must
-be attached to every participating query or write:
-
-```typescript
-import { ClientSession } from 'mongoose';
-
-import { DyNTS_MongoTransaction_ControlService } from '@futdevpro/nts-dynamo';
-
-const transactionService: DyNTS_MongoTransaction_ControlService =
-  DyNTS_MongoTransaction_ControlService.getInstance();
-
-const pipelineId: string = await transactionService.execute<string>({
-  transactionName: 'publish-pipeline-version',
-  issuer: 'pipeline-persistence-service',
-  maxCommitTimeMs: 3_000,
-  task: async (session: ClientSession): Promise<string> => {
-    // Every MongoDB operation in this callback must use `session`.
-    // Example: await model.updateOne(filter, update, { session: session });
-    // Example: await auditModel.create([ event ], { session: session });
-    return 'pipeline-id';
-  },
-});
-```
-
-The service uses snapshot reads, majority writes and primary routing, always closes the session, and emits
-stable content-free error codes. MongoDB transactions require a replica set or sharded deployment; a standalone
-MongoDB instance is intentionally not treated as transaction-capable. Mongoose may retry the callback after a
-transient transaction error, so the callback must not perform non-transactional side effects such as sending
-messages or mutating external systems.
-
-### Routing System
-
-The routing system provides a structured approach to defining RESTful API endpoints, simplifying Express router configuration:
-
-- **`DyNTS_RoutingModule`**: Groups related controllers under a common route path (replaces Express Router setup)
-- **`DyNTS_Controller`**: Abstract base class for defining HTTP endpoints (simplifies Express route handlers)
-- **`DyNTS_Endpoint_Params`**: Configuration for individual API endpoints (replaces Express route definitions)
-
-Instead of manually setting up Express routers and route handlers, you define endpoints through parameter objects. Controllers define endpoints with support for:
-- Multiple HTTP methods (GET, POST, PUT, PATCH, DELETE)
-- Pre-processing middleware (authentication, validation)
-- Task functions for handling requests
-- Route security levels (open, secure, both)
-
-### Global Services
-
-The `DyNTS_GlobalService` provides centralized access to:
-
-- Authentication service
-- Email service collection
-- Database models registry
-- Error handlers
-- Socket server instances
-
-### Authentication
-
-Dynamo-NTS provides an abstract `DyNTS_AuthService` class that you can extend to implement your authentication logic. The framework supports:
-
-- Token-based authentication
-- OAuth2 flows (via the OAuth2 module)
-- Session management
-- Route-level security configuration
-
-For product-local accounts, the optional `@futdevpro/nts-dynamo/account-security` entry point adds production
-security primitives without coupling a product to a shared account provider:
-
-- versioned adaptive password hashing and rehash detection;
-- hash-only email-verification and password-reset challenges with atomic one-time consumption;
-- opaque, hash-only access credentials backed by revocable server-side sessions;
-- one-time refresh rotation, replay detection, session listing and subject-wide revocation.
-
-Persistence remains application-owned through explicit atomic adapters. Transports must never put the raw
-credentials in URLs, logs, analytics or durable client storage. A consuming application must also apply its
-rate-limit, authorization, cookie/storage and audit-redaction policy at the API boundary.
-
-### Distributed rate limiting
-
-The `@futdevpro/nts-dynamo/rate-limit` entry point provides an atomic rate-limit boundary for HTTP services:
-
-- an exact sliding-window in-memory store for deterministic tests and explicitly single-instance development;
-- an application-owned shared-store contract for production deployments;
-- a production configuration gate that requires both shared persistence and explicit opaque subject/endpoint
-  extractors;
-- validated positive limits, windows and weighted request costs with stable, content-free failures;
-- trusted `req.ip` as the safe local default instead of reading caller-controlled forwarding headers directly;
-- explicit opportunistic local cleanup with no timer, polling loop or hidden background task.
-
+
+**Dynamo-NTS** (NodeTS) is a comprehensive backend framework for building robust, secure, and scalable Node.js applications with TypeScript. Built on top of [Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) (`@futdevpro/fsm-dynamo`), it provides a structured approach to server-side development with clear separation of concerns, extensive configuration options, and production-ready implementations for common backend tasks.
+
+Dynamo-NTS uses **[Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo)** as its foundational layer, implementing the server-side components of the FSM architecture. All core interfaces, types, and utilities are provided by FSM, ensuring consistency and type safety across the entire Dynamo ecosystem.
+
+Dynamo-NTS is part of the unified **Dynamo ecosystem**, a full-stack development framework designed to accelerate the development of scalable web applications. The ecosystem consists of interconnected packages that work together seamlessly, with Dynamo-NTS serving as the backend implementation layer. The frontend counterpart is **[Dynamo NGX](https://www.npmjs.com/package/@futdevpro/ngx-dynamo)**, which uses **[Dynamo NGX Models](https://www.npmjs.com/package/@futdevpro/ngx-dynamo-models)** for type-safe model definitions.
+
+### Design Philosophy
+
+Dynamo-NTS is built with two key principles:
+
+- **Full Override Capability**: Every component, service, and class can be overridden or extended. The framework provides a solid foundation with sensible defaults, but you have complete control to customize or replace any part to fit your specific needs. This makes Dynamo-NTS highly customizable and adaptable to any project requirements.
+
+- **Complete Type Information**: All types, interfaces, and definitions are included in the compiled output. This ensures excellent readability and maintainability—everything you need is available at compile time through TypeScript's type system, providing full IntelliSense support and eliminating the need to reference external documentation during development.
+
+### Simplified System Definitions
+
+Dynamo-NTS simplifies complex system definitions by abstracting common backend infrastructure into simple parameterization. Instead of manually configuring various libraries and services, you define your application through straightforward parameter objects:
+
+- **Express Usage**: HTTP/HTTPS server setup, routing, middleware, and error handling are configured through `DyNTS_App_Params`, `DyNTS_Http_Settings`, and `DyNTS_RoutingModule` parameters (simplifies Express server initialization and route management)
+- **MongoDB/Mongoose Usage**: Database connections, models, schemas, and operations are managed through `DyNTS_DBService` and `DyNTS_DataService` with simple data model parameter definitions (simplifies Mongoose schema creation and model management)
+- **Socket.io Usage**: Real-time communication setup, event handling, and presence tracking are configured through `DyNTS_SocketServerService` parameters and the `DyNTS_AppExtended` class (simplifies Socket.io server initialization and event management)
+- **Nodemailer Usage**: Email sending with templating, attachments, and async delivery is handled through `DyNTS_EmailService` with template component definitions (simplifies Nodemailer transporter setup and email template management)
+- **OAuth2 Implementation**: Complete OAuth2.0 protocol flows including authorization codes, token exchange, and refresh tokens are managed through `DyNTS_OAuth2_Controller` and `DyNTS_OAuth2_AuthService` (simplifies complex OAuth2 flow implementation)
+- **Axios Usage**: HTTP client requests to external APIs are standardized through `DyNTS_ApiService` with `DyNTS_ApiCall_Params` configuration (simplifies Axios request setup, error handling, and response management)
+- **Discord.js / Slack / Teams Bot Development**: Platform-agnostic bot framework through `DyNTS_Bot_MessagingProvider_ServiceBase` and bot modules (simplifies Discord.js, Slack, and Teams bot development with unified interfaces)
+- **OpenAI / AI Provider Integration**: AI/LLM operations including chat, embeddings, and vector search are abstracted through `DyNTS_AI_Provider_ServiceBase` and provider implementations (simplifies OpenAI SDK usage and enables multi-provider architecture)
+- **Location Tracking**: Optional, local-only IP geolocation through `geoip-lite`; addresses are not sent to an external service or written to logs by Dynamo-NTS
+
+This parameterization approach eliminates boilerplate code and provides a consistent, type-safe interface for all backend operations. Instead of learning multiple library APIs and their configuration patterns, developers work with unified Dynamo-NTS parameter objects that handle the underlying complexity.
+
+### Content-free process diagnostics
+
+`DyNTS_App` projects bootstrap failures, unhandled promise rejections, database connection/runtime failures,
+HTTP/HTTPS server errors, routing failures and Express fallbacks through the versioned
+`dynts-safe-diagnostic/1` contract before framework-owned logging or error forwarding. The public allowlist is
+limited to `contractVersion`, `code`, `stage`, `causeType`, `fingerprint` and `status`. Raw error messages,
+stacks, rejected promises, requests and database URIs are excluded. The fingerprint is derived only from the
+allowlisted classification, never from raw failure content.
+
+Consumers can use `DyNTS_SafeDiagnostic_ControlService.project()` when they need the same deterministic
+projection without logging, `report()` for safe framework logging, and `toError()` when a content-free
+`DyFM_Error` must cross an existing error-handler boundary. See
+[`__documentations/2026-08-22-content-free-process-error-boundary.md`](./__documentations/2026-08-22-content-free-process-error-boundary.md)
+for the normative boundary and verification matrix.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [Modules Overview](#modules-overview)
+- [Usage Examples](#usage-examples)
+- [Ecosystem Integration](#ecosystem-integration)
+- [API Reference](#api-reference)
+
+## Installation
+
+Install Dynamo-NTS using pnpm (recommended) or npm:
+
+```bash
+pnpm add @futdevpro/dynamo-nts
+# or
+npm install @futdevpro/dynamo-nts
+```
+
+### Peer Dependencies
+
+Dynamo-NTS requires peer dependencies that are divided into two categories: core dependencies (required for the main module) and module-specific dependencies (required only when using specific modules).
+
+#### Core Dependencies (Required)
+
+These dependencies are required for the main Dynamo-NTS functionality:
+
+- [`@futdevpro/fsm-dynamo`](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) - The foundational package providing core interfaces and utilities (always required)
+- `express` - Web framework for Node.js (simplified through Dynamo-NTS parameterization)
+- `mongoose` - MongoDB object modeling (simplified through Dynamo-NTS data services)
+- `axios` - HTTP client (simplified through Dynamo-NTS API service)
+- `body-parser` - Request body parsing middleware
+- `dotenv` - Environment variable management
+- `rxjs` - Reactive programming library
+- `@types/express` - TypeScript types for Express
+- `@types/node` - TypeScript types for Node.js
+- `ts-node` - TypeScript execution environment
+
+Install core dependencies:
+
+```bash
+pnpm add @futdevpro/fsm-dynamo express mongoose axios body-parser dotenv rxjs @types/express @types/node ts-node
+```
+
+#### Module-Specific Dependencies (Optional)
+
+These dependencies are only required when using specific modules:
+
+- **Socket Module**: `socket.io` - Real-time communication (simplified through Dynamo-NTS socket services)
+- **Email Service**: `nodemailer` - Email sending (simplified through Dynamo-NTS email services)
+- **Usage Module**: `geoip-lite` and `@types/geoip-lite` - optional, local-only IP geolocation. The provider is loaded only when a lookup is requested. Without it, lookup methods return `null` and the rest of Dynamo-NTS remains usable. The supported secure `geoip-lite` line requires Node.js 24 or newer.
+- **Bot Module (Discord)**: `discord.js` - Discord bot development (simplified through Dynamo-NTS bot module)
+- **AI Module (OpenAI)**: `openai` - OpenAI API integration (simplified through Dynamo-NTS AI module)
+
+The GeoIP lookup itself does not transmit or log an address. Calling the Usage module can persist the
+request address and derived location in the consumer's own data store. Consumers enabling that capability
+must define the applicable lawful basis, user-facing transparency, access controls, retention and deletion.
+
+Install module-specific dependencies as needed:
+
+```bash
+# For Socket module
+pnpm add socket.io
+
+# For Email service
+pnpm add nodemailer
+
+# For Usage module
+pnpm add geoip-lite@^2.0.3 @types/geoip-lite@^1.4.4
+
+# For Bot module (Discord)
+pnpm add discord.js
+
+# For AI module (OpenAI)
+pnpm add openai
+```
+
+## Quick Start
+
+The following example demonstrates how to set up a basic Dynamo-NTS application with routing and socket support:
+
+```typescript
+import { 
+  DyNTS_AppExtended,
+  DyNTS_App_Params,
+  DyNTS_GlobalService_Settings,
+  DyNTS_Http_Settings,
+  DyNTS_RoutingModule
+} from '@futdevpro/nts-dynamo';
+import { 
+  DyNTS_SocketServerService 
+} from '@futdevpro/nts-dynamo/socket';
+import { DyFM_usageSession_dataParams } from '@futdevpro/fsm-dynamo/usage';
+import { DyFM_customData_dataParams } from '@futdevpro/fsm-dynamo/custom-data';
+import { DyNTS_getUsageRoutingModule } from '@futdevpro/nts-dynamo/usage';
+import { DyNTS_getTestRoutingModule } from '@futdevpro/nts-dynamo/test';
+
+import { AuthService } from './core-services/auth.service';
+import { Email_ServiceCollection } from './core-services/email.service-collection';
+import { User_Controller } from './routes/user/user.controller';
+import { Chat_SocketServerService } from './socket-services/chat.socket-server-service';
+
+export class App extends DyNTS_AppExtended {
+
+  getAppParams(): DyNTS_App_Params {
+    return new DyNTS_App_Params({
+      name: 'My Application',
+      version: '1.0.0',
+      dbName: 'myapp',
+      dbUri: process.env.MONGO_URL || 'mongodb://localhost:27017/myapp',
+      systemShortCodeName: 'MYAPP',
+    });
+  }
+
+  getGlobalServiceCollection(): DyNTS_GlobalService_Settings {
+    return {
+      authService: AuthService.getInstance(),
+      emailServiceCollection: Email_ServiceCollection.getInstance(),
+      dbModels: [
+        // Your data model parameters here
+        DyFM_usageSession_dataParams,
+        DyFM_customData_dataParams,
+      ],
+    };
+  }
+
+  getPortSettings(): DyNTS_Http_Settings {
+    return new DyNTS_Http_Settings({
+      httpPort: 3000,
+    });
+  }
+
+  getRoutingModules(): DyNTS_RoutingModule[] {
+    return [
+      new DyNTS_RoutingModule({
+        route: '/user',
+        controllers: [
+          User_Controller.getInstance(),
+        ],
+      }),
+      DyNTS_getTestRoutingModule(),
+      DyNTS_getUsageRoutingModule(),
+    ];
+  }
+
+  getSocketServices(): DyNTS_SocketServerService<any>[] {
+    return [
+      Chat_SocketServerService.getInstance(),
+    ];
+  }
+}
+
+// Start the application
+const app = new App();
+```
+
+## Core Concepts
+
+Dynamo-NTS uses [Dynamo FSM](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) as its foundation, implementing all server-side components defined in the FSM architecture. All types, interfaces, and base models are provided by FSM, ensuring full type safety and consistency.
+
+### Extensibility and Customization
+
+Dynamo-NTS is designed with extensibility in mind. Every component, service, and class can be overridden or extended to meet your specific requirements:
+
+- **Service Override**: All services (authentication, email, data services, etc.) can be extended or completely replaced with custom implementations
+- **Method Override**: Abstract methods in base classes allow you to customize behavior while maintaining the framework structure
+- **Configuration Override**: Global settings, route security, and application parameters can be overridden at any level
+- **Type Safety**: All overrides maintain full TypeScript type safety, with all types and interfaces available at compile time
+
+This design philosophy ensures that Dynamo-NTS provides a solid foundation while remaining fully customizable for your specific use cases.
+
+### Complete Type Information
+
+All types, interfaces, and definitions are included in the compiled output, ensuring excellent readability and maintainability. When you compile your project, you have access to:
+
+- Complete type definitions for all services, models, and interfaces
+- Full IntelliSense support in your IDE
+- Compile-time type checking for all framework components
+- Self-documenting code through TypeScript's type system
+
+This approach eliminates the need to reference external documentation during development—everything you need is available in your IDE's autocomplete and type hints.
+
+### Application Classes
+
+Dynamo-NTS provides two main application base classes that simplify Express server setup:
+
+- **`DyNTS_App`**: Basic application class for standard HTTP server applications without real-time socket support
+- **`DyNTS_AppExtended`**: Extended application class that includes built-in socket server capabilities for real-time communication (simplifies Socket.io setup)
+
+Both classes abstract away Express server configuration, requiring you to implement several abstract methods with simple parameter objects:
+
+- `getAppParams()`: Define application parameters (name, version, database name, etc.) - replaces Express app initialization
+- `getGlobalServiceCollection()`: Configure global services (authentication, email, database models) - replaces manual service registration
+- `getPortSettings()`: Configure HTTP/HTTPS ports - replaces Express server.listen() configuration
+- `getRoutingModules()`: Define API routes and controllers - replaces Express router setup
+
+### Data Services
+
+Data services provide a structured way to interact with MongoDB, simplifying Mongoose model and schema definitions:
+
+- **`DyNTS_DBService<T>`**: Low-level MongoDB service for direct database operations (simplifies Mongoose model creation)
+- **`DyNTS_DataService<T>`**: High-level data service with business logic, validation, and dependency management (simplifies MongoDB CRUD operations)
+- **`DyNTS_ArchiveDataService<T>`**: Service for managing archived data in separate collections
+
+Instead of manually creating Mongoose schemas and models, you define data models through `DyFM_DataModel_Params` (from FSM), and Dynamo-NTS handles schema generation, model creation, and connection management automatically. Data services handle CRUD operations, data validation, dependency tracking, and provide methods for searching, filtering, and managing data relationships.
+
+### Atomic MongoDB transactions
+
+`DyNTS_MongoTransaction_ControlService` is the shared Bedrock entry point for business operations that must
+commit several MongoDB writes as one unit. The callback receives the same Mongoose `ClientSession` that must
+be attached to every participating query or write:
+
+```typescript
+import { ClientSession } from 'mongoose';
+
+import { DyNTS_MongoTransaction_ControlService } from '@futdevpro/nts-dynamo';
+
+const transactionService: DyNTS_MongoTransaction_ControlService =
+  DyNTS_MongoTransaction_ControlService.getInstance();
+
+const pipelineId: string = await transactionService.execute<string>({
+  transactionName: 'publish-pipeline-version',
+  issuer: 'pipeline-persistence-service',
+  maxCommitTimeMs: 3_000,
+  task: async (session: ClientSession): Promise<string> => {
+    // Every MongoDB operation in this callback must use `session`.
+    // Example: await model.updateOne(filter, update, { session: session });
+    // Example: await auditModel.create([ event ], { session: session });
+    return 'pipeline-id';
+  },
+});
+```
+
+The service uses snapshot reads, majority writes and primary routing, always closes the session, and emits
+stable content-free error codes. MongoDB transactions require a replica set or sharded deployment; a standalone
+MongoDB instance is intentionally not treated as transaction-capable. Mongoose may retry the callback after a
+transient transaction error, so the callback must not perform non-transactional side effects such as sending
+messages or mutating external systems.
+
+### Routing System
+
+The routing system provides a structured approach to defining RESTful API endpoints, simplifying Express router configuration:
+
+- **`DyNTS_RoutingModule`**: Groups related controllers under a common route path (replaces Express Router setup)
+- **`DyNTS_Controller`**: Abstract base class for defining HTTP endpoints (simplifies Express route handlers)
+- **`DyNTS_Endpoint_Params`**: Configuration for individual API endpoints (replaces Express route definitions)
+
+Instead of manually setting up Express routers and route handlers, you define endpoints through parameter objects. Controllers define endpoints with support for:
+- Multiple HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Pre-processing middleware (authentication, validation)
+- Task functions for handling requests
+- Route security levels (open, secure, both)
+
+### Global Services
+
+The `DyNTS_GlobalService` provides centralized access to:
+
+- Authentication service
+- Email service collection
+- Database models registry
+- Error handlers
+- Socket server instances
+
+### Authentication
+
+Dynamo-NTS provides an abstract `DyNTS_AuthService` class that you can extend to implement your authentication logic. The framework supports:
+
+- Token-based authentication
+- OAuth2 flows (via the OAuth2 module)
+- Session management
+- Route-level security configuration
+
+For product-local accounts, the optional `@futdevpro/nts-dynamo/account-security` entry point adds production
+security primitives without coupling a product to a shared account provider:
+
+- versioned adaptive password hashing and rehash detection;
+- hash-only email-verification and password-reset challenges with atomic one-time consumption;
+- opaque, hash-only access credentials backed by revocable server-side sessions;
+- one-time refresh rotation, replay detection, session listing and subject-wide revocation.
+
+Persistence remains application-owned through explicit atomic adapters. Transports must never put the raw
+credentials in URLs, logs, analytics or durable client storage. A consuming application must also apply its
+rate-limit, authorization, cookie/storage and audit-redaction policy at the API boundary.
+
+### Distributed rate limiting
+
+The `@futdevpro/nts-dynamo/rate-limit` entry point provides an atomic rate-limit boundary for HTTP services:
+
+- an exact sliding-window in-memory store for deterministic tests and explicitly single-instance development;
+- an application-owned shared-store contract for production deployments;
+- a production configuration gate that requires both shared persistence and explicit opaque subject/endpoint
+  extractors;
+- validated positive limits, windows and weighted request costs with stable, content-free failures;
+- trusted `req.ip` as the safe local default instead of reading caller-controlled forwarding headers directly;
+- explicit opportunistic local cleanup with no timer, polling loop or hidden background task.
+
 Production consumers must implement the shared store with one atomic permit decision across every application
 instance. They must derive non-sensitive, purpose-scoped bucket identifiers and must not persist or log raw IP
 addresses, credentials, email addresses or other request content as rate-limit keys.
@@ -381,20 +381,20 @@ Products remain responsible for exact tenant authorization, retention durations,
 selection/delete predicates, operational invocation, legal review and end-to-end deletion verification.
 
 ### Privacy lifecycle
-
-The optional `@futdevpro/nts-dynamo/privacy-lifecycle` entry point provides the shared machinery for standalone
-GDPR-capable products:
-
-- identity-gated, deadline-bearing data-subject requests;
-- explicit `received → identity-verified → scoped → planned → executing → verifying` processing;
+
+The optional `@futdevpro/nts-dynamo/privacy-lifecycle` entry point provides the shared machinery for standalone
+GDPR-capable products:
+
+- identity-gated, deadline-bearing data-subject requests;
+- explicit `received → identity-verified → scoped → planned → executing → verifying` processing;
 - deterministic product-domain contributors with resumable partial outcomes and documented retention bases;
 - bounded deterministic assembly of completed, checksum-verified multi-contributor JSON export bundles;
 - exact subject-and-organization scoped deletion and terminal verification of encrypted export artifacts;
 - append-only, checksummed legal acceptances;
 - versioned, purpose-specific consent grants and withdrawals.
 - fail-closed, exact-purpose consent authorization at the point of optional processing.
-
-The Bedrock module coordinates state and evidence only. Each consuming product must register every data domain,
+
+The Bedrock module coordinates state and evidence only. Each consuming product must register every data domain,
 implement hard-delete/anonymization/export behavior, and provide transaction-safe persistence. A request is
 never reported complete while a registered contributor has a failed outcome.
 
@@ -420,438 +420,438 @@ Products still own the legal definition and presentation of each optional purpos
 authenticated grant/withdrawal API and the downstream operation. Every optional downstream operation must call the
 authorizer immediately before use. Service-required processing must use a separate, explicitly documented legal
 basis and must never be disguised as consent-based processing.
-
-## Modules Overview
-
-Dynamo-NTS is organized into focused modules, each providing specific functionality:
-
-### Main Module
-
-The core foundation providing essential components:
-
-- **Collections**: Archive utilities, global settings, environment configuration
-- **Enums**: Data model types, service functions, route security levels
-- **Models**: Application configuration interfaces, control models, database types
-- **Services**: Core services for API communication, authentication, data management, routing
-
-### AI Module
-
-Provides abstractions and implementations for AI operations:
-
-- **Abstract Service Bases**: Base classes for AI providers, LLM services, LLM chat services, and embedding services
-- **OpenAI Implementation**: Complete OpenAI integration with LLM, chat, and embedding support
-- **Document AI**: Document chunking and preprocessing for AI models
-- **Vector Search**: MongoDB Atlas vector database operations with automatic data vectorization
-
-#### OpenAI-Compatible Providers
-
-The OAI service-ek (`DyNTS_OAI_LLM_ServiceBase`, `DyNTS_OAI_LLMChat_ServiceBase`, `DyNTS_OAI_Embedding_ControlService`) bármely OpenAI-API-kompatibilis endpoint-tal működnek — lokál LLM (LM Studio, Ollama), self-hosted (vLLM, LocalAI) is — a `DyFM_OAI_ClientOptions.baseURL` mező segítségével. Részletek + provider-konfig sample-ök: [`__documentations/2026-05-17-oai-compatible-providers.md`](__documentations/2026-05-17-oai-compatible-providers.md).
-
-### Assistant Module
-
-Platform and AI provider agnostic solutions for creating intelligent assistants:
-
-- Integrates communication providers (bot) with AI providers (LLM Chat)
-- Message conversion utilities
-- Conversation management
-- Configurable settings for system prompts and message filtering
-
-### Bot Module
-
-Platform-agnostic bot functionality:
-
-- Message, channel, and user wrappers for any messaging platform
-- Command system for bot commands
-- Routine system for scheduled and event-driven tasks
-- IO management for bot interactions
-- Provider support for Discord, Slack, and Teams
-
-### Socket Module
-
-Real-time communication capabilities that simplify Socket.io setup:
-
-- Socket client and server implementations with secure and open connection options (simplifies Socket.io server initialization)
-- Event handling system for managing real-time communications (replaces manual Socket.io event handler setup)
-- Presence tracking for monitoring connected clients
-- Error handling and logging for reliable operation
-- Extended application class with built-in socket server capabilities (automatically configures Socket.io with Express server)
-
-### Messaging Module
-
-Backend implementation for unified messaging system:
-
-- Data services for messages and conversations
-- Control services for business logic orchestration
-- Real-time socket events
-- RESTful HTTP endpoints
-- Integration with bot and assistant modules
-
-### OAuth2 Module
-
-Complete OAuth2.0 protocol implementation:
-
-- OAuth2 authorization and token management
-- Client management and user authentication
-- Token exchange and refresh operations
-- Authorization code and access token generation
-
-### Server Module
-
-Solutions for basic server endpoints:
-
-- Error handling for saving and retrieving server errors
-- Server status monitoring with version and uptime information
-- Server status snapshots for saving and retrieving status at specific times
-- Error statistics for monitoring and analysis
-
-#### Content-free database readiness probe
-
-Applications can perform one foreground readiness check against their own Mongoose connection without
-starting a timer, listener, retry loop, subscription, process hook, or background task:
-
-```typescript
-import {
-  DyNTS_DbReadinessProbe_ControlService,
-  DyNTS_DbReadinessProbeResult_Interface,
-} from '@futdevpro/nts-dynamo/server';
-
-const result: DyNTS_DbReadinessProbeResult_Interface =
-  await DyNTS_DbReadinessProbe_ControlService.probe({
-    connection: mongoose.connection,
-  });
-```
-
-The `dynts-db-readiness/1` result contains exactly six allowlisted fields: contract version, readiness,
-normalized connection state, ping success, bounded stage, and stable result code. It never contains a host,
-database name, URI, model metadata, credentials, driver error text, or arbitrary error properties. Failures
-resolve to a content-free, fail-closed result and the probe writes no log output.
-
-Timeout policy and cancellation are caller-owned. The probe observes the supplied `AbortSignal` before and
-after its single ping, but it does not create a timeout or interrupt an already-running driver operation.
-Configure the driver's operation timeout and abort the supplied signal at the application boundary.
-
-### Defaults Module
-
-Default implementations for common services:
-
-- Default user data model and service for authentication and user management
-- Default authentication service with basic token-based authentication
-- Default socket events service with graceful degradation
-- All services can be extended or replaced with custom implementations
-
-### Custom Data Module
-
-Tools for managing custom data:
-
-- Data service for handling custom data operations with optional initialization
-- Controller with RESTful endpoints for data operations
-- GET endpoint for retrieving custom data by ID
-- POST endpoint for modifying custom data
-- Configurable routing module with optional security overrides
-
-### Test Module
-
-Testing and monitoring tools:
-
-- Test endpoints for different HTTP methods (GET, POST, DELETE)
-- Server status endpoint with version and uptime information
-- Configurable routing module with security override options
-- Automatic controller registration for easy setup
-
-### Usage Module
-
-Session and usage tracking tools:
-
-- Session management tools for creating, updating, and closing sessions
-- Usage data collection and analysis tools
-- Location tracking from HTTP requests
-- Usage statistics retrieval with time range filtering
-- Daily usage statistics calculation
-
-## Usage Examples
-
-### Basic Application Setup
-
-This example shows a complete application setup using `DyNTS_AppExtended`:
-
-```typescript
-import { 
-  DyNTS_AppExtended,
-  DyNTS_App_Params,
-  DyNTS_GlobalService_Settings,
-  DyNTS_Http_Settings,
-  DyNTS_RoutingModule
-} from '@futdevpro/nts-dynamo';
-import { DyNTS_SocketServerService } from '@futdevpro/nts-dynamo/socket';
-
-export class App extends DyNTS_AppExtended {
-
-  getAppParams(): DyNTS_App_Params {
-    return new DyNTS_App_Params({
-      name: 'My Server',
-      version: '1.0.0',
-      dbName: 'myapp',
-    });
-  }
-
-  getGlobalServiceCollection(): DyNTS_GlobalService_Settings {
-    return {
-      authService: AuthService.getInstance(),
-      dbModels: [
-        // Your data models
-      ],
-    };
-  }
-
-  getPortSettings(): DyNTS_Http_Settings {
-    return new DyNTS_Http_Settings({
-      httpPort: 3000,
-    });
-  }
-
-  getRoutingModules(): DyNTS_RoutingModule[] {
-    return [
-      new DyNTS_RoutingModule({
-        route: '/api',
-        controllers: [
-          MyController.getInstance(),
-        ],
-      }),
-    ];
-  }
-
-  getSocketServices(): DyNTS_SocketServerService<any>[] {
-    return [
-      MySocketService.getInstance(),
-    ];
-  }
-}
-```
-
-### Routing Module Configuration
-
-Multiple routing modules can be configured to organize your API:
-
-```typescript
-getRoutingModules(): DyNTS_RoutingModule[] {
-  return [
-    new DyNTS_RoutingModule({
-      route: '/user',
-      controllers: [
-        User_Controller.getInstance(),
-        UserData_Controller.getInstance(),
-        UserSettings_Controller.getInstance(),
-      ],
-    }),
-    new DyNTS_RoutingModule({
-      route: '/project',
-      controllers: [
-        Project_Controller.getInstance(),
-        ProjectExtension_Controller.getInstance(),
-      ],
-    }),
-    new DyNTS_RoutingModule({
-      route: '/server',
-      controllers: [
-        ServerStatus_Controller.getInstance(),
-      ],
-    }),
-    DyNTS_getTestRoutingModule(),
-    DyNTS_getUsageRoutingModule(),
-  ];
-}
-```
-
-### Controller Implementation
-
-Controllers define API endpoints with authentication and business logic:
-
-```typescript
-import { Request, Response } from 'express';
-import { DyNTS_Controller, DyNTS_Endpoint_Params } from '@futdevpro/nts-dynamo';
-import { DyFM_HttpCallType } from '@futdevpro/fsm-dynamo';
-
-export class User_Controller extends DyNTS_Controller {
-
-  static getInstance(): User_Controller {
-    return User_Controller.getSingletonInstance();
-  }
-
-  private authService: AuthService = AuthService.getInstance();
-
-  setupEndpoints(): void {
-    this.endpoints = [
-      new DyNTS_Endpoint_Params({
-        name: 'getUser',
-        type: DyFM_HttpCallType.get,
-        endpoint: '/get/:userId',
-        preProcesses: [this.authService.authenticate_tokenSelf],
-        tasks: [
-          async (req: Request, res: Response, issuer: string): Promise<void> => {
-            const userService = new User_DataService({ issuer });
-            await userService.getDataById(req.params.userId);
-            res.send(userService.data);
-          },
-        ],
-      }),
-      new DyNTS_Endpoint_Params({
-        name: 'updateUser',
-        type: DyFM_HttpCallType.post,
-        endpoint: '/update',
-        preProcesses: [this.authService.authenticate_tokenSelf],
-        tasks: [
-          async (req: Request, res: Response, issuer: string): Promise<void> => {
-            const userService = new User_DataService({ issuer });
-            await userService.saveData(req.body);
-            res.send(userService.data);
-          },
-        ],
-      }),
-    ];
-  }
-}
-```
-
-### Data Service Implementation
-
-Data services provide a structured way to interact with MongoDB:
-
-```typescript
-import { DyNTS_DataService } from '@futdevpro/nts-dynamo';
-import { DyFM_DataModel_Params } from '@futdevpro/fsm-dynamo'; // FSM provides the data model parameter definition
-
-// Define your data model parameters
-const userDataParams: DyFM_DataModel_Params<UserData> = new DyFM_DataModel_Params({
-  dataName: 'userData',
-  typeSample: {
-    userId: '',
-    preferences: {},
-  },
-  // ... additional configuration
-});
-
-export class User_DataService extends DyNTS_DataService<UserData> {
-  constructor(params: { issuer: string }) {
-    super(userDataParams);
-    this.issuer = params.issuer;
-  }
-
-  // Custom business logic methods
-  async getUserPreferences(userId: string): Promise<UserPreferences> {
-    await this.getDataByDependencyId({ userId });
-    return this.data?.preferences || {};
-  }
-}
-```
-
-### Socket Server Service
-
-Socket services enable real-time communication:
-
-```typescript
-import { DyNTS_SocketServerService, DyNTS_SocketPresence } from '@futdevpro/nts-dynamo/socket';
-
-export class Chat_SocketServerService extends DyNTS_SocketServerService<DyNTS_SocketPresence, any> {
-
-  static getInstance(): Chat_SocketServerService {
-    return Chat_SocketServerService.getSingletonInstance();
-  }
-
-  protected setupSocketEvents(): void {
-    this.socketServer.on('connection', (socket) => {
-      socket.on('joinRoom', (roomId: string) => {
-        socket.join(roomId);
-      });
-
-      socket.on('sendMessage', async (data: { roomId: string; message: string }) => {
-        this.socketServer.to(data.roomId).emit('newMessage', data);
-      });
-    });
-  }
-}
-```
-
-### Vector Search with AI
-
-Dynamo-NTS provides built-in support for MongoDB Atlas vector search with automatic vectorization:
-
-```typescript
-import { DyNTS_OAI_VectorDataService } from '@futdevpro/nts-dynamo/ai/open-ai';
-
-export class Knowledge_DataService extends DyNTS_OAI_VectorDataService<Knowledge> {
-  
-  constructor() {
-    super(knowledgeDataParams);
-  }
-
-  async searchSimilarContent(query: string, limit: number = 10): Promise<Knowledge[]> {
-    return await this.vectorSearch({
-      input: query,
-      searchInKey: 'content', // Property that has vectorization enabled
-      limit: limit,
-      numberOfCandidates: 100,
-    });
-  }
-}
-```
-
-The vector search automatically:
-- Creates embeddings for search queries using the configured AI provider
-- Performs semantic search in MongoDB Atlas vector database
-- Returns results sorted by relevance
-- Supports filtering with additional MongoDB queries
-
-## Ecosystem Integration
-
-Dynamo-NTS is part of the unified **Dynamo ecosystem**, which consists of several interconnected packages:
-
-### Dynamo FSM (Full Stack Module)
-
-The foundational package [`@futdevpro/fsm-dynamo`](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) that provides:
-- Core interfaces and types shared across the ecosystem
-- Base model definitions (used by all Dynamo-NTS data services)
-- Utility functions
-- Type definitions for system-wide use
-- Data model parameter definitions (`DyFM_DataModel_Params`)
-
-Dynamo-NTS is built on top of Dynamo FSM and implements the server-side components of the FSM architecture. All data models, interfaces, and type definitions used in Dynamo-NTS are provided by FSM, ensuring consistency and type safety across the entire ecosystem.
-
-### Dynamo NGX (AngularX)
-
-The frontend counterpart [`@futdevpro/dynamo-ngx`](https://www.npmjs.com/package/@futdevpro/dynamo-ngx) provides:
-- Angular components and services
-- Frontend models that integrate with Dynamo-NTS backend (using shared FSM types)
-- Real-time communication clients (connects to Dynamo-NTS socket services)
-- Form management and data table components
-
-### Unified Patterns
-
-The Dynamo ecosystem enforces consistent patterns across all packages:
-
-- **Naming Conventions**: Consistent prefixes (`DyNTS_` for backend, `DyNX_` for frontend, `DyFM_` for shared)
-- **Type Safety**: Full TypeScript support with shared type definitions
-- **Architecture Patterns**: Consistent service patterns, data models, and API structures
-- **Error Handling**: Unified error handling across the stack
-- **Logging**: Consistent logging patterns and utilities
-
-This unified approach ensures that:
-- Developers learn one set of patterns that apply everywhere
-- Frontend and backend code integrate seamlessly
-- Type safety is maintained across the entire stack
-- Maintenance and updates are simplified
-
-## API Reference
-
-For detailed API documentation, see:
-
-- [Dynamo-NTS Documentation](fdp-documentations/specifications/dynamo-packages/dynamo-nts/dynamo-nts.md)
-- [Dynamo FSM Documentation](fdp-documentations/specifications/dynamo-packages/dynamo-fsm/dynamo-fsm.md)
-- [Dynamo Ecosystem Overview](fdp-documentations/specifications/dynamo-packages/dynamo_packages.md)
-
-## License
-
-ISC
-
-## Support
-
-For issues, questions, or contributions, please refer to the project repository.
+
+## Modules Overview
+
+Dynamo-NTS is organized into focused modules, each providing specific functionality:
+
+### Main Module
+
+The core foundation providing essential components:
+
+- **Collections**: Archive utilities, global settings, environment configuration
+- **Enums**: Data model types, service functions, route security levels
+- **Models**: Application configuration interfaces, control models, database types
+- **Services**: Core services for API communication, authentication, data management, routing
+
+### AI Module
+
+Provides abstractions and implementations for AI operations:
+
+- **Abstract Service Bases**: Base classes for AI providers, LLM services, LLM chat services, and embedding services
+- **OpenAI Implementation**: Complete OpenAI integration with LLM, chat, and embedding support
+- **Document AI**: Document chunking and preprocessing for AI models
+- **Vector Search**: MongoDB Atlas vector database operations with automatic data vectorization
+
+#### OpenAI-Compatible Providers
+
+The OAI service-ek (`DyNTS_OAI_LLM_ServiceBase`, `DyNTS_OAI_LLMChat_ServiceBase`, `DyNTS_OAI_Embedding_ControlService`) bármely OpenAI-API-kompatibilis endpoint-tal működnek — lokál LLM (LM Studio, Ollama), self-hosted (vLLM, LocalAI) is — a `DyFM_OAI_ClientOptions.baseURL` mező segítségével. Részletek + provider-konfig sample-ök: [`__documentations/2026-05-17-oai-compatible-providers.md`](__documentations/2026-05-17-oai-compatible-providers.md).
+
+### Assistant Module
+
+Platform and AI provider agnostic solutions for creating intelligent assistants:
+
+- Integrates communication providers (bot) with AI providers (LLM Chat)
+- Message conversion utilities
+- Conversation management
+- Configurable settings for system prompts and message filtering
+
+### Bot Module
+
+Platform-agnostic bot functionality:
+
+- Message, channel, and user wrappers for any messaging platform
+- Command system for bot commands
+- Routine system for scheduled and event-driven tasks
+- IO management for bot interactions
+- Provider support for Discord, Slack, and Teams
+
+### Socket Module
+
+Real-time communication capabilities that simplify Socket.io setup:
+
+- Socket client and server implementations with secure and open connection options (simplifies Socket.io server initialization)
+- Event handling system for managing real-time communications (replaces manual Socket.io event handler setup)
+- Presence tracking for monitoring connected clients
+- Error handling and logging for reliable operation
+- Extended application class with built-in socket server capabilities (automatically configures Socket.io with Express server)
+
+### Messaging Module
+
+Backend implementation for unified messaging system:
+
+- Data services for messages and conversations
+- Control services for business logic orchestration
+- Real-time socket events
+- RESTful HTTP endpoints
+- Integration with bot and assistant modules
+
+### OAuth2 Module
+
+Complete OAuth2.0 protocol implementation:
+
+- OAuth2 authorization and token management
+- Client management and user authentication
+- Token exchange and refresh operations
+- Authorization code and access token generation
+
+### Server Module
+
+Solutions for basic server endpoints:
+
+- Error handling for saving and retrieving server errors
+- Server status monitoring with version and uptime information
+- Server status snapshots for saving and retrieving status at specific times
+- Error statistics for monitoring and analysis
+
+#### Content-free database readiness probe
+
+Applications can perform one foreground readiness check against their own Mongoose connection without
+starting a timer, listener, retry loop, subscription, process hook, or background task:
+
+```typescript
+import {
+  DyNTS_DbReadinessProbe_ControlService,
+  DyNTS_DbReadinessProbeResult_Interface,
+} from '@futdevpro/nts-dynamo/server';
+
+const result: DyNTS_DbReadinessProbeResult_Interface =
+  await DyNTS_DbReadinessProbe_ControlService.probe({
+    connection: mongoose.connection,
+  });
+```
+
+The `dynts-db-readiness/1` result contains exactly six allowlisted fields: contract version, readiness,
+normalized connection state, ping success, bounded stage, and stable result code. It never contains a host,
+database name, URI, model metadata, credentials, driver error text, or arbitrary error properties. Failures
+resolve to a content-free, fail-closed result and the probe writes no log output.
+
+Timeout policy and cancellation are caller-owned. The probe observes the supplied `AbortSignal` before and
+after its single ping, but it does not create a timeout or interrupt an already-running driver operation.
+Configure the driver's operation timeout and abort the supplied signal at the application boundary.
+
+### Defaults Module
+
+Default implementations for common services:
+
+- Default user data model and service for authentication and user management
+- Default authentication service with basic token-based authentication
+- Default socket events service with graceful degradation
+- All services can be extended or replaced with custom implementations
+
+### Custom Data Module
+
+Tools for managing custom data:
+
+- Data service for handling custom data operations with optional initialization
+- Controller with RESTful endpoints for data operations
+- GET endpoint for retrieving custom data by ID
+- POST endpoint for modifying custom data
+- Configurable routing module with optional security overrides
+
+### Test Module
+
+Testing and monitoring tools:
+
+- Test endpoints for different HTTP methods (GET, POST, DELETE)
+- Server status endpoint with version and uptime information
+- Configurable routing module with security override options
+- Automatic controller registration for easy setup
+
+### Usage Module
+
+Session and usage tracking tools:
+
+- Session management tools for creating, updating, and closing sessions
+- Usage data collection and analysis tools
+- Location tracking from HTTP requests
+- Usage statistics retrieval with time range filtering
+- Daily usage statistics calculation
+
+## Usage Examples
+
+### Basic Application Setup
+
+This example shows a complete application setup using `DyNTS_AppExtended`:
+
+```typescript
+import { 
+  DyNTS_AppExtended,
+  DyNTS_App_Params,
+  DyNTS_GlobalService_Settings,
+  DyNTS_Http_Settings,
+  DyNTS_RoutingModule
+} from '@futdevpro/nts-dynamo';
+import { DyNTS_SocketServerService } from '@futdevpro/nts-dynamo/socket';
+
+export class App extends DyNTS_AppExtended {
+
+  getAppParams(): DyNTS_App_Params {
+    return new DyNTS_App_Params({
+      name: 'My Server',
+      version: '1.0.0',
+      dbName: 'myapp',
+    });
+  }
+
+  getGlobalServiceCollection(): DyNTS_GlobalService_Settings {
+    return {
+      authService: AuthService.getInstance(),
+      dbModels: [
+        // Your data models
+      ],
+    };
+  }
+
+  getPortSettings(): DyNTS_Http_Settings {
+    return new DyNTS_Http_Settings({
+      httpPort: 3000,
+    });
+  }
+
+  getRoutingModules(): DyNTS_RoutingModule[] {
+    return [
+      new DyNTS_RoutingModule({
+        route: '/api',
+        controllers: [
+          MyController.getInstance(),
+        ],
+      }),
+    ];
+  }
+
+  getSocketServices(): DyNTS_SocketServerService<any>[] {
+    return [
+      MySocketService.getInstance(),
+    ];
+  }
+}
+```
+
+### Routing Module Configuration
+
+Multiple routing modules can be configured to organize your API:
+
+```typescript
+getRoutingModules(): DyNTS_RoutingModule[] {
+  return [
+    new DyNTS_RoutingModule({
+      route: '/user',
+      controllers: [
+        User_Controller.getInstance(),
+        UserData_Controller.getInstance(),
+        UserSettings_Controller.getInstance(),
+      ],
+    }),
+    new DyNTS_RoutingModule({
+      route: '/project',
+      controllers: [
+        Project_Controller.getInstance(),
+        ProjectExtension_Controller.getInstance(),
+      ],
+    }),
+    new DyNTS_RoutingModule({
+      route: '/server',
+      controllers: [
+        ServerStatus_Controller.getInstance(),
+      ],
+    }),
+    DyNTS_getTestRoutingModule(),
+    DyNTS_getUsageRoutingModule(),
+  ];
+}
+```
+
+### Controller Implementation
+
+Controllers define API endpoints with authentication and business logic:
+
+```typescript
+import { Request, Response } from 'express';
+import { DyNTS_Controller, DyNTS_Endpoint_Params } from '@futdevpro/nts-dynamo';
+import { DyFM_HttpCallType } from '@futdevpro/fsm-dynamo';
+
+export class User_Controller extends DyNTS_Controller {
+
+  static getInstance(): User_Controller {
+    return User_Controller.getSingletonInstance();
+  }
+
+  private authService: AuthService = AuthService.getInstance();
+
+  setupEndpoints(): void {
+    this.endpoints = [
+      new DyNTS_Endpoint_Params({
+        name: 'getUser',
+        type: DyFM_HttpCallType.get,
+        endpoint: '/get/:userId',
+        preProcesses: [this.authService.authenticate_tokenSelf],
+        tasks: [
+          async (req: Request, res: Response, issuer: string): Promise<void> => {
+            const userService = new User_DataService({ issuer });
+            await userService.getDataById(req.params.userId);
+            res.send(userService.data);
+          },
+        ],
+      }),
+      new DyNTS_Endpoint_Params({
+        name: 'updateUser',
+        type: DyFM_HttpCallType.post,
+        endpoint: '/update',
+        preProcesses: [this.authService.authenticate_tokenSelf],
+        tasks: [
+          async (req: Request, res: Response, issuer: string): Promise<void> => {
+            const userService = new User_DataService({ issuer });
+            await userService.saveData(req.body);
+            res.send(userService.data);
+          },
+        ],
+      }),
+    ];
+  }
+}
+```
+
+### Data Service Implementation
+
+Data services provide a structured way to interact with MongoDB:
+
+```typescript
+import { DyNTS_DataService } from '@futdevpro/nts-dynamo';
+import { DyFM_DataModel_Params } from '@futdevpro/fsm-dynamo'; // FSM provides the data model parameter definition
+
+// Define your data model parameters
+const userDataParams: DyFM_DataModel_Params<UserData> = new DyFM_DataModel_Params({
+  dataName: 'userData',
+  typeSample: {
+    userId: '',
+    preferences: {},
+  },
+  // ... additional configuration
+});
+
+export class User_DataService extends DyNTS_DataService<UserData> {
+  constructor(params: { issuer: string }) {
+    super(userDataParams);
+    this.issuer = params.issuer;
+  }
+
+  // Custom business logic methods
+  async getUserPreferences(userId: string): Promise<UserPreferences> {
+    await this.getDataByDependencyId({ userId });
+    return this.data?.preferences || {};
+  }
+}
+```
+
+### Socket Server Service
+
+Socket services enable real-time communication:
+
+```typescript
+import { DyNTS_SocketServerService, DyNTS_SocketPresence } from '@futdevpro/nts-dynamo/socket';
+
+export class Chat_SocketServerService extends DyNTS_SocketServerService<DyNTS_SocketPresence, any> {
+
+  static getInstance(): Chat_SocketServerService {
+    return Chat_SocketServerService.getSingletonInstance();
+  }
+
+  protected setupSocketEvents(): void {
+    this.socketServer.on('connection', (socket) => {
+      socket.on('joinRoom', (roomId: string) => {
+        socket.join(roomId);
+      });
+
+      socket.on('sendMessage', async (data: { roomId: string; message: string }) => {
+        this.socketServer.to(data.roomId).emit('newMessage', data);
+      });
+    });
+  }
+}
+```
+
+### Vector Search with AI
+
+Dynamo-NTS provides built-in support for MongoDB Atlas vector search with automatic vectorization:
+
+```typescript
+import { DyNTS_OAI_VectorDataService } from '@futdevpro/nts-dynamo/ai/open-ai';
+
+export class Knowledge_DataService extends DyNTS_OAI_VectorDataService<Knowledge> {
+  
+  constructor() {
+    super(knowledgeDataParams);
+  }
+
+  async searchSimilarContent(query: string, limit: number = 10): Promise<Knowledge[]> {
+    return await this.vectorSearch({
+      input: query,
+      searchInKey: 'content', // Property that has vectorization enabled
+      limit: limit,
+      numberOfCandidates: 100,
+    });
+  }
+}
+```
+
+The vector search automatically:
+- Creates embeddings for search queries using the configured AI provider
+- Performs semantic search in MongoDB Atlas vector database
+- Returns results sorted by relevance
+- Supports filtering with additional MongoDB queries
+
+## Ecosystem Integration
+
+Dynamo-NTS is part of the unified **Dynamo ecosystem**, which consists of several interconnected packages:
+
+### Dynamo FSM (Full Stack Module)
+
+The foundational package [`@futdevpro/fsm-dynamo`](https://www.npmjs.com/package/@futdevpro/fsm-dynamo) that provides:
+- Core interfaces and types shared across the ecosystem
+- Base model definitions (used by all Dynamo-NTS data services)
+- Utility functions
+- Type definitions for system-wide use
+- Data model parameter definitions (`DyFM_DataModel_Params`)
+
+Dynamo-NTS is built on top of Dynamo FSM and implements the server-side components of the FSM architecture. All data models, interfaces, and type definitions used in Dynamo-NTS are provided by FSM, ensuring consistency and type safety across the entire ecosystem.
+
+### Dynamo NGX (AngularX)
+
+The frontend counterpart [`@futdevpro/dynamo-ngx`](https://www.npmjs.com/package/@futdevpro/dynamo-ngx) provides:
+- Angular components and services
+- Frontend models that integrate with Dynamo-NTS backend (using shared FSM types)
+- Real-time communication clients (connects to Dynamo-NTS socket services)
+- Form management and data table components
+
+### Unified Patterns
+
+The Dynamo ecosystem enforces consistent patterns across all packages:
+
+- **Naming Conventions**: Consistent prefixes (`DyNTS_` for backend, `DyNX_` for frontend, `DyFM_` for shared)
+- **Type Safety**: Full TypeScript support with shared type definitions
+- **Architecture Patterns**: Consistent service patterns, data models, and API structures
+- **Error Handling**: Unified error handling across the stack
+- **Logging**: Consistent logging patterns and utilities
+
+This unified approach ensures that:
+- Developers learn one set of patterns that apply everywhere
+- Frontend and backend code integrate seamlessly
+- Type safety is maintained across the entire stack
+- Maintenance and updates are simplified
+
+## API Reference
+
+For detailed API documentation, see:
+
+- [Dynamo-NTS Documentation](fdp-documentations/specifications/dynamo-packages/dynamo-nts/dynamo-nts.md)
+- [Dynamo FSM Documentation](fdp-documentations/specifications/dynamo-packages/dynamo-fsm/dynamo-fsm.md)
+- [Dynamo Ecosystem Overview](fdp-documentations/specifications/dynamo-packages/dynamo_packages.md)
+
+## License
+
+ISC
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository.