# rmanguinho/clean-ts-api architecture

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

- Interactive diagram: https://gitdiagram.com/rmanguinho/clean-ts-api
- Repository: https://github.com/rmanguinho/clean-ts-api

## Overview

##### Project Type and Purpose
- This is a backend API built with Node.js and TypeScript following Clean Architecture.
- It exposes both REST (Express) and GraphQL (Apollo Server) endpoints.
- It’s architected for TDD, SOLID, DDD and supports user signup/login, survey creation/listing, survey answers and results.
- MongoDB serves as the persistence layer.

##### Key Layers from the File Tree
- src/main – framework adapters, server bootstrap, routing, documentation (Swagger), GraphQL setup.
- src/presentation – controllers, HTTP helper, middleware, error types.
- src/validation / src/infra/validators – request validation adapters and rules.
- src/domain – core business models (Survey, SurveyResult, Account) and use-case interfaces.
- src/data – implementations of those use-case interfaces, plus repository protocols (DB, crypto).
- src/infra – concrete adapters for cryptography (bcrypt, JWT), MongoDB repositories, helpers, validators.
- tests – unit and integration tests for each layer.

a. Main Components
- Clients: REST clients (e.g. Postman), GraphQL clients.
- API Gateway Layer: Express server + middleware, Apollo Server.
- Presentation Layer: Route adapters → Controllers → HTTP Responses.
- Validation Layer: Validation composite → specific validators.
- Application/Use-Case Layer: Interactors that orchestrate business rules.
- Domain Layer: Entities and use-case interfaces.
- Data Layer (Ports & Adapters): Repository interfaces (addAccount, loadSurveys, etc.), cryptography interfaces.
- Infrastructure Layer: MongoDB adapters, bcrypt/jwt adapters, logger adapter.
- External Services: MongoDB, Swagger UI for docs, static file server.

b. Relationships & Data Flow
1. Client → HTTP/GraphQL request arrives at Express/Apollo (API Gateway).
2. Request passes through global and route-specific middleware (CORS, bodyParser, auth, validation).
3. Adapter transforms raw request into Controller input.
4. Controller invokes the corresponding Use-Case interactor via Factory.
5. Use-Case calls Domain Entities and Ports (repository and crypto interfaces).
6. Ports are implemented by Infrastructure adapters (MongoDB, Bcrypt, JWT).
7. Data flows back up: DB → Use-Case → Controller → Response.

c. Architectural Patterns & Principles
- Onion/Clean Architecture: strict layer separation, depend-inversion.
- Factory Pattern: wiring dependencies in src/main/factories.
- Adapter Pattern: protocol adapters for Express, Apollo, MongoDB, crypto.
- Decorator Pattern: log-controller-decorator wraps controllers for error logging.
- Middleware as chain of responsibility.

d. Key Technologies & Frameworks
- Express.js, Apollo Server Express for HTTP/GraphQL.
- TypeScript with tsconfig path aliases.
- MongoDB via native driver / custom query-builder.
- Bcrypt & JSON Web Token for hashing/auth.
- Swagger (openapi) for REST docs.
- Jest + in-memory-mongo for tests.

##### Essential Elements to Capture
- Entry points: Express routes, GraphQL schema/resolvers.
- Middleware chain (auth, validation, error-handling).
- Controller → Use-Case interactions.
- Ports (interfaces) vs Adapters (concrete repos, crypto).
- Factory/Composition Root at top level wiring everything.
- External dependencies: MongoDB, Bcrypt, JWT, Swagger UI.

## Diagram (Mermaid)

```mermaid
graph TB
  %% API Gateway & Presentation
  subgraph "API Gateway & Presentation"
    SG1["Express Server Bootstrap"]:::blue
    SwaggerDoc["Swagger UI Documentation"]:::blue
    Docs["docs (Swagger)"]:::blue
    StaticFilesCfg["Static File Serving Config"]:::blue
    EnvCfg["Environment Config"]:::blue
    AppCfg["App Configuration"]:::blue
    RoutesCfg["REST Routing Configuration"]:::blue
    RESTRoutes["REST Route Files"]:::blue
    GraphQLServer["Apollo GraphQL Server"]:::blue
    TypeDefs["GraphQL Type Definitions"]:::blue
    Resolvers["GraphQL Resolvers"]:::blue
    MiddlewaresCfg["Global & Route Middleware Chain"]:::blue
    RouteMws["Route Middleware Implementations"]:::blue
    ExRouteAdapter["Express Route Adapter"]:::blue
    ExMwAdapter["Express Middleware Adapter"]:::blue
    ApResolverAdapter["Apollo Resolver Adapter"]:::blue
    Decorator["Controller Logging Decorator"]:::blue
    FactoriesIndex["Composition Root (Factories)"]:::blue
  end

  %% Factories Modules
  subgraph "Factories"
    FControllers["Controller Factories"]:::blue
    FUseCases["Use-Case Factories"]:::blue
    FMiddlewares["Middleware Factories"]:::blue
    FDecorators["Decorator Factories"]:::blue
  end

  %% Presentation Layer
  subgraph "Presentation Layer"
    Controllers["Controllers"]:::blue
    HttpHelper["HTTP Helper"]:::blue
    PresMiddlewares["Presentation Middlewares"]:::blue
    PresProtocols["Presentation Protocols"]:::blue
  end

  %% Validation Layer
  subgraph "Validation Layer"
    ValComposite["Validation Composites & Rules"]:::orange
    ValProtocols["Validation Protocols"]:::orange
  end

  %% Application & Domain Layer
  subgraph "Application & Domain Layer"
    UseCases["Use-Case Interactors"]:::green
    DomainEntities["Domain Entities"]:::green
    DomainPorts["Domain Use-Case Interfaces"]:::green
  end

  %% Data Layer Protocols
  subgraph "Data Layer Protocols"
    DataProtocols["Repository & Crypto Protocols"]:::orange
  end

  %% Infrastructure & External Services
  subgraph "Infrastructure & External"
    Bcrypt["Bcrypt Adapter"]:::red
    JWT["JWT Adapter"]:::red
    MongoRepo["MongoDB Repositories"]:::red
    MongoHelper["Mongo Helper"]:::red
    QueryBuilder["Mongo Query Builder"]:::red
    MongoDB["MongoDB Database"]:::red
    SwaggerUIStatic["Swagger UI (Static Docs)"]:::red
  end

  %% Connections
  SG1 -->|"uses"| RoutesCfg
  SG1 -->|"serves"| StaticFilesCfg
  SG1 -->|"loads"| EnvCfg
  SG1 -->|"loads"| AppCfg
  SG1 -->|"initializes"| MiddlewaresCfg
  SG1 -->|"boots"| GraphQLServer
  SG1 -->|"sets up"| SwaggerDoc
  SG1 -->|"roots"| FactoriesIndex

  RoutesCfg --> RESTRoutes
  RESTRoutes --> ExRouteAdapter
  ExRouteAdapter --> Controllers

  GraphQLServer --> TypeDefs
  GraphQLServer --> Resolvers
  Resolvers --> ApResolverAdapter
  ApResolverAdapter --> Controllers

  MiddlewaresCfg --> RouteMws
  RouteMws --> ExMwAdapter
  ExMwAdapter --> FactoriesIndex

  FactoriesIndex --> FControllers
  FactoriesIndex --> FUseCases
  FactoriesIndex --> FMiddlewares
  FactoriesIndex --> FDecorators

  FControllers --> Controllers
  FMiddlewares --> PresMiddlewares
  Controllers --> HttpHelper

  Controllers -->|validates via| ValComposite
  ValComposite --> ValProtocols

  Controllers -->|calls| UseCases
  UseCases --> DomainEntities
  UseCases --> DomainPorts

  DomainPorts --> DataProtocols
  DataProtocols --> Bcrypt
  DataProtocols --> JWT
  DataProtocols --> MongoRepo

  MongoRepo --> MongoHelper
  MongoRepo --> QueryBuilder
  MongoRepo --> MongoDB

  SwaggerDoc --> SwaggerUIStatic

  %% Click Events
  click SG1 "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/server.ts"
  click SwaggerDoc "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/swagger.ts"
  click Docs "https://github.com/rmanguinho/clean-ts-api/tree/master/src/main/docs"
  click StaticFilesCfg "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/static-files.ts"
  click EnvCfg "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/env.ts"
  click AppCfg "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/app.ts"
  click RoutesCfg "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/routes.ts"
  click RESTRoutes "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/routes/*.ts"
  click GraphQLServer "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/graphql/apollo/apollo-server.ts"
  click TypeDefs "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/graphql/type-defs/*.ts"
  click Resolvers "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/graphql/resolvers/*.ts"
  click MiddlewaresCfg "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/config/middlewares.ts"
  click RouteMws "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/middlewares/*.ts"
  click ExRouteAdapter "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/adapters/express-route-adapter.ts"
  click ExMwAdapter "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/adapters/express-middleware-adapter.ts"
  click ApResolverAdapter "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/adapters/apollo-server-resolver-adapter.ts"
  click Decorator "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/decorators/log-controller-decorator.ts"
  click FactoriesIndex "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/factories/index.ts"
  click FControllers "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/factories/controllers/*.ts"
  click FUseCases "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/factories/usecases/*.ts"
  click FMiddlewares "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/factories/middlewares/*.ts"
  click FDecorators "https://github.com/rmanguinho/clean-ts-api/blob/master/src/main/factories/decorators/*.ts"
  click Controllers "https://github.com/rmanguinho/clean-ts-api/blob/master/src/presentation/controllers/*.ts"
  click HttpHelper "https://github.com/rmanguinho/clean-ts-api/blob/master/src/presentation/helpers/http-helper.ts"
  click PresMiddlewares "https://github.com/rmanguinho/clean-ts-api/blob/master/src/presentation/middlewares/*.ts"
  click PresProtocols "https://github.com/rmanguinho/clean-ts-api/blob/master/src/presentation/protocols/*.ts"
  click ValComposite "https://github.com/rmanguinho/clean-ts-api/blob/master/src/validation/validators/*.ts"
  click ValProtocols "https://github.com/rmanguinho/clean-ts-api/blob/master/src/validation/protocols/*.ts"
  click DataProtocols "https://github.com/rmanguinho/clean-ts-api/tree/master/src/data/protocols/**/*"
  click UseCases "https://github.com/rmanguinho/clean-ts-api/blob/master/src/data/usecases/*.ts"
  click DomainEntities "https://github.com/rmanguinho/clean-ts-api/blob/master/src/domain/models/*.ts"
  click DomainPorts "https://github.com/rmanguinho/clean-ts-api/blob/master/src/domain/usecases/*.ts"
  click Bcrypt "https://github.com/rmanguinho/clean-ts-api/blob/master/src/infra/cryptography/bcrypt-adapter.ts"
  click JWT "https://github.com/rmanguinho/clean-ts-api/blob/master/src/infra/cryptography/jwt-adapter.ts"
  click MongoRepo "https://github.com/rmanguinho/clean-ts-api/blob/master/src/infra/db/mongodb/*.ts"
  click MongoHelper "https://github.com/rmanguinho/clean-ts-api/blob/master/src/infra/db/mongodb/mongo-helper.ts"
  click QueryBuilder "https://github.com/rmanguinho/clean-ts-api/blob/master/src/infra/db/mongodb/query-builder.ts"

  %% Styles
  classDef blue fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
  classDef green fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
  classDef orange fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
  classDef red fill:#FFEBEE,stroke:#E53935,color:#B71C1C;
```
