# amm10090/amazon-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/amm10090/amazon-frontend
- Repository: https://github.com/amm10090/amazon-frontend

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered React application built with Next.js 15 (App Router).
- It aggregates Amazon discount product data, presents it via a user-facing storefront, and provides an admin dashboard (CMS) for content and user management.
- Key features: real-time data updates (SWR), personalized favorites, secure authentication (NextAuth.js + MongoDB), performance monitoring (Sentry, Hotjar), and rich animations (Framer Motion, Three.js).

##### File structure
- Top-level “app/” directory implements both UI pages (SSR/SSG/RSC) and API routes under “app/api/…/route.ts”.
- “app/auth/” houses authentication pages and server actions.
- “app/dashboard/” contains the admin CMS and blog management interfaces.
- “components/” holds reusable UI pieces, organized by domain (ui, layout, cms, dashboard, etc.).
- “lib/” contains API clients, server utilities, service layers, and database setup.
- “store/” is the Zustand state management layer.
- Config files: next.config.js, tsconfig.json, tailwind.config.mjs, plus environment templates.
- Supporting docs in “docs/” detail API usage, caching, and component guidelines.

##### Main components and boundaries
- Browser / Client:
- Next.js pages and client components
- SWR + Axios for data fetching
- React Three Fiber / Framer Motion on the client
- Next.js Server:
- App Router handling SSR/SSG/RSC
- API route handlers (REST endpoints under app/api)
- NextAuth.js server actions for login/session
- Database:
- MongoDB via Mongoose adapter
- Collections for users, products, categories, favorites, email templates
- External Services:
- Amazon Product APIs (data ingestion)
- Email provider / R2 storage for image uploads
- Sentry (error monitoring) / Hotjar (analytics)
- Third-party auth providers (Google, Facebook, etc.)
- Admin CMS:
- Dashboard UI communicates with the same API endpoints
- Rich text editor and file uploader components

##### Relationships and data flow
- User requests a page → Next.js server renders RSC/SSR → initial HTML + JS bundle sent.
- On client hydration, SWR/ Axios calls API routes for dynamic data (products, categories, user favorites).
- API route handlers verify session (NextAuth), interact with MongoDB, return JSON.
- Client components read/write global state via Zustand and local storage for guest favorites.
- Admin dashboard issues authenticated API calls to create/edit content.
- Background data ingestion jobs (could be external or triggered via API routes) fetch Amazon deals and populate the DB.
- Monitoring & analytics events flow from client/server to Sentry/Hotjar.

##### Key architectural patterns and principles
- Separation of concerns:
- UI vs. API vs. data services
- Components organized by domain
- Server Components (RSC) vs. Client Components
- Stateless API routes for CRUD operations
- Global state management via Zustand for cross-component state
- Caching & revalidation with SWR to achieve near real-time updates
- Secure authentication flow with NextAuth middleware

##### Essential elements
- Component labels (e.g., “Next.js Server”, “SWR fetch”, “Zustand Store”).
- Notes on key libraries (e.g., Framer Motion, Three.js, HeroUI) where they live in the stack.
- Clear separation of public storefront vs. admin dashboard modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Layer
    subgraph "Client Browser" 
        direction TB
        HOME["Homepage"]:::frontend
        PROD["Product Detail Page"]:::frontend
        DEALS["Deals Listing Page"]:::frontend
        CATS["Categories Listing Page"]:::frontend
        SIGNIN["Sign-in Page"]:::frontend
        SIGNUP["Sign-up Page"]:::frontend
        ADMIN_UI["Admin Dashboard UI"]:::frontend
        API_CLIENT["Axios API Client (lib/api.ts)"]:::frontend
        HOOKS["SWR Hooks (lib/hooks.ts)"]:::frontend
        STORE["Zustand Store"]:::frontend
        ANIM["Framer Motion & React Three Fiber"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server" 
        direction TB
        SSR["App Router (UI Pages & Layouts)"]:::server
        API["API Route Handlers"]:::server
        AUTH_API["Auth API Route"]:::server
        REVAL["Revalidation Action"]:::server
        UPLOAD["Image Upload API"]:::server
        EMAIL_API["Email API Endpoints"]:::server
        NEXTAUTH["NextAuth.js"]:::server
        SERVICES["Service Layer"]:::server
        FAV["Favorites Utilities"]:::server
        MCONN["MongoDB Connection"]:::server
        MODELS["Mongoose Models"]:::server
    end

    %% Database Layer
    subgraph "Database"
        DB[(MongoDB)]:::database
    end

    %% External Services Layer
    subgraph "External Services"
        AMAZON["Amazon Product APIs"]:::external
        EMAILPROV["Email Provider / R2 Storage"]:::external
        SENTRY["Sentry"]:::external
        HOTJAR["Hotjar"]:::external
        AUTHPROV["OAuth Providers"]:::external
    end

    %% Data Flows
    HOME -->|"GET /"| SSR
    PROD -->|"GET /product/:id"| SSR
    DEALS -->|"GET /deals"| SSR
    CATS -->|"GET /categories"| SSR
    SIGNIN -->|"GET /auth/signin"| SSR
    SIGNUP -->|"GET /auth/signup"| SSR
    ADMIN_UI -->|"GET /dashboard"| SSR

    SSR -->|"RSC/SSR Render"| HOME
    SSR -->|"RSC/SSR Render"| PROD
    SSR -->|"RSC/SSR Render"| DEALS
    SSR -->|"RSC/SSR Render"| CATS
    SSR -->|"RSC/SSR Render"| ADMIN_UI

    HOME --> API_CLIENT
    PROD --> API_CLIENT
    DEALS --> API_CLIENT
    CATS --> API_CLIENT
    ADMIN_UI --> API_CLIENT

    API_CLIENT --> HOOKS
    HOOKS --> API
    STORE --> API

    API -->|"GET/POST"| SERVICES
    AUTH_API -->|"POST /auth"| NEXTAUTH
    REVAL -->|"invoke revalidateProducts()"| SSR
    UPLOAD -->|"POST /upload/image"| SERVICES
    EMAIL_API -->|"POST /emails"| SERVICES

    SERVICES --> FAV
    SERVICES --> MCONN
    SERVICES --> MODELS

    MCONN --> DB
    MODELS --> DB
    NEXTAUTH --> DB

    %% Monitoring & Analytics
    HOME --> SENTRY
    HOME --> HOTJAR
    SSR --> SENTRY
    SSR --> HOTJAR

    %% External Data Ingestion
    SERVICES --> AMAZON
    UPLOAD --> EMAILPROV

    %% Click Events
    click SSR "https://github.com/amm10090/amazon-frontend/tree/main/app/"
    click API "https://github.com/amm10090/amazon-frontend/tree/main/app/api/"
    click AUTH_API "https://github.com/amm10090/amazon-frontend/blob/main/app/api/auth/[...nextauth]/route.ts"
    click SIGNIN "https://github.com/amm10090/amazon-frontend/blob/main/app/auth/signin/page.tsx"
    click SIGNUP "https://github.com/amm10090/amazon-frontend/blob/main/app/auth/signup/page.tsx"
    click HOME "https://github.com/amm10090/amazon-frontend/blob/main/app/page.tsx"
    click PROD "https://github.com/amm10090/amazon-frontend/blob/main/app/product/[id]/page.tsx"
    click DEALS "https://github.com/amm10090/amazon-frontend/blob/main/app/deals/page.tsx"
    click CATS "https://github.com/amm10090/amazon-frontend/blob/main/app/categories/page.tsx"
    click ADMIN_UI "https://github.com/amm10090/amazon-frontend/tree/main/app/dashboard/"
    click REVAL "https://github.com/amm10090/amazon-frontend/blob/main/app/actions/revalidateProducts.ts"
    click API_CLIENT "https://github.com/amm10090/amazon-frontend/blob/main/lib/api.ts"
    click HOOKS "https://github.com/amm10090/amazon-frontend/blob/main/lib/hooks.ts"
    click STORE "https://github.com/amm10090/amazon-frontend/blob/main/store/index.ts"
    click MCONN "https://github.com/amm10090/amazon-frontend/blob/main/lib/mongodb.ts"
    click MODELS "https://github.com/amm10090/amazon-frontend/blob/main/lib/models/User.ts"
    click FAV "https://github.com/amm10090/amazon-frontend/blob/main/lib/favorites/index.ts"
    click UPLOAD "https://github.com/amm10090/amazon-frontend/blob/main/app/api/upload/image/route.ts"
    click EMAIL_API "https://github.com/amm10090/amazon-frontend/tree/main/app/api/emails/"
    click EMAIL_API "https://github.com/amm10090/amazon-frontend/tree/main/app/api/email-templates/"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef server fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
    classDef database fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef external fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
```
