@futdevpro/nts-dynamo 1.15.64 → 1.15.68

package/README.md

@@ -1,678 +1,678 @@
-# Dynamo-NTS
-
-![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**: IP-based geolocation through `geoip-lite` is integrated into the usage tracking module (simplifies location data collection from HTTP requests)
-
-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.
-
-## 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` - IP geolocation (simplified through Dynamo-NTS usage module)
-- **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)
-
-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 @types/geoip-lite
-
-# 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.
-
-### 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
-
-## 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
-
-### 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](documentations/specifications/dynamo-packages/dynamo-nts/dynamo-nts.md)
-- [Dynamo FSM Documentation](documentations/specifications/dynamo-packages/dynamo-fsm/dynamo-fsm.md)
-- [Dynamo Ecosystem Overview](documentations/specifications/dynamo-packages/dynamo_packages.md)
-
-## License
-
-ISC
-
-## Support
-
-For issues, questions, or contributions, please refer to the project repository.
+# Dynamo-NTS
+
+![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**: IP-based geolocation through `geoip-lite` is integrated into the usage tracking module (simplifies location data collection from HTTP requests)
+
+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.
+
+## 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` - IP geolocation (simplified through Dynamo-NTS usage module)
+- **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)
+
+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 @types/geoip-lite
+
+# 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.
+
+### 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
+
+## 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
+
+### 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](documentations/specifications/dynamo-packages/dynamo-nts/dynamo-nts.md)
+- [Dynamo FSM Documentation](documentations/specifications/dynamo-packages/dynamo-fsm/dynamo-fsm.md)
+- [Dynamo Ecosystem Overview](documentations/specifications/dynamo-packages/dynamo_packages.md)
+
+## License
+
+ISC
+
+## Support
+
+For issues, questions, or contributions, please refer to the project repository.