# renatops1991/saturn-service architecture

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

- Interactive diagram: https://gitdiagram.com/renatops1991/saturn-service
- Repository: https://github.com/renatops1991/saturn-service

## Overview

##### Project Type and Purpose
- This is a standalone backend microservice (REST API) for user management (creation, authentication, profile updates) written in TypeScript/Node.js with Express and MongoDB.
- It follows a Clean-Architecture/Onion-style layering (presentation → application/use-cases → domain → infrastructure).

##### Core Architectural Layers & Components
- **Clients/Consumers**: Any HTTP client (browser, mobile app, Postman) invoking the API endpoints.
- **API Gateway (Express Server)**
- Entry point (`src/main/server.ts`) with global middleware (CORS, body-parser, content-type).
- Routes defined in `src/main/config/routes.ts` and adapted via `express-route-adapter.ts`.
- **Presentation Layer**
- **Controllers** (`src/presentation/controllers/…`): Handle HTTP requests/responses, use `http-helper.ts`.
- **Middleware** (`src/presentation/middlewares/auth-middleware.ts`): Enforce JWT auth.
- **Application Layer (Use Cases)**
- **Use-Case Interactors** (`src/data/use-cases/user.ts`): Business rules for signup, signin, fetch/update user.
- **Validation Composite** (`src/validation/validation-composite.ts` + factories): Validate incoming DTOs.
- **Domain Layer**
- **Entities** (`src/domain/entities/user.ts`, `address.ts`): Core business objects.
- **Protocols/Interfaces** (`src/domain/protocols/*.ts`): Abstractions for authentication, user repository.
- **Infrastructure Layer**
- **Data Persistence**
- **MongoDB Adapter** (`src/infra/mongodb/user-repository-mongo-adapter.ts`, `mongo-helper.ts`) implements `UserRepository` protocol.
- **Cryptography**
- **Bcrypt Adapter** (`bcrypt-adapter.ts`) and **JWT Adapter** (`jwt-adapter.ts`) implement `Authentication` and `Hashed` protocols.
- **Validators** (`email-validator-adapter.ts`) implement `EmailValidator` protocol.
- **Composition Root (Factories)**
- Wiring all dependencies (`src/main/factories/*.ts`): controllers, use-cases, middleware, validators.

##### Data Flow & Interactions
1. **HTTP Request** → Express middleware (CORS, parsing, content-type).
2. **Route Matching** → `express-route-adapter` → Selected Controller.
3. **Controller**
- Extracts DTO
- Runs validation composite
- Calls Use-Case interactor
4. **Use-Case**
- Uses domain protocols to orchestrate:
- Password hashing via Bcrypt Adapter
- JWT token creation via JWT Adapter
- CRUD via MongoDB Adapter
- Returns domain entity or token.
5. **Controller** formats response via `http-helper` → HTTP Response.

##### Key Architectural Patterns
- **Factory Method**: For creating controllers, express middleware, validation composites.
- **Adapter**: Express adapters, MongoDB adapter, cryptography adapters, email validator adapter.
- **Composite**: Validation pipeline combining multiple field checks.
- **Builder**: `user-builder.ts` for test fixtures and data assembly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["HTTP Client"]:::external

    %% API Gateway Layer
    subgraph "API Gateway"
        Server["Express Server"]:::gateway
        MiddlewareCfg["Global Middleware"]:::middleware
        Routes["Route Definitions"]:::config
        ExpressRouteAdapter["Express Route Adapter"]:::adapter
        ExpressMiddlewareAdapter["Express Middleware Adapter"]:::adapter
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        subgraph Controllers
            SignUpController["SignUpController"]:::presentation
            SignInController["SignInController"]:::presentation
            GetUserController["GetUserController"]:::presentation
            GetAllUsersController["GetAllUsersController"]:::presentation
            UpdateUserController["UpdateUserController"]:::presentation
            UpdateUserPasswordController["UpdateUserPasswordController"]:::presentation
            UpdateConfirmUserController["UpdateConfirmUserController"]:::presentation
        end
        subgraph Protocols_Http
            HttpHelper["HTTP Helper"]:::protocol
            ControllerProtocol["Controller Protocol"]:::protocol
            HttpProtocol["HTTP Protocol Types"]:::protocol
            MiddlewareProtocol["Middleware Protocol"]:::protocol
            ValidationProtocol["Validation Protocol"]:::protocol
        end
        AuthMiddleware["Auth Middleware"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        UseCase["User Use-Case Interactor"]:::usecase
        DTOs["DTOs"]:::dto
        ValidationComposite["Validation Composite"]:::usecase
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Entities["Entities"]:::domain
        Protocols["Protocols/Interfaces"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        subgraph "Persistence"
            MongoHelper["Mongo Helper"]:::infra
            UserRepoAdapter["UserRepositoryMongoAdapter"]:::infra
        end
        subgraph "Cryptography"
            BcryptAdapter["Bcrypt Adapter"]:::infra
            JwtAdapter["JWT Adapter"]:::infra
        end
        EmailValidator["Email Validator Adapter"]:::infra
    end

    %% Database
    MongoDB["MongoDB"]:::db

    %% Composition Root
    CompositionRoot["Composition Root<br/>(Factories)"]:::factory

    %% Data Flow
    Client -->|HTTP Request| Server
    Server --> MiddlewareCfg
    MiddlewareCfg --> ExpressMiddlewareAdapter
    Server --> Routes
    Routes --> ExpressRouteAdapter

    ExpressRouteAdapter --> SignUpController
    ExpressRouteAdapter --> SignInController
    ExpressRouteAdapter --> GetUserController
    ExpressRouteAdapter --> GetAllUsersController
    ExpressRouteAdapter --> UpdateUserController
    ExpressRouteAdapter --> UpdateUserPasswordController
    ExpressRouteAdapter --> UpdateConfirmUserController

    SignUpController -->|uses| HttpHelper
    SignUpController -->|validates| ValidationComposite
    SignInController -->|uses| HttpHelper
    SignInController -->|validates| ValidationComposite

    ValidationComposite -->|builds| DTOs
    ValidationComposite -->|implements| ValidationProtocol

    SignUpController --> UseCase
    SignInController --> UseCase
    GetUserController --> UseCase
    GetAllUsersController --> UseCase
    UpdateUserController --> UseCase
    UpdateUserPasswordController --> UseCase
    UpdateConfirmUserController --> UseCase

    UseCase -->|calls| Protocols
    Protocols -->|implemented by| UserRepoAdapter
    Protocols -->|uses| BcryptAdapter
    Protocols -->|uses| JwtAdapter
    UseCase -->|persistent| UserRepoAdapter

    UserRepoAdapter --> MongoHelper
    UserRepoAdapter --> MongoDB

    CompositionRoot --> SignUpController
    CompositionRoot --> SignInController
    CompositionRoot --> GetUserController
    CompositionRoot --> GetAllUsersController
    CompositionRoot --> UpdateUserController
    CompositionRoot --> UpdateUserPasswordController
    CompositionRoot --> UpdateConfirmUserController
    CompositionRoot --> ValidationComposite
    CompositionRoot --> AuthMiddleware

    AuthMiddleware -->|uses| MiddlewareProtocol
    CompositionRoot -->|wires| AuthMiddleware

    %% Click Events
    click Server "https://github.com/renatops1991/saturn-service/blob/production/src/main/server.ts"
    click MiddlewareCfg "https://github.com/renatops1991/saturn-service/blob/production/src/main/config/middleware.ts"
    click Routes "https://github.com/renatops1991/saturn-service/blob/production/src/main/config/routes.ts"
    click ExpressRouteAdapter "https://github.com/renatops1991/saturn-service/blob/production/src/main/adapters/express-route-adapter.ts"
    click ExpressMiddlewareAdapter "https://github.com/renatops1991/saturn-service/blob/production/src/main/adapters/express-middleware-adapter.ts"
    click SignUpController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/signup-user-controller.ts"
    click SignInController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/signin-user-controller.ts"
    click GetUserController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/get-user-controller.ts"
    click GetAllUsersController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/get-all-users-controller.ts"
    click UpdateUserController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/update-user-controller.ts"
    click UpdateUserPasswordController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/update-user-password-controller.ts"
    click UpdateConfirmUserController "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/controllers/user/update-confirm-user-controller.ts"
    click HttpHelper "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/http-helper.ts"
    click ControllerProtocol "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/protocols/controller.ts"
    click HttpProtocol "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/protocols/http.ts"
    click MiddlewareProtocol "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/protocols/middleware.ts"
    click ValidationProtocol "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/protocols/validation.ts"
    click AuthMiddleware "https://github.com/renatops1991/saturn-service/blob/production/src/presentation/middlewares/auth-middleware.ts"
    click UseCase "https://github.com/renatops1991/saturn-service/blob/production/src/data/use-cases/user.ts"
    click CompositionRoot "https://github.com/renatops1991/saturn-service/blob/production/src/main/factories/user-factory.ts"
    click DTOs "https://github.com/renatops1991/saturn-service/tree/production/src/main/dtos"
    click ValidationComposite "https://github.com/renatops1991/saturn-service/blob/production/src/validation/validation-composite.ts"
    click MongoHelper "https://github.com/renatops1991/saturn-service/blob/production/src/infra/mongodb/mongo-helper.ts"
    click UserRepoAdapter "https://github.com/renatops1991/saturn-service/blob/production/src/infra/mongodb/user-repository-mongo-adapter.ts"
    click BcryptAdapter "https://github.com/renatops1991/saturn-service/blob/production/src/infra/cryptography/bcrypt-adapter.ts"
    click JwtAdapter "https://github.com/renatops1991/saturn-service/blob/production/src/infra/cryptography/jwt-adapter.ts"
    click EmailValidator "https://github.com/renatops1991/saturn-service/blob/production/src/infra/validators/email-validator-adapter.ts"

    %% Styles
    classDef external fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef gateway fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef middleware fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
    classDef adapter fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef presentation fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef protocol fill:#d6d8db,stroke:#1b1e21,stroke-width:1px
    classDef usecase fill:#ffe5b4,stroke:#cc7a00,stroke-width:1px
    classDef dto fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef domain fill:#cfe2ff,stroke:#084298,stroke-width:1px
    classDef infra fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef db fill:#ced4da,stroke:#343a40,stroke-width:1px
    classDef factory fill:#f8d7da,stroke:#721c24,stroke-width:1px
```
