# fadi960/express-backend-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/fadi960/express-backend-boilerplate
- Repository: https://github.com/fadi960/express-backend-boilerplate

## Overview

##### Project Type and Purpose
- This is a standalone, production-ready backend API service (not a full front-to-back web app).
- It exposes REST endpoints for user management (CRUD), backed by PostgreSQL via Prisma ORM.
- Core concerns: request validation (Joi), security (Helmet, CORS, bcrypt, JWT), logging (Morgan), error handling, database migrations & seeding.

##### File Structure
Top-level:
- prisma/ – database schema (schema.prisma), migrations, seed script
- src/ – main application code
- package.json, .env template, README.md

Under src/:
- config/ – environment loading (dotenv) & PrismaClient initialization
- routes/ – Express routers (user.route.js)
- controllers/ – HTTP handlers that parse req, call services, send responses
- services/ – business logic (user.service.js)
- middlewares/ – request validation, 404, global error handling
- validations/ – Joi schemas (user.validation.js)
- utils/ – ApiError class, standard JSON response formatter
- app.js – assemble Express app: middlewares, routes, error handlers
- server.js – launch HTTP listener

##### Key Insights from README
- Layered architecture: controllers → services → Prisma ORM → PostgreSQL
- Uses UUIDs for primary keys, bcrypt for password hashing, JWT for auth
- Optional Knex migrations & seeders alongside Prisma tools
- Emphasis on environment config, security headers, CORS, logging, consistent JSON responses

##### Main Components
1. Client(s): Browser, mobile app, Postman – issues HTTP requests to the API.
2. HTTP Server Layer:
- server.js (Node.js process)
- app.js (Express instance)
3. Middleware Layer:
- CORS, Helmet, Morgan, bodyParser
- validate (Joi wrapper)
- notFound (404)
- errorHandler (global catcher)
4. Routing & Controller Layer:
- user.route.js → user.controller.js
5. Service Layer:
- user.service.js (business rules, calling ORM)
6. ORM / Data Access Layer:
- PrismaClient (config/database.js) interacting with schema.prisma
- Optional Knex migrations/seeders
7. Persistence:
8. Auxiliary Tools:
- dotenv (env loader)
- Prisma migrate & seed scripts (prisma/seed.js)
- Knex CLI (optional)

##### Relationships & Data Flows
- request → security/logging middlewares → validation middleware → route handler
- route handler → controller → service
- service → PrismaClient → PostgreSQL
- DB response back up the chain → controller → responseHandler → client
- Errors propagate to errorHandler middleware → formatted JSON error

##### Architectural Patterns & Technologies
- Layered (aka “services” or “hexagonal”) architecture separating transport, validation, business logic, data access.
- Use of ORM (Prisma) for data mapping; optional micro-migration subsystem via Knex.
- JWT-based auth (via jsonwebtoken) and bcrypt password hashing.
- Centralized error & response handling for uniform API contract.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client (Browser/Postman/Mobile)"]:::client

    %% HTTP Layer
    subgraph "HTTP Layer"
        server["server.js – HTTP Server Entry Point"]:::http
        app["app.js – Express App"]:::http
    end

    %% Config & Utils
    subgraph "Config & Utilities"
        env["index.js – Env Loader"]:::utils
        apiError["ApiError.js – API Error Utility"]:::utils
        response["responseHandler.js – JSON Response Formatter"]:::utils
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        cors["CORS, Helmet, Morgan"]:::middleware
        validate["validate.js – Request Validation"]:::middleware
        notFound["notFound.js – 404 Handler"]:::middleware
        errorHandler["errorHandlers.js – Global Error Handler"]:::middleware
    end

    %% Routing & Controller Layer
    subgraph "Routing & Controller Layer"
        routes["user.route.js – Router"]:::controller
        controller["user.controller.js – Controller"]:::controller
    end

    %% Validation Schemas
    subgraph "Validation Schemas"
        validation["user.validation.js – Joi Schemas"]:::validation
    end

    %% Service Layer
    subgraph "Service Layer"
        service["user.service.js – Business Logic"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        dbClient["database.js – PrismaClient"]:::dataAccess
        schema["schema.prisma"]:::dataAccess
        migrations["migrations (Knex/Prisma)"]:::dataAccess
        seedScript["seed.js – Prisma Seed Script"]:::dataAccess
    end

    %% Database
    db["PostgreSQL Database"]:::db

    %% Client to Server Flow
    Client -->|"HTTP Request"| server
    server --> app

    %% Config Initialization
    app --> env
    env --> dbClient

    %% Middleware Chain
    app --> cors
    cors --> validate
    validate --> routes
    routes --> controller
    controller --> service
    service --> dbClient
    dbClient --> db

    %% Response Flow
    db --> dbClient
    dbClient --> service
    service --> controller
    controller --> response
    response --> client

    %% Error Flow
    controller -->|Errors| errorHandler
    service -->|Errors| errorHandler
    errorHandler --> response

    %% Optional Knex Migrations/Seeders (dashed)
    migrations -.-> dbClient
    seedScript -.-> dbClient

    %% Utility Usage
    controller --> apiError
    controller --> response

    %% Validation Usage
    routes --> validation

    %% Click Events
    click server "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/server.js"
    click app "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/app.js"
    click env "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/config/index.js"
    click dbClient "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/config/database.js"
    click validate "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/middlewares/validate.js"
    click notFound "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/middlewares/notFound.js"
    click errorHandler "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/middlewares/errorHandlers.js"
    click routes "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/routes/user.route.js"
    click controller "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/controllers/user.controller.js"
    click service "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/services/user.service.js"
    click validation "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/validations/user.validation.js"
    click apiError "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/utils/ApiError.js"
    click response "https://github.com/fadi960/express-backend-boilerplate/blob/main/src/utils/responseHandler.js"
    click schema "https://github.com/fadi960/express-backend-boilerplate/blob/main/prisma/schema.prisma"
    click migrations "https://github.com/fadi960/express-backend-boilerplate/tree/main/prisma/migrations"
    click seedScript "https://github.com/fadi960/express-backend-boilerplate/blob/main/prisma/seed.js"

    %% Styles
    classDef client fill:#a3be8c,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef http fill:#88c0d0,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef utils fill:#d8dee9,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef middleware fill:#b48ead,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef controller fill:#8fbcbb,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef validation fill:#ebcb8b,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef service fill:#a3be8c,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef dataAccess fill:#b48ead,stroke:#2e3440,color:#2e3440,stroke-width:1px
    classDef db fill:#d08770,stroke:#2e3440,color:#2e3440,stroke-width:1px
```
