# edwinhern/express-typescript architecture

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

- Interactive diagram: https://gitdiagram.com/edwinhern/express-typescript
- Repository: https://github.com/edwinhern/express-typescript

## Overview

##### Project type and purpose
- This is a backend web-service boilerplate built with Express.js and TypeScript.
- Its purpose is to provide a ready-to-use structure for REST APIs, complete with request validation (Zod), logging (pino), middleware (rate-limiter, error handler), and auto-generated OpenAPI docs.

##### File structure
- src/server.ts and src/index.ts initialize and launch the Express server.
- src/api contains feature folders (healthCheck, user) each with router → controller → service → repository layers.
- src/api-docs houses OpenAPI document generator and router for Swagger UI.
- src/common holds cross-cutting middleware (errorHandler, rateLimiter, requestLogger), shared response model, and utilities (envConfig, HTTP handlers, validation).
- Configuration files: .env.template, vite.config.mts (path aliases), tsconfig.json, biome.json (linting), Dockerfile.

##### README
- Highlights tech stack: Node.js, Express, TypeScript, Zod, pino-http, Helmet, CORS, Vitest/Supertest, Docker.
- Mentions folder organization by feature, error handling, auto-update, and API browser (Swagger).

a. Main components
- Client / API Consumer (Postman, frontend)
- Load Balancer / Ingress (optional)
- Express Server Entry Point
- Middleware Layer
– Request Logger
– Rate Limiter
– CORS & Helmet
– Error Handler
- Routing Layer
– Feature Routers (healthCheckRouter, userRouter)
– OpenAPI Router
- Controller Layer
- Service Layer
- Repository Layer / Data Access
- Shared Models & Utils
- OpenAPI Document Generator
- External Services (e.g., Database, Cache)
- Logging Sink (console, files)

b. Relationships and interactions
- Client sends HTTP request → Load Balancer → Express Server → Middleware chain → Router selects feature → Controller invokes Service → Service calls Repository → Repository interacts with Data Store → Service builds a ServiceResponse → Controller sends HTTP response → Middleware error handler catches uncaught errors → Client receives response.
- OpenAPI Router reads generated docs from the document generator module.

c. Architectural patterns & design principles
- Layered architecture (Router → Controller → Service → Repository).
- Separation of concerns: feature-based folder structure.
- Centralized error handling and request logging.
- Dependency inversion through interfaces for serviceResponse and repository.
- Configuration via environment (Zod-validated) and path aliases for clean imports.

d. Relevant technologies/frameworks
- Express.js (HTTP server)
- TypeScript (static typing)
- Zod (validation of .env and request payloads)
- pino-http (logging)
- Vitest + Supertest (testing)
- Swagger (API docs via openAPIRouter)
- Docker (containerization)
- Renovate (dependency updates)
- Biomejs (linting / formatting)

##### Elements
- Middleware: light yellow
- Routers/Controllers: light blue
- Services/Repositories: light green
- External systems (DB, Cache, Logger): grey
- Docs: purple
- Annotations for protocols (HTTP, WebSocket if any), ports, and environment variables.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    Client["Client / API Consumer"]:::external
    LoadBalancer["Load Balancer / Ingress"]:::external
    Database["Database"]:::external
    LoggerSink["Logging Sink\n(console, files)"]:::external

    %% Docker Boundary
    subgraph "Docker Container" 
        direction TB
        EnvConfig["envConfig\n(src/common/utils/envConfig.ts)"]:::config
        Entry["Express Server Entry Point\n(src/index.ts, src/server.ts)"]:::server

        %% Middleware Layer
        subgraph "Middleware Layer"
            direction TB
            RequestLogger["Request Logger\n(src/common/middleware/requestLogger.ts)"]:::middleware
            RateLimiter["Rate Limiter\n(src/common/middleware/rateLimiter.ts)"]:::middleware
            CORSCHelmet["CORS & Helmet"]:::middleware
            ErrorHandler["Error Handler\n(src/common/middleware/errorHandler.ts)"]:::middleware
        end

        %% Routing Layer
        subgraph "Routing Layer"
            direction TB
            HealthRouter["HealthCheck Router\n(src/api/healthCheck/healthCheckRouter.ts)"]:::router
            UserRouter["User Router\n(src/api/user/userRouter.ts)"]:::router
            OpenAPIRouter["OpenAPI Router\n(src/api-docs/openAPIRouter.ts)"]:::docs
        end

        %% Controller Layer
        UserController["User Controller\n(src/api/user/userController.ts)"]:::controller

        %% Service Layer
        UserService["User Service\n(src/api/user/userService.ts)"]:::service

        %% Repository Layer
        UserRepository["User Repository\n(src/api/user/userRepository.ts)"]:::repository

        %% Common Models & Utils
        ServiceResponse["ServiceResponse Model\n(src/common/models/serviceResponse.ts)"]:::model
        CommonValidation["Common Validation\n(src/common/utils/commonValidation.ts)"]:::util
        HTTPHandlers["HTTP Handlers\n(src/common/utils/httpHandlers.ts)"]:::util

        %% OpenAPI Docs Components
        OpenAPIDocGen["OpenAPI Document Generator\n(src/api-docs/openAPIDocumentGenerator.ts)"]:::docs
        OpenAPIBuilders["OpenAPI Response Builders\n(src/api-docs/openAPIResponseBuilders.ts)"]:::docs
    end

    %% Configuration files
    EnvTemplate[".env.template"]:::config
    TSConfig["tsconfig.json\nvite.config.mts"]:::config
    Linting["biome.json"]:::config
    Dockerfile["Dockerfile"]:::config

    %% Request Flow
    Client -->|HTTP Request| LoadBalancer
    LoadBalancer --> Entry
    Entry --> EnvConfig
    Entry --> RequestLogger
    RequestLogger --> RateLimiter
    RateLimiter --> CORSCHelmet
    CORSCHelmet --> HealthRouter
    CORSCHelmet --> UserRouter
    CORSCHelmet --> OpenAPIRouter
    HealthRouter -->|"healthCheck()"| Entry
    UserRouter --> UserController
    OpenAPIRouter --> OpenAPIDocGen
    OpenAPIRouter --> OpenAPIBuilders
    UserController --> ServiceResponse
    UserController --> CommonValidation
    UserController --> HTTPHandlers
    UserController --> UserService
    UserService --> UserRepository
    UserRepository --> Database
    UserService --> ServiceResponse
    Entry --> ErrorHandler
    RequestLogger --> LoggerSink
    OpenAPIDocGen --> OpenAPIBuilders

    %% Click Events
    click Entry "https://github.com/edwinhern/express-typescript/blob/master/src/index.ts"
    click Entry "https://github.com/edwinhern/express-typescript/blob/master/src/server.ts"
    click EnvConfig "https://github.com/edwinhern/express-typescript/blob/master/src/common/utils/envConfig.ts"
    click RequestLogger "https://github.com/edwinhern/express-typescript/blob/master/src/common/middleware/requestLogger.ts"
    click RateLimiter "https://github.com/edwinhern/express-typescript/blob/master/src/common/middleware/rateLimiter.ts"
    click ErrorHandler "https://github.com/edwinhern/express-typescript/blob/master/src/common/middleware/errorHandler.ts"
    click HealthRouter "https://github.com/edwinhern/express-typescript/blob/master/src/api/healthCheck/healthCheckRouter.ts"
    click UserRouter "https://github.com/edwinhern/express-typescript/blob/master/src/api/user/userRouter.ts"
    click OpenAPIRouter "https://github.com/edwinhern/express-typescript/blob/master/src/api-docs/openAPIRouter.ts"
    click UserController "https://github.com/edwinhern/express-typescript/blob/master/src/api/user/userController.ts"
    click UserService "https://github.com/edwinhern/express-typescript/blob/master/src/api/user/userService.ts"
    click UserRepository "https://github.com/edwinhern/express-typescript/blob/master/src/api/user/userRepository.ts"
    click ServiceResponse "https://github.com/edwinhern/express-typescript/blob/master/src/common/models/serviceResponse.ts"
    click CommonValidation "https://github.com/edwinhern/express-typescript/blob/master/src/common/utils/commonValidation.ts"
    click HTTPHandlers "https://github.com/edwinhern/express-typescript/blob/master/src/common/utils/httpHandlers.ts"
    click OpenAPIDocGen "https://github.com/edwinhern/express-typescript/blob/master/src/api-docs/openAPIDocumentGenerator.ts"
    click OpenAPIBuilders "https://github.com/edwinhern/express-typescript/blob/master/src/api-docs/openAPIResponseBuilders.ts"

    %% Styles
    classDef middleware fill:#FFF9C4,stroke:#FBC02D
    classDef router fill:#BBDEFB,stroke:#1976D2
    classDef controller fill:#81D4FA,stroke:#0288D1
    classDef service fill:#C8E6C9,stroke:#388E3C
    classDef repository fill:#A5D6A7,stroke:#2E7D32
    classDef external fill:#ECEFF1,stroke:#90A4AE
    classDef docs fill:#E1BEE7,stroke:#8E24AA
    classDef config fill:#CFD8DC,stroke:#455A64
    classDef server fill:#FFE0B2,stroke:#EF6C00
    classDef model fill:#FFF3E0,stroke:#FB8C00
    classDef util fill:#E0F7FA,stroke:#006064
```
