# benelferink/mern-template architecture

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

- Interactive diagram: https://gitdiagram.com/benelferink/mern-template
- Repository: https://github.com/benelferink/mern-template

## Overview

##### Project type and purpose
- This is a full-stack MERN (MongoDB, Express, React, Node) template.
- It provides a React single-page application (SPA) frontend with basic auth flows, and an Express/Node backend exposing RESTful endpoints and connecting to a MongoDB datastore.

##### File structure to locate major components
- Top-level “client” folder: React app
– public/: static HTML, manifest, robots.txt
– src/: components, hooks, contexts, assets, utils (axios wrapper), store (zustand or similar)
- Top-level “server” folder: Node.js/Express API
– src/routes: HTTP route definitions (e.g., /auth)
– src/controllers: business logic for login, register, token auth
– src/middlewares: request validation, error handling, token checking
– src/models: Mongoose models (Account)
– src/utils: Mongo connection, JWT, cryptography, validation (Joi)
- Root CI/CD configs (.github/workflows), lint/build scripts, .env examples

##### Key points from README
- MERN stack boilerplate with authentication
- Shows how to run server and client simultaneously
- Target audience: quick-start full-stack projects

##### Main components
A. Client (React SPA)
- UI Components (AuthModal, Header, OnlineIndicator…)
- State Management (contexts, custom hooks, localStorage)
- HTTP layer (axios instance)
B. API Layer (Express/Node)
- Routes (/auth endpoints)
- Controllers (register, login, login-with-token)
- Middlewares (bearer token check, error handler)
C. Database (MongoDB)
- Account collection
D. External/Infrastructure
- Environment variables (.env)
- CI/CD pipelines, hosting (optional)

##### Relationships and data flow
1) User interacts with React UI → triggers state updates or form submissions.
2) React uses axios to call Express endpoints (e.g., POST /auth/login).
3) Express middleware validates token or payload, then routes request to controller.
4) Controller uses utils/jwt and utils/crypt to verify credentials, then interacts with MongoDB via utils/mongo and Mongoose models.
5) MongoDB returns data → controller builds response (JWT token payload) → middleware/error handler as needed → Express sends JSON response.
6) React receives response, stores token in localStorage/context, updates UI state.

##### Highlighted architectural patterns and design principles
- Layered architecture (Presentation, API, Business Logic, Data Access).
- Separation of concerns: UI components vs. state/context vs. HTTP utils vs. business controllers vs. DB models.
- Use of middleware for cross-cutting concerns (auth checks, error handling).
- Stateless JWT auth pattern.
- Config/injection via environment variables.

##### Specific elements
– Callouts for key libraries (React, axios, Express, Joi, Mongoose, JWT)
– Notation of environment variables (.env) controlling DB URI, JWT_SECRET

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Browser
    User(["User"]):::external
    Browser(["Browser"]):::external
    User --> Browser
    Browser --> ReactSPA

    %% Frontend Layer
    subgraph "Frontend (React SPA)"
        ReactSPA["React SPA"]:::frontend
        AuthModal["AuthModal"]:::frontend
        Header["Header"]:::frontend
        OnlineIndicator["OnlineIndicator"]:::frontend
        AuthContext["AuthContext"]:::frontend
        useLocalStorage["useLocalStorage Hook"]:::frontend
        useMediaQuery["useMediaQuery Hook"]:::frontend
        useModalStore["Modal Store"]:::frontend
        Axios["Axios Instance"]:::frontend
    end
    Browser --> ReactSPA
    ReactSPA --> AuthModal
    ReactSPA --> Header
    ReactSPA --> OnlineIndicator
    ReactSPA --> AuthContext
    ReactSPA --> useLocalStorage
    ReactSPA --> useMediaQuery
    ReactSPA --> useModalStore
    ReactSPA --> Axios
    Axios -->|"HTTP Request"| ExpressRouter

    %% Backend Layer
    subgraph "Backend (Express API)"
        ExpressRouter["Express Router (/auth)"]:::backend
        CheckBearer["Check Bearer Token"]:::backend
        ErrorHandler["Error Handler"]:::backend
        RegisterCtrl["Register Controller"]:::backend
        LoginCtrl["Login Controller"]:::backend
        TokenLoginCtrl["Login-with-Token Controller"]:::backend
        mongoUtil["Mongo Connection"]:::backend
        jwtUtil["JWT Helpers"]:::backend
        cryptUtil["Cryptography Utils"]:::backend
        joiUtil["Joi Validation"]:::backend
        appSetup["Express App Setup"]:::backend
        AccountModel["Account Model"]:::backend
    end
    ExpressRouter --> CheckBearer
    ExpressRouter --> ErrorHandler
    CheckBearer --> RegisterCtrl
    CheckBearer --> LoginCtrl
    CheckBearer --> TokenLoginCtrl
    RegisterCtrl --> jwtUtil
    RegisterCtrl --> cryptUtil
    RegisterCtrl --> mongoUtil
    LoginCtrl --> jwtUtil
    LoginCtrl --> cryptUtil
    LoginCtrl --> mongoUtil
    TokenLoginCtrl --> jwtUtil
    TokenLoginCtrl --> mongoUtil
    mongoUtil --> AccountModel
    AccountModel --> MongoDB
    ControllersResponse["Controller Response"]:::backend
    RegisterCtrl --> ControllersResponse
    LoginCtrl --> ControllersResponse
    TokenLoginCtrl --> ControllersResponse
    ControllersResponse --> ErrorHandler
    ErrorHandler --> ExpressRouter
    ExpressRouter -->|"HTTP Response"| Axios

    %% Database
    MongoDB["MongoDB"]:::db

    %% External / Config
    EnvFrontend[".env.example (Frontend)"]:::external
    EnvBackend[".env.example (Backend)"]:::external
    CIFrontend["GitHub Actions: build-frontend.yml"]:::external
    CIBackend["GitHub Actions: build-backend.yml"]:::external

    EnvFrontend --> ReactSPA
    EnvBackend --> appSetup
    CIFrontend --> ReactSPA
    CIBackend --> appSetup

    %% Click events
    click ReactSPA "https://github.com/benelferink/mern-template/tree/main/client/src"
    click AuthModal "https://github.com/benelferink/mern-template/blob/main/client/src/components/AuthModal.tsx"
    click Header "https://github.com/benelferink/mern-template/blob/main/client/src/components/Header.tsx"
    click OnlineIndicator "https://github.com/benelferink/mern-template/blob/main/client/src/components/OnlineIndicator.tsx"
    click AuthContext "https://github.com/benelferink/mern-template/blob/main/client/src/contexts/AuthContext.tsx"
    click useLocalStorage "https://github.com/benelferink/mern-template/blob/main/client/src/hooks/useLocalStorage.ts"
    click useMediaQuery "https://github.com/benelferink/mern-template/blob/main/client/src/hooks/useMediaQuery.ts"
    click useModalStore "https://github.com/benelferink/mern-template/blob/main/client/src/store/useModalStore.ts"
    click Axios "https://github.com/benelferink/mern-template/blob/main/client/src/utils/axios.ts"
    click ExpressRouter "https://github.com/benelferink/mern-template/blob/main/server/src/routes/auth.ts"
    click RegisterCtrl "https://github.com/benelferink/mern-template/blob/main/server/src/controllers/auth/register.ts"
    click LoginCtrl "https://github.com/benelferink/mern-template/blob/main/server/src/controllers/auth/login.ts"
    click TokenLoginCtrl "https://github.com/benelferink/mern-template/blob/main/server/src/controllers/auth/login-with-token.ts"
    click CheckBearer "https://github.com/benelferink/mern-template/blob/main/server/src/middlewares/check-bearer-token.ts"
    click ErrorHandler "https://github.com/benelferink/mern-template/blob/main/server/src/middlewares/error-handler.ts"
    click AccountModel "https://github.com/benelferink/mern-template/blob/main/server/src/models/Account.ts"
    click mongoUtil "https://github.com/benelferink/mern-template/blob/main/server/src/utils/mongo.ts"
    click jwtUtil "https://github.com/benelferink/mern-template/blob/main/server/src/utils/jwt.ts"
    click cryptUtil "https://github.com/benelferink/mern-template/blob/main/server/src/utils/crypt.ts"
    click joiUtil "https://github.com/benelferink/mern-template/blob/main/server/src/utils/joi.ts"
    click appSetup "https://github.com/benelferink/mern-template/blob/main/server/src/utils/app.ts"
    click EnvFrontend "https://github.com/benelferink/mern-template/blob/main/client/.env.example"
    click EnvBackend "https://github.com/benelferink/mern-template/blob/main/server/.env.example"
    click CIFrontend "https://github.com/benelferink/mern-template/blob/main/.github/workflows/build-frontend.yml"
    click CIBackend "https://github.com/benelferink/mern-template/blob/main/.github/workflows/build-backend.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef db fill:#FFF3E0,stroke:#E65100,color:#BF360C
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#616161
```
