# shivomv/nodejsstartertemplate architecture

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

- Interactive diagram: https://gitdiagram.com/shivomv/nodejsstartertemplate
- Repository: https://github.com/shivomv/nodejsstartertemplate

## Overview

##### Project type and purpose
- This is a full-stack MERN (MongoDB, Express, React, Node) starter template.
- Purpose: Provide a scaffold with user authentication, audit logging, Swagger-based API docs, and a service-based backend architecture coupled with a React frontend.

##### File structure
- Top-level:
- backend/ – Express.js server
- frontend/ – React.js single-page application
- package.json, readme.md, LICENSE, .gitignore
- backend/ substructure:
- api/v1/routes – defines HTTP endpoints
- controllers – handle requests, invoke services
- services – business logic, database calls
- models – Mongoose schemas
- middlewares – auth, validation, error handling, audit
- utils – helpers (logging, JWT, email, error handler)
- config – environment, database connection
- swagger – definitions & UI setup
- frontend/ substructure:
- public & index.html – host root DOM
- src/components – reusable UI components
- src/pages – route views (Login, Dashboard, Admin, etc.)
- src/context/hooks – state & side-effect management
- src/lib – API client (Axios/queryClient), shared types, utils

##### README for additional insights
- Architecture: service-based backend, separation of concerns (controllers/services/validators)
- Tech stack: Node.js/Express, MongoDB/Mongoose, React/Context API/React Router, Axios
- Features: JWT auth (HTTP-only cookies), role-based access, password reset via email, Swagger docs, structured audit logs

##### Essential elements to capture
- High-level separation: Frontend vs Backend
- Internal backend layering: Routes, Middleware, Controllers, Services, Models
- External dependencies: MongoDB, SMTP, Swagger UI
- Authentication flow (JWT issuance, HTTP-only cookies)
- Audit logging path
- API documentation endpoint

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Block
    subgraph "Frontend (React SPA)" 
        direction TB
        User["User"]:::external
        ReactApp["React App"]:::frontend
        APIClient["Axios/React Query Client"]:::frontend
        Pages["Pages (Route Views)"]:::frontend
        Components["UI Components"]:::frontend
        Context["Context & Hooks"]:::frontend
        ReactApp --> APIClient
        ReactApp --> Pages
        ReactApp --> Components
        ReactApp --> Context
        User --> ReactApp
    end

    %% Frontend File Nodes for click events
    subgraph "Frontend Files"
        direction TB
        HTML["index.html"]:::frontend
        MainJS["main.jsx"]:::frontend
        AppJS["App.jsx"]:::frontend
        LoginPage["Login.jsx"]:::frontend
        DashboardPage["Dashboard.jsx"]:::frontend
        ButtonComp["button.jsx"]:::frontend
        AuthContext["AuthContext.jsx"]:::frontend
        QueryClientTS["queryClient.ts"]:::frontend
    end

    ReactApp --> HTML
    ReactApp --> MainJS
    ReactApp --> AppJS
    Pages --> LoginPage
    Pages --> DashboardPage
    Components --> ButtonComp
    Context --> AuthContext
    APIClient --> QueryClientTS

    click HTML "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/index.html"
    click MainJS "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/main.jsx"
    click AppJS "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/App.jsx"
    click LoginPage "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/pages/Login.jsx"
    click DashboardPage "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/pages/Dashboard.jsx"
    click ButtonComp "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/components/ui/button.jsx"
    click AuthContext "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/context/AuthContext.jsx"
    click QueryClientTS "https://github.com/shivomv/nodejsstartertemplate/blob/main/frontend/src/lib/queryClient.ts"

    %% Backend Block
    subgraph "Backend (Express/Node)" 
        direction TB
        APILayer["API Layer (Routes & Swagger)"]:::backend
        MiddlewareLayer["Middleware Layer"]:::backend
        ControllerLayer["Controller Layer"]:::backend
        ServiceLayer["Service Layer"]:::backend
        ModelLayer["Data Access Layer (Mongoose Models)"]:::backend
        UtilsLayer["Utils & Logging"]:::backend
        ConfigLayer["Configuration"]:::backend

        APILayer --> MiddlewareLayer
        MiddlewareLayer --> ControllerLayer
        ControllerLayer --> ServiceLayer
        ServiceLayer --> ModelLayer
        ModelLayer --> MongoDB
        MiddlewareLayer --> UtilsLayer
        ServiceLayer --> UtilsLayer
        ConfigLayer --> APILayer
        ConfigLayer --> ServiceLayer
    end

    %% Backend Entry Points
    ServerJS["server.js"]:::backend
    AppJSBackend["app.js"]:::backend
    ServerJS --> APILayer
    ServerJS --> ConfigLayer
    AppJSBackend --> APILayer

    click ServerJS "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/server.js"
    click AppJSBackend "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/app.js"

    %% API Layer Files
    subgraph "Routes & Swagger"
        direction TB
        IndexRoutes["index.js (routes)"]:::backend
        UserRoutes["userRoutes.js"]:::backend
        SwaggerUI["swagger/index.js"]:::backend
    end
    APILayer --> IndexRoutes
    APILayer --> UserRoutes
    APILayer --> SwaggerUI

    click IndexRoutes "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/api/v1/routes/index.js"
    click UserRoutes "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/api/v1/routes/userRoutes.js"
    click SwaggerUI "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/swagger/index.js"

    %% Middleware Nodes
    subgraph "Middlewares"
        direction TB
        AuthMW["auth.js"]:::backend
        ValidatorMW["validator.js"]:::backend
        AuditMW["auditMiddleware.js"]:::backend
        ErrorMW["error.js"]:::backend
    end
    MiddlewareLayer --> AuthMW
    MiddlewareLayer --> ValidatorMW
    MiddlewareLayer --> AuditMW
    MiddlewareLayer --> ErrorMW

    click AuthMW "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/middlewares/auth.js"
    click ValidatorMW "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/middlewares/validator.js"
    click AuditMW "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/middlewares/auditMiddleware.js"
    click ErrorMW "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/middlewares/error.js"

    %% Controller Nodes
    subgraph "Controllers"
        direction TB
        UserController["userController.js"]:::backend
    end
    ControllerLayer --> UserController

    click UserController "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/controllers/userController.js"

    %% Service Nodes
    subgraph "Services"
        direction TB
        UserService["userService.js"]:::backend
    end
    ServiceLayer --> UserService

    click UserService "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/services/userService.js"

    %% Model Nodes
    subgraph "Models"
        direction TB
        UserModel["userModel.js"]:::backend
    end
    ModelLayer --> UserModel

    click UserModel "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/models/userModel.js"

    %% Utils & Logging
    subgraph "Utilities & Logging"
        direction TB
        ErrorHandler["ErrorHandler.js"]:::backend
        JWTUtil["jwtToken.js"]:::backend
        SendEmail["sendEmail.js"]:::backend
        LoggerUtil["logger.js"]:::backend
        AuditLogger["auditLogger.js"]:::backend
    end
    UtilsLayer --> ErrorHandler
    UtilsLayer --> JWTUtil
    UtilsLayer --> SendEmail
    UtilsLayer --> LoggerUtil
    UtilsLayer --> AuditLogger

    click ErrorHandler "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/utils/ErrorHandler.js"
    click JWTUtil "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/utils/jwtToken.js"
    click SendEmail "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/utils/sendEmail.js"
    click LoggerUtil "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/utils/logger.js"
    click AuditLogger "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/utils/auditLogger.js"

    %% Configuration
    click ConfigEnv "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/config/config.env.sample"
    click DBConfig "https://github.com/shivomv/nodejsstartertemplate/blob/main/backend/config/database.js"
    ConfigLayer --> ConfigEnv
    ConfigLayer --> DBConfig

    %% External Services
    MongoDB["MongoDB"]:::db
    SMTP["Email Service (SMTP)"]:::external
    MongoDB -- "reads/writes" --> ModelLayer
    UserService -.->|"password reset"| SMTP

    %% Swagger UI Doc Endpoint
    SwaggerDocs["Swagger UI"]:::external
    APILayer -->|"docs endpoint"| SwaggerDocs

    %% Audit logs path
    AuditMW -->|"writes logs"| LoggerUtil

    %% Classes
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20;
    classDef db fill:#FFF3E0,stroke:#E65100,color:#E65100;
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64;
```
