Dynamo-NTS

The additive @futdevpro/nts-dynamo/application-alert-delivery subpath provides an explicitly invoked, durable, content-free application-alert sender outbox with idempotency, bounded retry/backoff, leases, fencing and terminal delivery evidence. Its aggregate operations projection exposes only state/due/expired-lease counts and timestamps. It starts no timer, poller or background worker.

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 (@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 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, which uses Dynamo NGX 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 for the normative boundary and verification matrix.

Table of Contents

• Installation
• Quick Start
• Core Concepts
• Modules Overview
• Usage Examples
• Ecosystem Integration
• API Reference

Installation

Install Dynamo-NTS using pnpm (recommended) or npm:

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 - 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:

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:

# 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:

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 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:

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.

Namespace-bound keyset pagination

The optional @futdevpro/nts-dynamo/pagination entry point provides a strict keyset cursor codec for bounded API listings. A codec instance binds every cursor to one declared namespace and an exact tuple dimension count, uses canonical unpadded base64url, rejects expanded or reordered payloads, and returns defensive tuple copies.

The cursor is an integrity and routing boundary, not encryption. Consumers must put only non-sensitive ordering values such as canonical timestamps and opaque resource identifiers into the tuple. Tenant, account, email, authorization or business-content fields must remain server-derived and outside the cursor payload.

Explicit lifecycle cleanup

The optional @futdevpro/nts-dynamo/lifecycle-cleanup entry point coordinates resumable product cleanup without learning product collection names or retention policy. Consumers supply opaque scope/root hashes, one immutable ordered stage plan and one database-only adapter per stage. Each explicit invocation runs at most one bounded batch; the module never starts a timer, polling loop, scheduler or network callback.

Schedule the cleanup gate in the same caller-owned Mongo transaction as the product soft delete, and cancel it in the same transaction as an allowed restore. Due work uses Mongo server time, a bounded lease and a monotonic fencing token. Product mutations and progress commit share one ClientSession, so they commit or roll back together. An expired or replaced worker cannot commit, incomplete stages resume without advancing, and parents cannot run before every earlier product-defined stage is complete.

The shared store retains only opaque hashes, plan identity, aggregate counts, timestamps and result checksums. Products remain responsible for exact tenant authorization, retention durations, stage meanings, deterministic 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;
• 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, 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.

The export-bundle assembler accepts only server-derived request, subject and organization authority. It reads encrypted contributor artifacts through the existing exact-scope artifact boundary, validates each outcome and checksum, sorts contributors deterministically and returns sensitive JSON only in memory. The consuming product still owns step-up authorization, response delivery, filename policy and cache-prevention headers, and must never log or persist the returned plaintext without equivalent encryption and expiry controls.

DyNTS_PrivacyExportArtifactPrivacyContributor_ControlService can be registered before product-domain authority roots to include transient export artifacts in account erasure. It deletes only the exact data-subject and tenant scope and verifies that scope again after execution. Prior export artifacts are deliberately not recursively included in later access or export bundles.

DyNTS_PrivacyConsentAuthorization_ControlService is the shared enforcement boundary for optional processing. The consumer supplies trusted subject, organization, purpose and required policy version values; the service asks the ledger adapter for the latest event in that exact scope. Only a current grant for the required policy version is allowed. Missing evidence, withdrawal, a stale policy version, malformed or cross-scope evidence, an unavailable store, and an adapter without the exact lookup capability all fail closed. Results contain only stable decision metadata and never consent identifiers, request fingerprints, persistence diagnostics or processing payloads.

Products still own the legal definition and presentation of each optional purpose, its versioned policy, the 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.

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:

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:

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:

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:

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:

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:

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:

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 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 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
• Dynamo FSM Documentation
• Dynamo Ecosystem Overview

License

ISC

Support

For issues, questions, or contributions, please refer to the project repository.