# jawherkl/node-api-postgres architecture

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

- Interactive diagram: https://gitdiagram.com/jawherkl/node-api-postgres
- Repository: https://github.com/jawherkl/node-api-postgres

## Overview

##### Project Type and Purpose
- This is a **standalone backend service**: a modern RESTful API built with Node.js/Express that manages user data and metrics in a PostgreSQL database.
- It offers authentication (JWT), role-based access control, soft-deletion, password-reset via email (SendGrid), metrics instrumentation (Prometheus), Swagger docs, and unit tests.

##### File Structure and Architectural Layers
- **Entry Point**: index.js – initializes Express app, loads middleware, routes, Swagger, metrics.
- **Configuration Layer** (`config/`): DB connection (config/db.js), Swagger setup (config/swagger.js + swagger.json), environment.
- **Routing Layer** (`routes/`): loginRoutes, userRoutes, metricsRoutes – define API endpoints and attach controllers.
- **Controller Layer** (`controllers/`): Implements request handlers (authController, userController, metricsController).
- **Business Logic & Services** (`middleware/`, `utils/`):
- middleware/auth.js & authorize.js – JWT validation, RBAC.
- middleware/upload.js – file upload handling.
- middleware/errorHandler.js – centralized error formatting.
- utils/mailer.js – email service (SendGrid).
- utils/logger.js – logging.
- **Data Access Layer** (`models/`): ORM/DB-client models for Users and Metrics.
- **External Integrations**:
- PostgreSQL database (configurable via docker-compose or .env).
- SendGrid (mailer utility).
- Prometheus (prometheus.yml) exposing `/metrics` endpoint.
- **Supporting Files**:
- Swagger UI served at `/api-docs`.
- Static HTML (public/reset-password.html).
- File storage directory (`uploads/`).
- Docker artifacts (Dockerfile, docker-compose.yml).

##### Architectural Patterns & Design Principles
- **Layered / MVC-style** separation: Routes → Controllers → Models.
- **Middleware pipeline** for cross-cutting concerns (auth, error handling, file uploads).
- **Modularization**: config, routes, controllers, models, utils all decoupled.
- **Infrastructure as Code**: Docker + docker-compose for reproducible environment.
- **Observability**: logs (utils/logger) + metrics (Prometheus).
- **Documentation**: self-documenting API via Swagger.

##### Essential Elements
- Clear **component names**: API Gateway (Express), Auth Service (JWT/Middleware), User Service (Controllers + Models), Metrics Service.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Clients (Web/Mobile/CLI)"]:::client

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        index["index.js\n(Express App Init)"]:::server
        click index "https://github.com/jawherkl/node-api-postgres/blob/main/index.js"

        %% Configuration Layer
        subgraph "Configuration Layer" 
            direction TB
            dbConfig["config/db.js"]:::config
            click dbConfig "https://github.com/jawherkl/node-api-postgres/blob/main/config/db.js"
            swaggerSetup["config/swagger.js"]:::config
            click swaggerSetup "https://github.com/jawherkl/node-api-postgres/blob/main/config/swagger.js"
            swaggerSpec["config/swagger.json"]:::config
            click swaggerSpec "https://github.com/jawherkl/node-api-postgres/blob/main/config/swagger.json"
        end

        %% Routing Layer
        subgraph "Routing Layer" 
            direction TB
            loginRoutes["routes/loginRoutes.js"]:::routes
            click loginRoutes "https://github.com/jawherkl/node-api-postgres/blob/main/routes/loginRoutes.js"
            userRoutes["routes/userRoutes.js"]:::routes
            click userRoutes "https://github.com/jawherkl/node-api-postgres/blob/main/routes/userRoutes.js"
            metricsRoutes["routes/metricsRoutes.js"]:::routes
            click metricsRoutes "https://github.com/jawherkl/node-api-postgres/blob/main/routes/metricsRoutes.js"
        end

        %% Controller Layer
        subgraph "Controller Layer"
            direction TB
            authController["controllers/authController.js"]:::controller
            click authController "https://github.com/jawherkl/node-api-postgres/blob/main/controllers/authController.js"
            userController["controllers/userController.js"]:::controller
            click userController "https://github.com/jawherkl/node-api-postgres/blob/main/controllers/userController.js"
            metricsController["controllers/metricsController.js"]:::controller
            click metricsController "https://github.com/jawherkl/node-api-postgres/blob/main/controllers/metricsController.js"
        end

        %% Middleware Pipeline
        subgraph "Middleware Pipeline"
            direction TB
            jwtAuth["middleware/auth.js"]:::middleware
            click jwtAuth "https://github.com/jawherkl/node-api-postgres/blob/main/middleware/auth.js"
            rbacAuth["middleware/authorize.js"]:::middleware
            click rbacAuth "https://github.com/jawherkl/node-api-postgres/blob/main/middleware/authorize.js"
            upload["middleware/upload.js"]:::middleware
            click upload "https://github.com/jawherkl/node-api-postgres/blob/main/middleware/upload.js"
            errorHandler["middleware/errorHandler.js"]:::middleware
            click errorHandler "https://github.com/jawherkl/node-api-postgres/blob/main/middleware/errorHandler.js"
        end

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            userModel["models/user.js"]:::model
            click userModel "https://github.com/jawherkl/node-api-postgres/blob/main/models/user.js"
            metricsModel["models/metrics.js"]:::model
            click metricsModel "https://github.com/jawherkl/node-api-postgres/blob/main/models/metrics.js"
        end

        %% Utility Services
        subgraph "Utility Services"
            direction TB
            mailer["utils/mailer.js"]:::util
            click mailer "https://github.com/jawherkl/node-api-postgres/blob/main/utils/mailer.js"
            logger["utils/logger.js"]:::util
            click logger "https://github.com/jawherkl/node-api-postgres/blob/main/utils/logger.js"
        end

        %% Static Assets & Storage
        subgraph "Static & Storage"
            direction TB
            resetPage["public/reset-password.html"]:::static
            click resetPage "https://github.com/jawherkl/node-api-postgres/blob/main/public/reset-password.html"
            uploadsDir["uploads/"]:::infra
            click uploadsDir "https://github.com/jawherkl/node-api-postgres/tree/main/uploads/"
        end

        %% Exposed Swagger UI
        swaggerUI["Swagger UI\n(/api-docs)"]:::server
    end

    %% External Services & Infrastructure
    postgres[(PostgreSQL Database 5432)]:::external
    sendgrid[(SendGrid Email Service)]:::external
    prometheus[(Prometheus)]:::external
    dockerfile["Dockerfile"]:::infra
    click dockerfile "https://github.com/jawherkl/node-api-postgres/tree/main/Dockerfile"
    compose["docker-compose.yml"]:::infra
    click compose "https://github.com/jawherkl/node-api-postgres/blob/main/docker-compose.yml"
    promConfig["prometheus.yml"]:::infra
    click promConfig "https://github.com/jawherkl/node-api-postgres/blob/main/prometheus.yml"

    %% Connections
    Clients -->|"HTTP|JSON"| index
    index -->|"load"| dbConfig
    index -->|"load"| swaggerSetup
    swaggerSetup -->|"uses"| swaggerSpec
    index -->|"mount"| loginRoutes
    index -->|"mount"| userRoutes
    index -->|"mount"| metricsRoutes
    loginRoutes -->|"calls"| authController
    userRoutes -->|"calls"| userController
    metricsRoutes -->|"calls"| metricsController
    index -->|"use"| jwtAuth
    index -->|"use"| rbacAuth
    index -->|"use"| upload
    index -->|"use"| errorHandler
    authController -->|"DB ops"| userModel
    userController -->|"DB ops"| userModel
    metricsController -->|"DB ops"| metricsModel
    authController -->|"send email"| mailer
    metricsController -->|"log metrics"| logger
    metricsController -->|"expose /metrics"| prometheus
    index -->|"serve UI"| swaggerUI
    index -->|"serve file"| resetPage
    index -->|"write/read"| uploadsDir
    userModel -->|"SQL"| postgres
    metricsModel -->|"SQL"| postgres
    index -->|"HTTP"| postgres
    index -->|"SMTP/HTTP"| sendgrid
    prometheus -->|"scrape /metrics"| index

    %% Styles
    classDef client fill:#f9f,stroke:#333
    classDef server fill:#bbf,stroke:#333
    classDef config fill:#dfd,stroke:#333
    classDef routes fill:#ffd,stroke:#333
    classDef controller fill:#fdc,stroke:#333
    classDef middleware fill:#ffc,stroke:#333
    classDef model fill:#cdf,stroke:#333
    classDef util fill:#ddf,stroke:#333
    classDef static fill:#fcf,stroke:#333
    classDef external fill:#bfb,stroke:#333
    classDef infra fill:#fbf,stroke:#333
```
