# burakorkmez/mern-advanced-auth architecture

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

- Interactive diagram: https://gitdiagram.com/burakorkmez/mern-advanced-auth
- Repository: https://github.com/burakorkmez/mern-advanced-auth

## Overview

##### Project Type and Purpose
- This is a full-stack authentication tutorial application.
- Frontend: React SPA (Vite + Tailwind CSS) implementing signup, login, email verification, forgot/reset password, and a protected dashboard UI.
- Backend: Node.js + Express REST API with MongoDB (via Mongoose) for user data, JWT for authentication, and Mailtrap for email delivery.

##### High-Level File Structure Analysis
- Top-level “frontend” directory:
- Vite config, PostCSS/Tailwind config, ESLint.
- `src/` contains React components, pages, global styles, and a lightweight store for auth state.
- `public/` holds static assets (HTML shell, screenshot for README).
- Top-level “backend” directory:
- `controllers/`: business logic for auth endpoints.
- `routes/`: Express routes wiring controllers.
- `models/`: Mongoose schema for User.
- `middleware/`: JWT verification.
- `db/`: MongoDB connection setup.
- `mailtrap/`: email templates and Mailtrap configuration.
- `utils/`: token generation and cookie-setting helper.
- `index.js`: Express app bootstrap and route mounting.

##### Core Architectural Components
a. Frontend SPA
- React components and pages (Login, Signup, Dashboard, etc.)
- AuthStore: client-side state management for user session
- HTTP client (fetch or Axios) calls to backend endpoints
b. Backend API
- Express server handling REST endpoints: signup, login, verify email, forgot/reset password, checkAuth, logout
- JWT middleware enforces route protection
- Controllers coordinate DB operations and email triggers
c. Database
- MongoDB (hosted externally or locally via MONGO_URI)
- Mongoose for ODM mapping and schema validation
d. Email Service
- Mailtrap API for sending verification, reset, and welcome emails via configured templates

##### Relationships and Data Flows
1. Browser (React SPA) → HTTP POST /signup → Express → Controller → Mongoose writes User → generate JWT → set HTTP-Only cookie → send verification email via Mailtrap → respond to client
2. Browser follows email link → HTTP GET /verify-email → Express → Controller marks user as verified
3. Protected pages (e.g., Dashboard) → HTTP GET /checkAuth → JWT middleware validates token → allows access
4. Forgot/Reset flows: browser triggers POST /forgot-password → email sent; POST /reset-password → controller updates password
5. Logout: clears cookie

##### Architectural Patterns and Principles
- MVC-style layering in backend (Routes → Controllers → Models → DB)
- Stateless JWT authentication with HTTP-Only cookies for XSS protection
- Single responsibility per module (e.g., dedicated utils for token generation, dedicated mailtrap folder)
- Clear separation of concerns between frontend UI and backend API

##### Technologies & Frameworks
- Frontend: React, Vite, Tailwind CSS, PostCSS, ESLint, Zustand (or similar store)
- Backend: Node.js, Express, Mongoose (MongoDB), JSON Web Tokens, dotenv for config
- Email: Mailtrap API
- Deployment: `npm run build` (frontend Vite build), `npm run start` (backend server)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend SPA (React/Vite)" 
        style FrontendLayer fill:#D0E8FF,stroke:#0288D1,stroke-width:2px
        FE_ViteConfig["vite.config.js"] 
        FE_TailwindConfig["tailwind.config.js"] 
        FE_ESLint[".eslintrc.cjs"]
        subgraph "src/"
            style FE_Src fill:#E3F2FD,stroke:#0288D1
            FE_Main["main.jsx"]
            FE_App["App.jsx"]
            subgraph "pages/"
                style FE_Pages fill:#E3F2FD,stroke:#0288D1
                FE_Login["LoginPage.jsx"]
                FE_Signup["SignUpPage.jsx"]
                FE_Dashboard["DashboardPage.jsx"]
                FE_EmailVerif["EmailVerificationPage.jsx"]
                FE_Forgot["ForgotPasswordPage.jsx"]
                FE_Reset["ResetPasswordPage.jsx"]
            end
            subgraph "components/"
                style FE_Comp fill:#E3F2FD,stroke:#0288D1
                FE_Input["Input.jsx"]
                FE_Loading["LoadingSpinner.jsx"]
                FE_PasswordMeter["PasswordStrengthMeter.jsx"]
                FE_FloatingShape["FloatingShape.jsx"]
            end
            FE_Styles["index.css"]
            FE_Store["authStore.js"]
            FE_Utils["date.js"]
        end
        FE_Public["public/"]
    end

    %% Backend Layer
    subgraph "Backend API (Node.js/Express)" 
        style BE_Layer fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px
        BE_Index["index.js"]
        BE_DBConnect["connectDB.js"]
        subgraph "models/"
            style BE_Models fill:#E8F5E9,stroke:#2E7D32
            BE_UserModel["user.model.js"]
        end
        subgraph "controllers/"
            style BE_Controllers fill:#E8F5E9,stroke:#2E7D32
            BE_AuthController["auth.controller.js"]
        end
        subgraph "routes/"
            style BE_Routes fill:#E8F5E9,stroke:#2E7D32
            BE_AuthRoute["auth.route.js"]
        end
        subgraph "middleware/"
            style BE_Middleware fill:#E8F5E9,stroke:#2E7D32
            BE_VerifyToken["verifyToken.js"]
        end
        subgraph "utils/"
            style BE_UtilsBS fill:#E8F5E9,stroke:#2E7D32
            BE_GenToken["generateTokenAndSetCookie.js"]
        end
        subgraph "mailtrap/"
            style BE_Mailtrap fill:#E8F5E9,stroke:#2E7D32
            BE_MailConfig["mailtrap.config.js"]
            BE_Templates["emailTemplates.js"]
            BE_Emails["emails.js"]
        end
        BE_EnvNotes["Env: MONGO_URI, JWT_SECRET, MAILTRAP_TOKEN"]
    end

    %% External Services
    MongoDB[(MongoDB)]:::database
    Mailtrap[(Mailtrap API)]:::email

    %% Data Flows
    FE_Main -->|"HTTP POST /signup,/login,/forgot-password,/reset-password"| BE_AuthRoute
    FE_Main -->|"HTTP GET /verify-email,/checkAuth"| BE_AuthRoute
    BE_AuthRoute -->|routes to| BE_AuthController
    BE_AuthController -->|uses| BE_UserModel
    BE_AuthController -->|calls| BE_GenToken
    BE_GenToken -->|sets cookie| BE_AuthController
    BE_AuthController -->|sends email via| BE_Emails
    BE_Emails -->|uses templates & config| BE_Templates
    BE_Emails -->|uses| BE_MailConfig
    BE_AuthController -->|"DB query"| MongoDB
    BE_DBConnect -->|connects| MongoDB
    BE_VerifyToken -->|verifies JWT| BE_AuthRoute
    BE_AuthController -->|responds with JSON + HTTP-Only Cookie| FE_Main
    BE_Emails -->|SMTP/HTTP| Mailtrap

    %% Click Events Frontend
    click FE_ViteConfig "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/vite.config.js"
    click FE_TailwindConfig "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/tailwind.config.js"
    click FE_ESLint "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/.eslintrc.cjs"
    click FE_Main "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/main.jsx"
    click FE_App "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/App.jsx"
    click FE_Login "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/LoginPage.jsx"
    click FE_Signup "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/SignUpPage.jsx"
    click FE_Dashboard "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/DashboardPage.jsx"
    click FE_EmailVerif "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/EmailVerificationPage.jsx"
    click FE_Forgot "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/ForgotPasswordPage.jsx"
    click FE_Reset "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/pages/ResetPasswordPage.jsx"
    click FE_Input "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/components/Input.jsx"
    click FE_Loading "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/components/LoadingSpinner.jsx"
    click FE_PasswordMeter "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/components/PasswordStrengthMeter.jsx"
    click FE_FloatingShape "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/components/FloatingShape.jsx"
    click FE_Styles "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/index.css"
    click FE_Store "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/store/authStore.js"
    click FE_Utils "https://github.com/burakorkmez/mern-advanced-auth/blob/master/frontend/src/utils/date.js"
    click FE_Public "https://github.com/burakorkmez/mern-advanced-auth/tree/master/frontend/public/"

    %% Click Events Backend
    click BE_Index "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/index.js"
    click BE_DBConnect "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/db/connectDB.js"
    click BE_UserModel "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/models/user.model.js"
    click BE_AuthController "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/controllers/auth.controller.js"
    click BE_AuthRoute "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/routes/auth.route.js"
    click BE_VerifyToken "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/middleware/verifyToken.js"
    click BE_GenToken "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/utils/generateTokenAndSetCookie.js"
    click BE_MailConfig "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/mailtrap/mailtrap.config.js"
    click BE_Templates "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/mailtrap/emailTemplates.js"
    click BE_Emails "https://github.com/burakorkmez/mern-advanced-auth/blob/master/backend/mailtrap/emails.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0288D1
    classDef backend fill:#E8F5E9,stroke:#2E7D32
    classDef database fill:#FFF3E0,stroke:#FB8C00
    classDef email fill:#F3E5F5,stroke:#8E24AA
    class FE_ViteConfig,FE_TailwindConfig,FE_ESLint,FE_Main,FE_App,FE_Login,FE_Signup,FE_Dashboard,FE_EmailVerif,FE_Forgot,FE_Reset,FE_Input,FE_Loading,FE_PasswordMeter,FE_FloatingShape,FE_Styles,FE_Store,FE_Utils,FE_Public frontend
    class BE_Index,BE_DBConnect,BE_UserModel,BE_AuthController,BE_AuthRoute,BE_VerifyToken,BE_GenToken,BE_MailConfig,BE_Templates,BE_Emails,BE_EnvNotes backend
```
