# kokeitor/node-express-ts-public architecture

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

- Interactive diagram: https://gitdiagram.com/kokeitor/node-express-ts-public
- Repository: https://github.com/kokeitor/node-express-ts-public

## Overview

##### Project type and purpose
- This is a backend RESTful API service built with Node.js, Express and TypeScript, structured according to Clean Architecture.
- Its primary responsibilities are user authentication (JWT + role-based access), user CRUD operations against a PostgreSQL database, email-verification via the Resend service, and professional logging/monitoring via Better Stack.

##### File structure
- Top-level directories:
- src/presentation – HTTP layer: Express app entrypoint, routers, controllers, middleware.
- src/domain – Pure business logic: entities, DTOs, use-cases, repository interfaces, error definitions.
- src/infrastructure – Implementation of domain interfaces: data sources, mappers, repository concrete classes.
- src/adapters – Third-party integrations: bcrypt, JWT, Resend email client.
- src/config – Environment, database connection (PostgreSQL), logging (Winston), validation (Zod).
- data – Static assets: SQL scripts, email templates.
- tests – Supertest/Jest test suites for API, auth, CRUD and health checks.
- Configuration and deployment files:
- .github/workflows/deploy-pipeline.yaml – CI/CD pipeline.
- example.env/.secrets/ca.pem – Environment and DB certificates.
- tsconfig.json, eslint.config.mjs – TypeScript and lint settings.

##### README for additional insights
- Confirms Clean Architecture and modular patterns (ports & adapters).
- Lists key features: JWT authentication middleware, role validation, user CRUD, email verification.
- Mentions technology stack: Node.js, Express.js, TypeScript, PostgreSQL on Aiven Cloud, Better Stack logging, GitHub Actions CI/CD.
- Testing strategy: Jest + Supertest, parallelized tests, lint & transpile.

##### Detail level
- Critical modules: routes, controllers, use-cases, repositories, data sources, adapters
- Do not collapse the domain layer—show individual use-cases and repository interfaces
- Config/environment as a side component that feeds into app initialization
- Test suite in a separate lane to show coverage of routes and use-cases

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Clients["External Clients\n(Postman, Web UI, Other Services)"]:::external
    Clients --> ExpressApp

    %% Express App Entry
    ExpressApp["Express App Entry Point"]:::presentation
    click ExpressApp "https://github.com/kokeitor/node-express-ts-public/blob/master/src/app.ts"

    %% Application Initialization
    ExpressApp --> AppInit
    AppInit["App Initialization"]:::presentation
    click AppInit "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/apps/app.ts"

    %% Configuration
    subgraph "Configuration"
        configApp["App & Env Setup"]:::config
        configDB["Database Config"]:::config
        configLog["Logging Config"]:::config
        configZod["Validation (Zod)"]:::config
    end
    ExpressApp --> configApp
    ExpressApp --> configDB
    ExpressApp --> configLog
    ExpressApp --> configZod
    click configApp "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/app.ts"
    click configApp "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/envs.ts"
    click configApp "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/index.ts"
    click configDB "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/postgresql.ts"
    click configLog "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/winston.ts"
    click configZod "https://github.com/kokeitor/node-express-ts-public/blob/master/src/config/zod.validator.ts"

    %% Presentation Layer
    subgraph "Presentation Layer"
        AuthMiddleware["Authentication Middleware"]:::presentation
        CommonMiddleware["Common/Error Handling Middleware"]:::presentation
        AuthRoutes["Auth Routes"]:::presentation
        CRUDRoutes["CRUD Routes"]:::presentation
        AuthController["Auth Controller"]:::presentation
        CRUDController["CRUD Controller"]:::presentation
    end
    click AuthMiddleware "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/middleware/auth/auth.ts"
    click CommonMiddleware "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/middleware/common.ts"
    click AuthRoutes "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/auth/routes.ts"
    click CRUDRoutes "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/crud/routes.ts"
    click AuthController "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/auth/controller.ts"
    click CRUDController "https://github.com/kokeitor/node-express-ts-public/blob/master/src/presentation/crud/controller.ts"

    AppInit --> AuthMiddleware
    AuthMiddleware --> CommonMiddleware
    CommonMiddleware --> AuthRoutes
    CommonMiddleware --> CRUDRoutes
    AuthRoutes --> AuthController
    CRUDRoutes --> CRUDController

    %% Domain Layer
    subgraph "Domain Layer"
        entityUser["User Entity"]:::domain
        dtoLogin["Login DTO"]:::domain
        dtoRegister["Register DTO"]:::domain
        dtoCRUD["CRUD DTO"]:::domain
        repoAuthIntf["Auth Repository Interface"]:::domain
        repoCRUDIntf["CRUD Repository Interface"]:::domain
        ucLogin["Login Use-Case"]:::domain
        ucRegister["Register Use-Case"]:::domain
        ucSendEmail["Send Email Verification"]:::domain
        ucValidateToken["Validate User Token"]:::domain
        ucValidateRole["Validate User Role"]:::domain
        ucVerifyUser["Verify User"]:::domain
        dsIntf["Postgres CRUD Data Source Interface"]:::domain
    end
    click entityUser "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/entities/user.entitiy.ts"
    click dtoLogin "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/dtos/auth/login-user.dto.ts"
    click dtoRegister "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/dtos/auth/register-user.dto.ts"
    click dtoCRUD "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/dtos/crud/crud-user.dto.ts"
    click repoAuthIntf "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/repositories/auth/auth.repository.ts"
    click repoCRUDIntf "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/repositories/crud/crud.repository.ts"
    click ucLogin "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/login-user.use-case.ts"
    click ucRegister "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/register-user.use-case.ts"
    click ucSendEmail "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/send-email-verification.use-case.ts"
    click ucValidateToken "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/validate-user-token.use-case.ts"
    click ucValidateRole "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/validate-user-rol.use-case.ts"
    click ucVerifyUser "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/use-cases/auth/verify-user.use-case.ts"
    click dsIntf "https://github.com/kokeitor/node-express-ts-public/blob/master/src/domain/datasources/crud/postgres.datasource.ts"

    AuthController --> ucLogin
    AuthController --> ucRegister
    AuthController --> ucSendEmail
    AuthController --> ucVerifyUser
    CRUDController --> dsIntf

    ucLogin --> repoAuthIntf
    ucRegister --> repoAuthIntf
    ucSendEmail --> adapterResend
    ucValidateToken --> adapterJWT
    ucValidateRole --> adapterJWT
    ucVerifyUser --> repoAuthIntf
    dsIntf --> repoCRUDIntf

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        dsImpl["CRUD Data Source Impl"]:::infra
        mapperUser["User Mapper"]:::infra
        repoAuthImpl["Auth Repo Impl"]:::infra
        repoCRUDImpl["CRUD Repo Impl"]:::infra
    end
    click dsImpl "https://github.com/kokeitor/node-express-ts-public/blob/master/src/infrastructure/datasources/crud/crud.datasource.impl.ts"
    click mapperUser "https://github.com/kokeitor/node-express-ts-public/blob/master/src/infrastructure/mappers/user.mapper.ts"
    click repoAuthImpl "https://github.com/kokeitor/node-express-ts-public/blob/master/src/infrastructure/repositories/auth/auth.repository.impl.ts"
    click repoCRUDImpl "https://github.com/kokeitor/node-express-ts-public/blob/master/src/infrastructure/repositories/crud/crud.repository.impl.ts"

    repoAuthIntf --> repoAuthImpl
    repoCRUDIntf --> repoCRUDImpl
    dsIntf --> dsImpl
    dsImpl --> mapperUser
    repoAuthImpl --> dsImpl
    repoCRUDImpl --> dsImpl

    %% Adapter Layer
    subgraph "Adapter Layer"
        adapterBcrypt["Bcrypt Adapter"]:::adapter
        adapterJWT["JWT Adapter"]:::adapter
        adapterResend["Resend Email Adapter"]:::adapter
    end
    click adapterBcrypt "https://github.com/kokeitor/node-express-ts-public/blob/master/src/adapters/bcrypt.adapter.ts"
    click adapterJWT "https://github.com/kokeitor/node-express-ts-public/blob/master/src/adapters/jwt.adapter.ts"
    click adapterResend "https://github.com/kokeitor/node-express-ts-public/blob/master/src/adapters/resend.adapter.ts"

    ucRegister --> adapterBcrypt
    ucLogin --> adapterBcrypt
    ucLogin --> adapterJWT
    ucRegister --> adapterJWT

    %% External Systems
    PostgresDB["PostgreSQL (Aiven Cloud)"]:::external
    ResendService["Resend Email API"]:::external
    BetterStack["Better Stack Logging"]:::external

    dsImpl --> PostgresDB
    adapterResend --> ResendService
    configLog --> BetterStack

    %% Static Assets
    subgraph "Static Assets"
        sqlScripts["SQL Scripts"]:::external
        emailTemp1["Email Template Basic"]:::external
        emailTemp2["Email Template Pro"]:::external
    end
    click sqlScripts "https://github.com/kokeitor/node-express-ts-public/blob/master/data/postgresql/sql/users.sql"
    click emailTemp1 "https://github.com/kokeitor/node-express-ts-public/blob/master/data/email/email-verification-content.html"
    click emailTemp2 "https://github.com/kokeitor/node-express-ts-public/blob/master/data/email/email-verification-content-pro.html"

    %% Testing
    subgraph "Testing"
        apiTest["API & Health Tests"]:::test
        authTest["Auth Tests"]:::test
        crudTest["CRUD Tests"]:::test
    end
    click apiTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/api.test.ts"
    click apiTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/health/health.test.ts"
    click authTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/auth/login-user.test.ts"
    click authTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/auth/helper.ts"
    click crudTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/crud/put.test.ts"
    click crudTest "https://github.com/kokeitor/node-express-ts-public/blob/master/src/tests/crud/helper.ts"
    apiTest --> AuthRoutes
    apiTest --> CRUDRoutes
    apiTest --> AppInit

    %% CI/CD Pipeline
    CICDPipeline["CI/CD Pipeline"]:::ci
    click CICDPipeline "https://github.com/kokeitor/node-express-ts-public/blob/master/.github/workflows/deploy-pipeline.yaml"
    CICDPipeline --> AppInit

    %% Styles
    classDef presentation fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef domain fill:#E6FFE6,stroke:#2c662d,color:#2c662d;
    classDef infra fill:#FFF4E6,stroke:#d2691e,color:#d2691e;
    classDef adapter fill:#F3E6FF,stroke:#6e2dd0,color:#6e2dd0;
    classDef external fill:#F0F0F0,stroke:#999,color:#555;
    classDef config fill:#FFFBE6,stroke:#b8860b,color:#b8860b;
    classDef test fill:#FFE6E6,stroke:#d02d2d,color:#d02d2d;
    classDef ci fill:#FFEAF0,stroke:#d02d4b,color:#d02d4b;
```
