# gsthalves/customers architecture

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

- Interactive diagram: https://gitdiagram.com/gsthalves/customers
- Repository: https://github.com/gsthalves/customers

## Overview

##### Main Components
- API/Presentation Layer:
– Located under api/src/presentation with further separations for NestJS controllers (for synchronous HTTP interactions) and Lambda handlers (for serverless entry points).
– This layer is responsible for handling incoming API requests (e.g., create, update, delete, search, and get customer operations).

- Application Layer:
– Found under api/src/application, this layer encapsulates the business logic and use-cases (for customer operations).
– It also handles orchestration, error management, and validation logic.

- Domain Layer:
– Located under api/src/domain and contains entities, contracts (interfaces), enums, and domain errors.
– Represents the core business rules (e.g., customer entity details, customer status enums) and ensures the integrity of business data.

- Infrastructure Layer (Within API):
– Located under api/src/infrastructure, includes adapters, factories, and repositories for interfacing with external services like DynamoDB and OpenSearch, as well as logging.
– This layer abstracts the implementation details of external storage, search, and logging systems.

- Cloud Infrastructure:
– Represented by the “infrastructure” directory that holds Terraform configuration, makefiles, and environment definitions.
– This sets up all the necessary AWS services (such as Lambda, DynamoDB, possibly API Gateway, etc.) that the application requires to run in the cloud.

##### Interactions and Relationships
- Front-end communication (via API Gateway or direct HTTP calls) will hit the Presentation Layer (either NestJS controllers or Lambda handlers).
- The Presentation Layer delegates requests to the Application Layer’s use-cases.
- The Application Layer interacts with the Domain Layer (business entities, domain errors) to enforce business rules.
- For persistent storage and search queries, the Application Layer calls upon the Infrastructure Layer’s repositories through adapters for DynamoDB and OpenSearch.
- Logging and error reporting are managed via an infrastructure adapter (e.g., Winston Logger) that is also integrated within the Infrastructure Layer.

##### Architectural Patterns and Design Principles
- Layered (or hexagonal/clean) architecture is evident: clear separations exist between presentation, application, domain, and infrastructure.
- Dependency Inversion: Domain contracts and interfaces allow you to plug in various infrastructure implementations (e.g., DynamoDB adapter, OpenSearch adapter) without affecting the core business logic.
- Serverless design: With Lambda functions as part of the presentation layer and terraform-managed resources, the system emphasizes scalability and cloud-native deployment.
- Testability: The presence of detailed spec files (e.g., *.spec.ts) indicates an emphasis on unit testing across the various layers.

##### Essential Elements
- Each component (e.g., NestJS Controllers, Lambda Handlers, Customer Use-Cases, Customer Entity, DynamoDB and OpenSearch repositories, Logging adapter, Terraform-managed AWS resources).
- Labels that indicate protocol or dependency types (e.g., “HTTP API Request”, “Database Repository”, “Search Index”, “Logging”).
- Annotations that briefly note the role of each layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    EXT["API Gateway/Clients"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
      direction TB
      PN1["NestJS Controllers (HTTP)"]:::presentation
      PN2["Lambda Handlers (Serverless)"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
      direction TB
      AP1["Use-Cases & Business Logic"]:::application
      AP2["Error Handling"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
      direction TB
      DO1["Customer Entities"]:::domain
      DO2["Domain Contracts"]:::domain
      DO3["Customer Enums"]:::domain
      DO4["Domain Errors"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
      direction TB
      subgraph "Adapters"
        direction TB
        IAD1["DynamoDB Adapter"]:::infrastructure
        IAD2["OpenSearch Adapter"]:::infrastructure
        IAD3["Logger Adapter"]:::infrastructure
      end
      subgraph "Repositories"
        direction TB
        IR1["DynamoDB Repository"]:::infrastructure
        IR2["OpenSearch Repository"]:::infrastructure
      end
      INF3["Factories"]:::infrastructure
    end

    %% Cloud Infrastructure
    subgraph "Cloud Infrastructure"
      direction TB
      CI1["Terraform AWS Resources"]:::cloud
    end

    %% External Systems
    DB["DynamoDB (DB)"]:::externalDB
    OS["OpenSearch (Search)"]:::externalDB
    LOG["Logger Service"]:::external

    %% Connections from External Client to Presentation
    EXT -->|"HTTP_Request"| PN1
    EXT -->|"Event_Trigger"| PN2

    %% Presentation to Application
    PN1 -->|"delegates"| AP1
    PN2 -->|"delegates"| AP1

    %% Application interactions
    AP1 -->|"calls_entity"| DO1
    AP1 -->|"uses_contract"| DO2
    AP1 -->|"validates_enum"| DO3
    AP1 -->|"reports_error"| AP2

    %% Application to Infrastructure
    AP1 -->|"persist"| IAD1
    AP1 -->|"db_access"| IR1
    AP1 -->|"search_index"| IR2
    AP1 -->|"logs"| IAD3

    %% Infrastructure Adapters to External Systems
    IAD1 -->|"DDB_calls"| DB
    IAD2 -->|"search_calls"| OS
    IAD3 -->|"logging"| LOG
    IR1 -->|"db_calls"| DB
    IR2 -->|"index_calls"| OS

    %% Cloud provisions Infrastructure and Presentation (Lambda)
    CI1 -->|"provisions"| PN2
    CI1 ---|"provisions"| IAD1
    CI1 ---|"provisions"| IAD2
    CI1 ---|"provisions"| IAD3
    CI1 ---|"provisions"| IR1
    CI1 ---|"provisions"| IR2
    CI1 ---|"provisions"| INF3

    %% Click Events
    click PN1 "https://github.com/gsthalves/customers/tree/develop/api/src/presentation/nestjs/controllers/customer"
    click PN2 "https://github.com/gsthalves/customers/tree/develop/api/src/presentation/lambda/handlers/customer"
    click AP1 "https://github.com/gsthalves/customers/tree/develop/api/src/application/use-cases/customer"
    click AP2 "https://github.com/gsthalves/customers/tree/develop/api/src/application/errors/customer"
    click DO1 "https://github.com/gsthalves/customers/tree/develop/api/src/domain/entities/customers"
    click DO2 "https://github.com/gsthalves/customers/tree/develop/api/src/domain/contracts"
    click DO3 "https://github.com/gsthalves/customers/tree/develop/api/src/domain/enums/customer"
    click DO4 "https://github.com/gsthalves/customers/tree/develop/api/src/domain/errors/commons"
    click IAD1 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/adapters/dynamodb"
    click IAD2 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/adapters/opensearch"
    click IAD3 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/adapters/logger"
    click IR1 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/repositories/dynamodb/customer"
    click IR2 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/repositories/opensearch/customer"
    click INF3 "https://github.com/gsthalves/customers/tree/develop/api/src/infrastructure/factories"
    click CI1 "https://github.com/gsthalves/customers/tree/develop/infrastructure"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef application fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef infrastructure fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef cloud fill:#e2e3e5,stroke:#aaaaaa,stroke-width:2px;
    classDef external fill:#f0f0f0,stroke:#333,stroke-dasharray:5,5;
    classDef externalDB fill:#d1e7dd,stroke:#0f5132,stroke-width:2px,font-style:italic;
```
