Dynamo-NTS

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

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

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.

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

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:

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.