# nicolasm-83200/next-amazona-v2 architecture

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

- Interactive diagram: https://gitdiagram.com/nicolasm-83200/next-amazona-v2
- Repository: https://github.com/nicolasm-83200/next-amazona-v2

## Overview

##### Project Type and Purpose
- This is a full-stack e-commerce web application built with Next.js (using the new “app” directory), TypeScript, Tailwind CSS, and MongoDB via Mongoose.
- It provides both a customer-facing storefront (“app/(front)”) and an admin dashboard (“app/admin”), with authentication (NextAuth), order management, product management, and payment integrations (PayPal / Cloudinary).

##### High-Level Architecture Components
a. Client (Browser)
- React components served by Next.js, including customer pages (product listing, cart, checkout, profile) and admin pages (dashboard, orders, products, users).
b. Next.js Server
- Renders pages (Server Components / Client Components)
- Hosts API routes under app/api/… (e.g., /api/products, /api/orders, /api/auth, /api/admin/…)
- Applies middleware (middleware.ts) for auth checks or rewrites
c. Business Logic Layer
- lib/services/*.ts encapsulate domain operations (e.g., productService)
- lib/hooks provide client state management (e.g., useCartStore)
- NextAuth configuration (app/api/auth/[...nextauth])
d. Data Layer
- Mongoose models in lib/models (UserModel, ProductModel, OrderModel)
- dbConnect utility to establish MongoDB connection
e. External Services
- MongoDB Atlas (or self-hosted)
- PayPal REST API for payments (lib/paypal.ts, /api/orders/[id]/capture-paypal-order)
- Cloudinary for image uploads (app/api/cloudinary-sign)
f. Deployment Platform
- Vercel (leveraging next.config.mjs), environment variables

##### Relationships & Data Flow
1. User → Next.js Frontend
- Navigation triggers React components (pages under app/(front) or app/admin).
- Components call API via fetch or client hooks (e.g., /api/products).
2. Next.js API Routes → Business Logic
- API route handlers call service functions (lib/services)
- Services use Mongoose models and dbConnect to query/update MongoDB
3. Payment Flow
- Frontend requests PayPal order creation (/api/orders/[id]/create-paypal-order)
- PayPal SDK returns approval URL, user approves → capture route
4. Media Upload
- Frontend requests Cloudinary signature → uploads directly to Cloudinary
5. Auth Flow
- NextAuth “/api/auth/[...nextauth]” protects pages via middleware
- Profile API (/api/auth/profile) reads/writes user data

##### Architectural Patterns & Design Principles
- File-system routing (Next.js “app” directory) separates concerns by URL path.
- Server Components vs Client Components: use “use client” only where needed (e.g., CartDetails).
- Layered architecture: API routes → Services → Models → Database.
- Context / Global Providers: components/ClientProviders.tsx wraps React context (NextAuthProvider, Zustand store).
- Environment-agnostic config (next.config.mjs, tailwind.config.ts, tsconfig.json).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser/Application Entry
    Browser["Client Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        CustomerFrontend["Customer Frontend<br/>app/(front)"]:::frontend
        AdminFrontend["Admin Frontend<br/>app/admin"]:::frontend
        ClientProviders["Client Providers<br/>components/ClientProviders.tsx"]:::frontend
        Providers["Global Providers<br/>components/Providers.tsx"]:::frontend
        AdminLayout["Admin Layout<br/>components/admin/AdminLayout.tsx"]:::frontend
        Menu["Menu Component<br/>components/header/Menu.tsx"]:::frontend
        SearchBox["SearchBox Component<br/>components/header/SearchBox.tsx"]:::frontend
        Footer["Footer Component<br/>components/footer/Footer.tsx"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js API Routes)" 
        direction TB
        Middleware["Middleware Interceptor<br/>middleware.ts"]:::backend
        ProductsAPI["Products API<br/>app/api/products"]:::backend
        OrdersAPI["Orders API<br/>app/api/orders"]:::backend
        AuthAPI["Auth API<br/>app/api/auth"]:::backend
        AdminAPI["Admin API<br/>app/api/admin"]:::backend
        CloudinaryAPI["Cloudinary Signature API<br/>app/api/cloudinary-sign/route.ts"]:::backend
        NextAuthRoute["NextAuth Route<br/>app/api/auth/[...nextauth]/route.ts"]:::backend
    end

    %% Business Logic Services
    subgraph "Services & Hooks" 
        direction TB
        ProductService["Product Service<br/>lib/services/productService.ts"]:::backend
        CartStore["useCartStore Hook<br/>lib/hooks/useCartStore.ts"]:::backend
        LayoutHook["useLayout Hook<br/>lib/hooks/useLayout.ts"]:::backend
        NextAuthConfig["NextAuth Config<br/>lib/auth.ts"]:::backend
        PayPalInt["PayPal Integration<br/>lib/paypal.ts"]:::ext
    end

    %% Data Layer
    subgraph "Data Models & DB" 
        direction TB
        UserModel["User Model<br/>lib/models/UserModel.ts"]:::db
        ProductModel["Product Model<br/>lib/models/ProductModel.ts"]:::db
        OrderModel["Order Model<br/>lib/models/OrderModel.ts"]:::db
        DBConnect["DB Connect Utility<br/>lib/dbConnect.ts"]:::db
        MongoDB["MongoDB<br/>(Atlas)"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        PayPal["PayPal REST API"]:::ext
        Cloudinary["Cloudinary Storage"]:::ext
        Vercel["Vercel Deployment"]:::ext
    end

    %% Legend
    subgraph "Legend"
        direction LR
        F[FrontEnd]:::frontend
        B[BackEnd/API]:::backend
        D[(Database)]:::db
        E((External)):::ext
    end

    %% Connections
    Browser --> CustomerFrontend
    Browser --> AdminFrontend

    CustomerFrontend -->|fetch /api/products| ProductsAPI
    CustomerFrontend -->|fetch /api/orders| OrdersAPI
    CustomerFrontend -->|fetch /api/auth/profile| AuthAPI
    CustomerFrontend -->|upload signature| CloudinaryAPI
    AdminFrontend -->|fetch /api/admin/...| AdminAPI

    ProductsAPI --> Middleware
    OrdersAPI --> Middleware
    AuthAPI --> Middleware
    AdminAPI --> Middleware
    NextAuthRoute --> Middleware

    ProductsAPI --> ProductService
    OrdersAPI --> ProductService
    AuthAPI --> NextAuthConfig
    AdminAPI --> ProductService

    ProductService --> DBConnect
    DBConnect --> MongoDB
    ProductService --> UserModel
    ProductService --> ProductModel
    ProductService --> OrderModel

    OrdersAPI --> PayPalInt
    PayPalInt --> PayPal
    CloudinaryAPI --> Cloudinary

    CustomerFrontend --> CartStore
    CustomerFrontend --> LayoutHook

    CustomerFrontend --> ClientProviders
    ClientProviders --> Providers
    AdminFrontend --> AdminLayout
    AdminFrontend --> Menu
    AdminFrontend --> SearchBox
    AdminFrontend --> Footer

    Vercel --- NextAuthConfig
    Vercel --- DBConnect

    %% Click Events
    click CustomerFrontend "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/(front)"
    click AdminFrontend "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/admin"
    click ProductsAPI "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/api/products"
    click OrdersAPI "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/api/orders"
    click AuthAPI "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/api/auth"
    click AdminAPI "https://github.com/nicolasm-83200/next-amazona-v2/tree/master/app/api/admin"
    click CloudinaryAPI "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/app/api/cloudinary-sign/route.ts"
    click Middleware "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/middleware.ts"
    click NextAuthRoute "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/app/api/auth/[...nextauth]/route.ts"
    click NextAuthConfig "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/auth.ts"
    click DBConnect "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/dbConnect.ts"
    click UserModel "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/models/UserModel.ts"
    click ProductModel "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/models/ProductModel.ts"
    click OrderModel "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/models/OrderModel.ts"
    click ProductService "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/services/productService.ts"
    click CartStore "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/hooks/useCartStore.ts"
    click LayoutHook "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/hooks/useLayout.ts"
    click PayPalInt "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/lib/paypal.ts"
    click ClientProviders "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/ClientProviders.tsx"
    click Providers "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/Providers.tsx"
    click AdminLayout "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/admin/AdminLayout.tsx"
    click Menu "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/header/Menu.tsx"
    click SearchBox "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/header/SearchBox.tsx"
    click Footer "https://github.com/nicolasm-83200/next-amazona-v2/blob/master/components/footer/Footer.tsx"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#1f78b4,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#238636,stroke-width:1px
    classDef db fill:#fff3cd,stroke:#d69e2e,stroke-width:1px
    classDef ext fill:#e2dbe2,stroke:#6f42c1,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
