# cuongpq-dgh/nestjs-localization-module architecture

> Architecture diagram of the GitHub repository cuongpq-dgh/nestjs-localization-module, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cuongpq-dgh/nestjs-localization-module
- Repository: https://github.com/cuongpq-dgh/nestjs-localization-module

## Overview

This project is a dynamic NestJS module designed to provide localization support for NestJS applications. Its primary purpose is to manage translations through a set of RESTful APIs, integrate with a PostgreSQL (or other SQL) database via TypeORM for persistence of language and translation entities, and optionally leverage the Microsoft Translator API for automatic translation. The module is configurable via its forRoot() method, making it both flexible and pluggable in larger applications.

##### Main Components
- Dynamic Module Configuration: Represent the module setup where the module is configured via forRoot() (with options for an existing TypeORM connection, API prefix, cache, default language, and an optional authentication guard).
- Controllers: Include separate controllers such as ConfigController, LanguageController, Third-Party-ConfigController, and Translation-related controllers. They are responsible for handling API requests related to configuration, languages, and translations.
- DTOs (Data Transfer Objects): Represent all the DTOs defined under the src/dtos directory. These include creation, update, filtering, and batch-processing DTOs for languages, translations, and third-party configurations.
- Entities: Show the entity layer with objects like config.entity, language.entity, third-party-config.entity, translation.entity, and translations.entity. These represent the database tables mapped through TypeORM.
- Services: Highlight the service layer which includes LanguageService, TranslationsService, Third-Party-ConfigService, and MicrosoftTranslatorService. These components encapsulate the business logic, data handling, and integration with external APIs.
- Guards and Pipes: Illustrate the presence of custom Guard (localization-auth.guard) for security and validation Pipe (parse-string-param.pipe) for processing route parameters.
- Utility Components: Optionally include utilities like short-uuid.util for any auxiliary function.

##### Relationships and Interactions
- Data Flow Through DTOs: Illustrate that the submitted data is first mapped and validated using DTOs before being forwarded to the service layer.
- Configuration Flow: Show that configuration (like third-party API keys and database connection options) is first set via module configuration and then used throughout the system (by the controllers and services).

##### Architectural Patterns and Design Principles
- Layered Architecture: Emphasize the separation of concerns among Controllers, DTOs, Services, and Entities.
- RESTful API Design: Highlight that the controllers expose a well-defined set of endpoints for translations and languages.

##### Technology, Frameworks, and Libraries
- TypeORM: Illustrate that the entity layer interacts with the database through TypeORM.
- Microsoft Translator API: Denote the integration with external translation services.
- Optional Components: If relevant, show integration points with i18next for the client-side usage as per the README examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client/External API Calls"]:::external
    ModuleCfg["Dynamic Module Configuration (forRoot)"]:::module

    subgraph "Controllers Layer"
        ConfigCtr["ConfigController"]:::controller
        LangCtr["LanguageController"]:::controller
        ThirdPartyCtr["Third-PartyConfigController"]:::controller
        TranslationCtr["TranslationController"]:::controller
        TranslationsCtr["TranslationsController"]:::controller
    end

    subgraph "DTOs Layer"
        CreateLangDTO["CreateLanguageDTO"]:::dto
        UpdateLangDTO["UpdateLanguageDTO"]:::dto
        CreateThirdPartyDTO["CreateThirdPartyConfigDTO"]:::dto
        FilterThirdPartyDTO["FilterThirdPartyConfigDTO"]:::dto
        UpdateThirdPartyDTO["UpdateThirdPartyConfigDTO"]:::dto
        BatchTranslateDTO["BatchTranslateDTO"]:::dto
        CreateTranslationDTO["CreateTranslationDTO"]:::dto
        FilterTranslationDTO["FilterTranslationDTO"]:::dto
        MissingTranslationDTO["MissingTranslationDTO"]:::dto
        UpdateTranslationDTO["UpdateTranslationDTO"]:::dto
    end

    subgraph "Services Layer"
        LangService["LanguageService"]:::service
        TranslationsService["TranslationsService"]:::service
        ThirdPartyConfigService["Third-PartyConfigService"]:::service
        MS_TranslatorService["MicrosoftTranslatorService"]:::service
        msAPI["External Microsoft Translator API"]:::external
    end

    subgraph "Entities Layer"
        ConfigEntity["ConfigEntity"]:::entity
        LangEntity["LanguageEntity"]:::entity
        ThirdPartyEntity["Third-PartyConfigEntity"]:::entity
        TranslationEntity["TranslationEntity"]:::entity
        TranslationsEntity["TranslationsEntity"]:::entity
    end

    subgraph "Guards & Pipes"
        AuthGuard["LocalizationAuthGuard"]:::guard
        ParsePipe["ParseStringParamPipe"]:::pipe
    end

    ShortUUIDUtil["ShortUUIDUtil"]:::utility

    %% Connections from Client
    Client -->|"calls"| ConfigCtr
    Client -->|"calls"| LangCtr
    Client -->|"calls"| ThirdPartyCtr
    Client -->|"calls"| TranslationCtr
    Client -->|"calls"| TranslationsCtr

    %% Dynamic Module Configuration flows
    ModuleCfg -->|"configures"| ConfigCtr
    ModuleCfg -->|"configures"| LangCtr
    ModuleCfg -->|"configures"| ThirdPartyCtr
    ModuleCfg -->|"configures"| TranslationCtr
    ModuleCfg -->|"configures"| TranslationsCtr
    ModuleCfg -->|"injects"| LangService
    ModuleCfg -->|"injects"| TranslationsService
    ModuleCfg -->|"injects"| ThirdPartyConfigService
    ModuleCfg -->|"injects"| MS_TranslatorService

    %% Controllers use DTOs for validation (examples)
    ConfigCtr -->|"validates"| CreateLangDTO
    LangCtr -->|"validates"| UpdateLangDTO
    ThirdPartyCtr -->|"validates"| CreateThirdPartyDTO
    TranslationCtr -->|"validates"| CreateTranslationDTO
    TranslationsCtr -->|"validates"| BatchTranslateDTO

    %% DTOs to Services mapping
    CreateLangDTO ---|"triggers"| LangService
    UpdateLangDTO ---|"triggers"| LangService

    CreateThirdPartyDTO ---|"triggers"| ThirdPartyConfigService
    FilterThirdPartyDTO ---|"triggers"| ThirdPartyConfigService
    UpdateThirdPartyDTO ---|"triggers"| ThirdPartyConfigService

    BatchTranslateDTO ---|"triggers"| TranslationsService
    CreateTranslationDTO ---|"triggers"| TranslationsService
    FilterTranslationDTO ---|"triggers"| TranslationsService
    MissingTranslationDTO ---|"triggers"| TranslationsService
    UpdateTranslationDTO ---|"triggers"| TranslationsService

    %% Services interact with Entities
    LangService -->|"persists"| LangEntity
    TranslationsService -->|"persists"| TranslationEntity
    TranslationsService -->|"persists"| TranslationsEntity
    ThirdPartyConfigService -->|"persists"| ThirdPartyEntity
    ConfigCtr -->|"reads/writes"| ConfigEntity

    %% Microsoft Translator Service external integration
    MS_TranslatorService -->|"calls"| msAPI

    %% Guards and Pipes applied to Controllers (dotted lines)
    AuthGuard -.->|"applies to"| ConfigCtr
    AuthGuard -.->|"applies to"| LangCtr
    AuthGuard -.->|"applies to"| ThirdPartyCtr
    AuthGuard -.->|"applies to"| TranslationCtr
    AuthGuard -.->|"applies to"| TranslationsCtr

    ParsePipe -.->|"parses"| ConfigCtr
    ParsePipe -.->|"parses"| LangCtr
    ParsePipe -.->|"parses"| ThirdPartyCtr
    ParsePipe -.->|"parses"| TranslationCtr
    ParsePipe -.->|"parses"| TranslationsCtr

    %% Utility used by Services
    ShortUUIDUtil -->|"assists"| TranslationsService

    %% Click Events
    click ModuleCfg "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/module/translations.module.ts"
    click ConfigCtr "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/controllers/config.controller.ts"
    click LangCtr "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/controllers/language.controller.ts"
    click ThirdPartyCtr "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/controllers/third-party-config.controller.ts"
    click TranslationCtr "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/controllers/translation.controller.ts"
    click TranslationsCtr "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/controllers/translations.controller.ts"

    click CreateLangDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/language/create-language.dto.ts"
    click UpdateLangDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/language/update-language.dto.ts"
    click CreateThirdPartyDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/third-party-config/create-third-party-config.dto.ts"
    click FilterThirdPartyDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/third-party-config/filter-third-party-config.dto.ts"
    click UpdateThirdPartyDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/third-party-config/update-third-party-config.dto.ts"
    click BatchTranslateDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/translation/batch-translate.dto.ts"
    click CreateTranslationDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/translation/create-translation.dto.ts"
    click FilterTranslationDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/translation/filter-translation.dto.ts"
    click MissingTranslationDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/translation/missing-translation.dto.ts"
    click UpdateTranslationDTO "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/dtos/translation/update-translation.dto.ts"

    click ConfigEntity "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/entities/config.entity.ts"
    click LangEntity "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/entities/language.entity.ts"
    click ThirdPartyEntity "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/entities/third-party-config.entity.ts"
    click TranslationEntity "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/entities/translation.entity.ts"
    click TranslationsEntity "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/entities/translations.entity.ts"

    click LangService "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/services/language.service.ts"
    click TranslationsService "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/services/translations.service.ts"
    click ThirdPartyConfigService "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/services/third-party-config.service.ts"
    click MS_TranslatorService "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/services/microsoft-translator.service.ts"

    click AuthGuard "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/guards/localization-auth.guard.ts"
    click ParsePipe "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/pipe/parse-string-param.pipe.ts"
    click ShortUUIDUtil "https://github.com/cuongpq-dgh/nestjs-localization-module/blob/main/src/utils/short-uuid.util.ts"

    %% Styles
    classDef module fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef controller fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef dto fill:#A9DFBF,stroke:#333,stroke-width:2px;
    classDef service fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef entity fill:#D7BDE2,stroke:#333,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef guard fill:#F1948A,stroke:#333,stroke-width:2px;
    classDef pipe fill:#85C1E9,stroke:#333,stroke-width:2px;
    classDef utility fill:#FAD7A0,stroke:#333,stroke-width:2px;
```
