# handrespatrick/clean-serverless-api architecture

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

- Interactive diagram: https://gitdiagram.com/handrespatrick/clean-serverless-api
- Repository: https://github.com/handrespatrick/clean-serverless-api

## Overview

##### Project type and purpose
- This is a serverless HTTP API (no UI) built with Node.js and TypeScript, following Clean Architecture and DDD principles.
- Its sole use case is “get user by name” against the Star Wars API (https://swapi.dev).

##### File structure
- Top-level:
- serverless.yaml – defines the AWS Lambda function and HTTP endpoint (API Gateway).
- src/
– application/ (use-case orchestration and protocol definitions)
– domain/ (core business interfaces, entities, exceptions)
– infra/ (concrete adapters & gateways: HTTP client, Star Wars gateway implementation)
– main/ (entrypoint, DI-style factories, environment config, routing)
– presentation/ (controllers, HTTP helpers, request/response models)
- Tests mirror each layer.
- Build/config: tsconfig.json, package.json scripts, GitHub Actions, linting, SonarQube, etc.

##### Key README insights
- Clean Architecture layers (presentation → application → domain → infra).
- Technology stack: Node.js, TypeScript, Serverless Framework (AWS Lambda + API Gateway), Jest for tests.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Serverless Infrastructure
    subgraph "Serverless Infrastructure"
        direction TB
        APIGateway["API Gateway (GET /user)"]:::external
        Lambda["AWS Lambda Function"]:::infrastructure
    end

    APIGateway -->|"HTTP Request"| Lambda

    %% Lambda Function Container
    subgraph "Lambda Function"
        direction TB

        %% Main / Entrypoint
        subgraph "Entrypoint / Configuration"
            direction TB
            EnvConfig["Env & Routing"]:::infrastructure
            RouteDef["HTTP Route Definition"]:::infrastructure
        end

        EnvConfig --> RouteDef

        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            ControllerProt["IController"]:::presentation
            Controller["GetUserByName Controller"]:::presentation
            HTTPHelper["HTTP Helpers"]:::presentation
            CommonHelper["Common Helpers"]:::presentation
            ModelsHttp["HTTP Models"]:::presentation
            ModelsGateway["Gateway Models"]:::presentation
        end

        RouteDef -->|"handle()"| Controller
        Controller -->|"implements IController"| ControllerProt
        Controller -->|"use HTTP Helpers"| HTTPHelper
        Controller --> CommonHelper
        Controller --> ModelsHttp
        Controller --> ModelsGateway

        %% Application Layer
        subgraph "Application Layer"
            direction TB
            UseCaseProtHTTP["IHttpClient"]:::application
            UseCaseProtGW["IStarWarsGateway"]:::application
            UseCase["GetUserByName Use Case"]:::application
        end

        Controller -->|"execute()"| UseCase
        UseCase -->|"depends on IHttpClient"| UseCaseProtHTTP
        UseCase -->|"depends on IStarWarsGateway"| UseCaseProtGW

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            DomainProt["IGetUserByName"]:::domain
            NotFoundEx["NotFoundException"]:::domain
        end

        UseCaseProtGW -->|"adheres to IGetUserByName"| DomainProt
        UseCase -->|"throws"| NotFoundEx

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            direction TB
            HttpAdapterImpl["HTTP Adapter Implementation"]:::infra
            SWGatewayImpl["StarWars Gateway Implementation"]:::infra
        end

        UseCaseProtHTTP --> HttpAdapterImpl
        DomainProt -->|"implemented by"| SWGatewayImpl
        HttpAdapterImpl -->|"HTTP call"| SWAPI

    end

    %% External Service
    SWAPI["SWAPI (swapi.dev)"]:::external
    SWGatewayImpl -->|"GET /people?search=name"| SWAPI

    %% Dependency Injection Factories
    subgraph "Factories"
        direction TB
        ControllerFactory["MakeGetUserByNameController"]:::infrastructure
        UseCaseFactory["MakeGetUserByNameUseCase"]:::infrastructure
        HttpAdapterFactory["MakeHttpAdapter"]:::infrastructure
        SWGatewayFactory["MakeStarWarsGateway"]:::infrastructure
    end

    Lambda --> EnvConfig
    EnvConfig --> ControllerFactory
    ControllerFactory --> Controller
    ControllerFactory --> UseCaseFactory
    UseCaseFactory --> UseCase
    UseCaseFactory --> SWGatewayFactory
    SWGatewayFactory --> SWGatewayImpl
    SWGatewayFactory --> HttpAdapterFactory
    HttpAdapterFactory --> HttpAdapterImpl

    %% Click Events
    click APIGateway "https://github.com/handrespatrick/clean-serverless-api/blob/main/serverless.yaml"
    click EnvConfig "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/config/env.ts"
    click RouteDef "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/routes/get-user-by-name-route.ts"
    click Controller "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/controllers/get-user-by-name.controller.ts"
    click HTTPHelper "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/helpers/http.helper.ts"
    click CommonHelper "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/helpers/common.helper.ts"
    click ModelsHttp "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/models/http.model.ts"
    click ModelsGateway "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/models/gateway.model.ts"
    click ControllerProt "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/presentation/protocols/controller.protocol.ts"
    click UseCase "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/application/usecases/get-user-by-name.usecase.ts"
    click UseCaseProtGW "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/application/protocols/starwars-gateway.protocol.ts"
    click UseCaseProtHTTP "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/application/protocols/http-adapter.protocol.ts"
    click DomainProt "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/domain/protocols/get-user-by-name.protocol.ts"
    click NotFoundEx "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/domain/exceptions/not-found.exception.ts"
    click HttpAdapterImpl "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/infra/adapters/http.adapter.ts"
    click SWGatewayImpl "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/infra/gateways/starwars.gateway.ts"
    click ControllerFactory "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/factories/controllers/make-get-user-by-name-controller.factory.ts"
    click UseCaseFactory "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/factories/usecases/make-get-user-by-name-usecase.factory.ts"
    click HttpAdapterFactory "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/factories/infra/adapters/make-http-adapter.factory.ts"
    click SWGatewayFactory "https://github.com/handrespatrick/clean-serverless-api/blob/main/src/main/factories/infra/gateways/make-starwars-gateway.factory.ts"

    %% Styles
    classDef presentation fill:#cce5ff,stroke:#004085,color:#004085;
    classDef application fill:#d4edda,stroke:#155724,color:#155724;
    classDef domain fill:#fff3cd,stroke:#856404,color:#856404;
    classDef infra fill:#ffe5b4,stroke:#e69500,color:#e69500;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef infrastructure fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
