# ssut/nestjs-sqs architecture

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

- Interactive diagram: https://gitdiagram.com/ssut/nestjs-sqs
- Repository: https://github.com/ssut/nestjs-sqs

## Overview

##### Project type and purpose
- This is a **NestJS module library** whose purpose is to simplify working with AWS SQS queues inside a Nest application.
- It provides decorator-based message handlers (consumers) and a service for sending messages (producers), built on top of the `bbc/sqs-consumer` and `bbc/sqs-producer` packages.

##### File structure
- **lib/** contains the core implementation:
– `sqs.module.ts` – defines the Nest module and handles dynamic registration (`register()` / `registerAsync()`).
– `sqs.service.ts` – exposes `send(name, message)` and manages producer instances.
– `sqs.decorators.ts` – contains `@SqsMessageHandler()` and event-handler decorators.
– `sqs.constants.ts` & `sqs.types.ts` – configuration keys and type definitions.
- **e2e/** contains an end-to-end test demonstrating module usage.
- Root config and CI/CD workflows manage linting, testing, publishing, and ElasticMQ setup.

##### Extract insights from the README
- The module uses AWS SQS or ElasticMQ under the hood.
- Consumers are long-running processes that poll SQS and invoke decorated methods on your Nest providers.
- Producers send messages via the SqsService to any named queue.

##### Main components
a. **Nest Application**
– The consumer of this library.
– Imports `SqsModule` in its root or feature module.
b. **SqsModule**
– Configures producers and consumers.
– Registers `SqsService` and sets up `sqs-consumer` clients.
c. **SqsService**
– Holds a registry of named producer instances.
– Uses `bbc/sqs-producer` to send messages to SQS.
d. **Decorated Providers**
– Any NestJS `@Injectable()` classes with `@SqsMessageHandler()` or `@SqsConsumerEventHandler()` decorators.
– Act as message callbacks.
e. **bbc/sqs-consumer**
– Polls AWS SQS queue(s).
– Routes incoming messages into Nest via the decorated methods.
f. **AWS SQS / ElasticMQ**
– The external queue service.
– Receives messages from producers; delivers messages to consumers.
g. **bbc/sqs-producer**
– Sends messages into AWS SQS.

##### Relationships and data flows
– **Startup**: Nest’s DI container loads `SqsModule` → configures consumer loops via `bbc/sqs-consumer` → binds decorated handlers.
– **Message production**: Nest component calls `SqsService.send()` → `bbc/sqs-producer` pushes the message to AWS SQS.
– **Message consumption**: `bbc/sqs-consumer` polls AWS SQS → on message received it invokes the corresponding `@SqsMessageHandler` in your provider.
– **Error events**: Consumer errors are emitted and routed to methods decorated with `@SqsConsumerEventHandler`.

##### Architectural patterns and design principles
- **Modular design**: NestJS module encapsulates SQS logic.
- **Decorator pattern**: Simplifies binding SQS events to handler methods.
- **Dependency injection**: Clean separation—your code only depends on `SqsService` and decorators, not the underlying SQS client.
- **Adapter pattern**: Wraps `bbc/sqs-consumer` / `bbc/sqs-producer` to fit Nest’s lifecycle.

##### Elements
- From NestApp → SqsModule (import)
- From SqsService → bbc/sqs-producer → AWS SQS
- From AWS SQS → bbc/sqs-consumer → Decorated Providers
- **Blue rectangles** for internal modules or classes (SqsModule, SqsService, Decorators).
- **Green rectangles** for third‐party libraries (bbc/sqs-producer, bbc/sqs-consumer).
– **Annotations**: note async registration options, batch vs. single‐message handling, and event hooks (e.g., processing_error).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules (Blue)
    NestApp["Nest Application"]:::internal
    SqsModule["SqsModule"]:::internal
    SqsService["SqsService"]:::internal
    Decorators["@SqsMessageHandler / @SqsConsumerEventHandler\n(Decorators)"]:::internal
    Constants["Module Configuration Keys"]:::internal
    Types["Type Definitions"]:::internal
    Index["Public API Barrel Export"]:::internal
    DecoratedProviders["Decorated Providers\n(User Code)"]:::internal

    %% Third-Party Libraries (Green)
    bbcProducer["bbc/sqs-producer"]:::thirdparty
    bbcConsumer["bbc/sqs-consumer"]:::thirdparty

    %% External Systems (Orange)
    AwsSqs["AWS SQS / ElasticMQ"]:::external
    ElasticMQConfig["ElasticMQ Config\n(.github/build/elasticmq.conf)"]:::external
    E2EWorkflow["E2E Test Workflow\n(.github/workflows/test.yml)"]:::external
    PublishWorkflow["CI Publish Workflow\n(.github/workflows/publish.yml)"]:::external
    Package["package.json"]:::external

    %% Relationships
    NestApp -->|"imports"| SqsModule
    SqsModule -->|"provides"| SqsService
    SqsModule -->|"registers handlers"| Decorators
    SqsModule -->|"uses constants"| Constants
    SqsModule -->|"uses types"| Types

    Index -->|"exports"| SqsModule
    Index -->|"exports"| SqsService
    Index -->|"exports"| Decorators
    Index -->|"exports"| Constants
    Index -->|"exports"| Types

    SqsService -->|"send() calls"| bbcProducer
    bbcProducer -->|"pushes messages to"| AwsSqs
    AwsSqs -->|"polls messages via"| bbcConsumer
    bbcConsumer -->|"invokes handlers in"| DecoratedProviders

    E2EWorkflow -->|"configures"| ElasticMQConfig
    E2EWorkflow -->|"runs tests on"| NestApp
    PublishWorkflow -->|"publishes via"| Package

    %% Click events
    click NestApp "https://github.com/ssut/nestjs-sqs/blob/master/e2e/module.e2e-spec.ts"
    click SqsModule "https://github.com/ssut/nestjs-sqs/blob/master/lib/sqs.module.ts"
    click SqsService "https://github.com/ssut/nestjs-sqs/blob/master/lib/sqs.service.ts"
    click Decorators "https://github.com/ssut/nestjs-sqs/blob/master/lib/sqs.decorators.ts"
    click Constants "https://github.com/ssut/nestjs-sqs/blob/master/lib/sqs.constants.ts"
    click Types "https://github.com/ssut/nestjs-sqs/blob/master/lib/sqs.types.ts"
    click Index "https://github.com/ssut/nestjs-sqs/blob/master/lib/index.ts"
    click ElasticMQConfig "https://github.com/ssut/nestjs-sqs/blob/master/.github/build/elasticmq.conf"
    click E2EWorkflow "https://github.com/ssut/nestjs-sqs/blob/master/.github/workflows/test.yml"
    click PublishWorkflow "https://github.com/ssut/nestjs-sqs/blob/master/.github/workflows/publish.yml"
    click Package "https://github.com/ssut/nestjs-sqs/blob/master/package.json"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000
    classDef thirdparty fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
```
