# chandara-code/nest-js-heroku architecture

> Architecture diagram of the GitHub repository chandara-code/nest-js-heroku, 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/chandara-code/nest-js-heroku
- Repository: https://github.com/chandara-code/nest-js-heroku

## Overview

This project is a NestJS REST API boilerplate designed to serve as a backend for common applications. It is built using NestJS and leverages TypeORM for database operations, which includes migrations and seeding. Additionally, it supports a variety of authentication mechanisms (email/password plus multiple social logins like Apple, Facebook, Google, and Twitter), file uploading (both local and S3), internationalization (i18n), and mailing (via nodemailer). There is also robust testing infrastructure with both unit and end-to-end (E2E) tests, along with Docker configurations for containerized deployment and CI/CD integration using GitHub and GitLab workflows.

##### And List Main Components
- API Gateway / Entry Point: Represented by the central NestJS application (src/app.module.ts, src/main.ts).
- REST API Modules: Include various domain-specific modules such as:
- Articles, Auth (with multiple submodules for each social provider), Files, Firebase Admin, Forgot, Home, Mail, Session, and Users.
- Database: Represented by the TypeORM integration (src/config/database.config.ts, src/database/ folder with migrations, seeds, and the data source configuration).
- Authentication Services: Covering standard email login, social logins, token handling (JWT, refresh tokens) and strategies under src/api/auth and associated strategies.
- External Services and Integrations: Such as:
- Social login providers (Apple, Facebook, Google, Twitter).
- Mailing server (with nodemailer, and maildev for local testing).
- File storage services (local file system and Amazon S3).
- Firebase Admin for push notifications.
- Configuration and Environment Management: Using @nestjs/config and various config files located in src/config.
- Internationalization (i18n): Managed via translation files under src/assets/i18n.
- Logging and API Response Handling: Custom error handling, logging (docker-compose and logging docs in /docs), and response formatting in src/core.
- Testing Infrastructure: Unit and E2E tests in the test directory.
- DevOps/CI Integration: Dockerfiles, docker-compose files, CI configurations (GitHub Actions, GitLab pipelines) indicating containerized deployment.

##### Relationships and Data Flow
- The REST API layers interact with the database via TypeORM, and each module (articles, users, etc.) is responsible for its own domain logic.
- Authentication components (controllers, services, strategies) interact with the user management module and the database for token generation and validation.
- File uploads service connects with storage backends (local or S3) and is integrated with the main API.
- External API calls (for social logins, mailing, or Firebase notifications) are handled by designated modules that encapsulate the integration logic.
- Configuration modules act as cross-cutting components that inject necessary settings into all parts of the application.
- Testing flows (E2E tests, unit tests) simulate user and admin interactions with these endpoints.

##### Architectural Patterns and Design Principles
- Modular Architecture: Each functionality is split into well-defined modules (e.g., each API segment in src/api has its own module, controller, and service).
- Separation of Concerns: Clear separation between business logic (services), presentation (controllers), and data access (TypeORM entities and repositories).
- Dependency Injection: Utilized throughout via NestJS to manage configurations and service dependencies.
- Microservice Readiness: The project layout makes it relatively easy to separate modules into individual microservices if required.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry Point
    A["NestJS API Gateway"]:::gateway

    %% REST API Modules Subgraph
    subgraph "REST API Modules"
        AA["Articles"]:::module
        AB["Auth"]:::module
        AC["Apple Auth"]:::module
        AD["Facebook Auth"]:::module
        AE["Google Auth"]:::module
        AF["Twitter Auth"]:::module
        AG["Files"]:::module
        AH["Firebase Admin"]:::module
        AI["Forgot Password"]:::module
        AJ["Home"]:::module
        AK["Mail"]:::module
        AL["Session"]:::module
        AM["Users"]:::module
    end

    %% Core & Configuration Subgraph
    subgraph "Core & Config"
        BA["Configuration"]:::config
        BB["Internationalization"]:::config
        BC["Logging & API Response"]:::config
    end

    %% External Systems
    D["Database (TypeORM)"]:::database
    E["Social Providers"]:::external
    F["File Storage (Local/S3)"]:::external
    G["Mail Service (Nodemailer/Maildev)"]:::external
    H["Firebase Service"]:::external

    %% DevOps and Testing
    I["DevOps/CI & Containerization"]:::devops
    J["Testing Infrastructure"]:::testing

    %% Connections from API Gateway to Modules
    A -->|"routes"| AA
    A -->|"routes"| AB
    A -->|"routes"| AG
    A -->|"routes"| AH
    A -->|"routes"| AI
    A -->|"routes"| AJ
    A -->|"routes"| AK
    A -->|"routes"| AL
    A -->|"routes"| AM

    %% Connections within Auth Submodules to Social Providers
    AB -->|"integrates"| E
    AC -->|"integrates"| E
    AD -->|"integrates"| E
    AE -->|"integrates"| E
    AF -->|"integrates"| E

    %% Module interactions with Database
    AA -->|"uses"| D
    AB -->|"uses"| D
    AG -->|"uses"| D
    AM -->|"uses"| D

    %% External integrations from specific modules
    AG -->|"uploads to"| F
    AK -->|"sends via"| G
    AH -->|"notifies via"| H

    %% Core & Config connections injecting configurations
    BA ---|"configures"| A
    BB ---|"localizes"| A
    BC ---|"monitors"| A

    %% DevOps and Testing flows
    I ---|"deploys"| A
    J ---|"validates"| A

    %% Additional interaction between Auth and Users
    AB ---|"manages"| AM

    %% Click Events for API Gateway / Entry Point
    click A "https://github.com/chandara-code/nest-js-heroku/blob/main/src/app.module.ts"
    click A "https://github.com/chandara-code/nest-js-heroku/blob/main/src/main.ts"

    %% Click Events for REST API Modules
    click AA "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/articles"
    click AB "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/auth"
    click AC "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/auth-apple"
    click AD "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/auth-facebook"
    click AE "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/auth-google"
    click AF "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/auth-twitter"
    click AG "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/files"
    click AH "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/firebase-admin"
    click AI "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/forgot"
    click AJ "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/home"
    click AK "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/mail"
    click AL "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/session"
    click AM "https://github.com/chandara-code/nest-js-heroku/tree/main/src/api/users"

    %% Click Events for Database Integration
    click D "https://github.com/chandara-code/nest-js-heroku/blob/main/src/config/database.config.ts"
    click D "https://github.com/chandara-code/nest-js-heroku/tree/main/src/database"

    %% Click Events for Configuration and Internationalization
    click BA "https://github.com/chandara-code/nest-js-heroku/tree/main/src/config"
    click BB "https://github.com/chandara-code/nest-js-heroku/tree/main/src/assets/i18n"
    click BC "https://github.com/chandara-code/nest-js-heroku/tree/main/src/core"

    %% Click Events for Testing and DevOps
    click J "https://github.com/chandara-code/nest-js-heroku/tree/main/test"
    click I "https://github.com/chandara-code/nest-js-heroku/tree/main/Dockerfile"

    %% Class Definitions for styling
    classDef gateway fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef module fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef config fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef database fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef devops fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef testing fill:#D5F5E3,stroke:#239B56,stroke-width:2px;
```
