# kquiggins/nextjs_ecommerce architecture

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

- Interactive diagram: https://gitdiagram.com/kquiggins/nextjs_ecommerce
- Repository: https://github.com/kquiggins/nextjs_ecommerce

## Overview

##### Project type and purpose
- This is a full-stack e-commerce web application (“Comic Store”) built with Next.js App Router and React Server Components.
- It offers a product catalog, user authentication, shopping cart, checkout flow (shipping, payment), order management, user profile, and PayPal integration.

##### File structure
- Top-level directories:
- app/ – Next.js App Router folders, split by route segments: (auth), (root), admin, user, api.
- components/ – Shared React UI components (shadcn/ui + custom).
- lib/ – Server-side business logic (“actions”), utility functions, auth guard, PayPal helper.
- db/ & prisma/ – Prisma client, schema, migrations, seed/sample data.
- public/ & assets/ – Static images and global CSS.
- middleware.ts, next.config.ts, auth.config.ts – Configuration for auth, routing, builds.
- app/api/auth – NextAuth.js route for credentials provider.
- prisma/migrations – Database evolution via SQL.

##### README for additional insights
- Confirms Next.js, Tailwind CSS, TypeScript, Prisma ORM (PostgreSQL/Neon), NextAuth.js, PayPal.
- Highlights use of React Server Components, Server Actions for state management.
- Outlines feature set and data-flow points (e.g., cart.actions.ts, order.actions.ts).

##### Main components & interactions
a. Frontend layer (Browser)
- React components under app/ and components/ (RSC + client components).
- UI state hooks (`useTransition`, `useActionState`).
- Static assets (public/, assets/).
b. Next.js server layer
- App Router server-side rendering and API Routes (app/api).
- Server Actions in lib/actions invoked via POST requests or streaming.
- Middleware for guarding routes (admin-guard, lib/auth-guard.ts).
c. Business logic layer
- lib/actions: cart, comic, order, user.
- lib/utils, lib/validators, auth.ts, auth.config.ts.
d. Data access layer
- Prisma Client (db/prisma.ts) connecting to PostgreSQL.
- prisma/schema.prisma & migrations.
e. External services
- NextAuth.js identity provider (credentials).
- PayPal REST API for payment capture.
- Neon DB (PostgreSQL) hosting.
f. Deployment environment
- Vercel serverless functions or Node server.
- Environment variables (.env.local) for DB, NextAuth secrets, PayPal credentials.

##### Architectural patterns & design principles
- Layered architecture: UI → Server/API → Business logic → Data layer.
- React Server Components with streaming and Server Actions replace traditional REST calls.
- MVC-ish separation: app/ (view+controller), lib/actions (controller/model glue), prisma (model).
- Authentication and authorization via middleware (NextAuth + custom guards).
- Infrastructure as code: Prisma migrations define DB schema evolution.

##### Diagramming recommendations
- Green for server runtime (Next.js App Router, API Routes).
- Orange for business logic (lib/actions).
- Purple clouds for external services (NextAuth, PayPal).
- User → Next.js Server (SSR request, API call).
- Next.js Server → Business Logic → Database.
- Server → PayPal API (payment capture).
- Browser → PayPal checkout if applicable.
- RSC vs. client components, server actions, and API endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser / Client Layer
    subgraph "Browser / Client"
        direction TB
        UIApp["UI Routes (app/)"]:::frontend
        SharedUI["Shared Components (components/)"]:::frontend
        StaticAssets["Static Assets (public/, assets/)"]:::frontend
    end

    %% Next.js Server Layer
    subgraph "Next.js Server (Node Runtime)"
        direction TB
        AppRouter["App Router (SSR & RSC)"]:::server
        APIRoutes["NextAuth API Route"]:::server
        Middleware["Middleware & Guards"]:::server
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        direction TB
        CartActions["Cart Actions"]:::business
        OrderActions["Order Actions"]:::business
        ComicActions["Comic Actions"]:::business
        UserActions["User Actions"]:::business
        PayPalHelper["PayPal Helper"]:::business
        Utils["Utils & Validators"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PrismaClient["Prisma Client"]:::data
        PrismaSchema["Prisma Schema & Migrations"]:::data
        SeedData["Seed & Sample Data"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        NextAuthService["NextAuth Identity Provider"]:::external
        PayPalAPI["PayPal REST API"]:::external
    end

    %% Connections
    UIApp -->|"SSR/API Calls"| AppRouter
    SharedUI --> AppRouter
    StaticAssets --> AppRouter

    AppRouter -->|"Invokes"| CartActions
    AppRouter -->|"Invokes"| OrderActions
    AppRouter -->|"Invokes"| ComicActions
    AppRouter -->|"Invokes"| UserActions
    AppRouter -->|"Routes through"| Middleware
    AppRouter -->|"API Auth Requests"| APIRoutes

    CartActions -->|"Reads/Writes"| PrismaClient
    OrderActions --> PrismaClient
    ComicActions --> PrismaClient
    UserActions --> PrismaClient
    PayPalHelper -->|"Calls"| PayPalAPI
    Utils --> CartActions
    Utils --> OrderActions
    Utils --> ComicActions
    Utils --> UserActions

    PrismaClient --> PrismaSchema
    PrismaClient --> SeedData

    APIRoutes -->|"Validates via"| NextAuthService
    Middleware -->|"Guards with"| NextAuthService

    %% Click Events
    click UIApp "https://github.com/kquiggins/nextjs_ecommerce/tree/main/app/"
    click SharedUI "https://github.com/kquiggins/nextjs_ecommerce/tree/main/components/"
    click APIRoutes "https://github.com/kquiggins/nextjs_ecommerce/blob/main/app/api/auth/[...nextauth]/route.ts"
    click Middleware "https://github.com/kquiggins/nextjs_ecommerce/blob/main/middleware.ts"
    click Middleware "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/auth-guard.ts"
    click CartActions "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/actions/cart.actions.ts"
    click OrderActions "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/actions/order.actions.ts"
    click ComicActions "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/actions/comic.actions.ts"
    click UserActions "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/actions/user.actions.ts"
    click PayPalHelper "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/paypal.ts"
    click Utils "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/utils.ts"
    click Utils "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/validators.ts"
    click Utils "https://github.com/kquiggins/nextjs_ecommerce/blob/main/lib/constants/index.ts"
    click PrismaClient "https://github.com/kquiggins/nextjs_ecommerce/blob/main/db/prisma.ts"
    click SeedData "https://github.com/kquiggins/nextjs_ecommerce/blob/main/db/seed.ts"
    click SeedData "https://github.com/kquiggins/nextjs_ecommerce/blob/main/db/sample-data.ts"
    click PrismaSchema "https://github.com/kquiggins/nextjs_ecommerce/blob/main/prisma/schema.prisma"
    click PrismaSchema "https://github.com/kquiggins/nextjs_ecommerce/tree/main/prisma/migrations/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef server fill:#90EE90,stroke:#000,stroke-width:1px
    classDef business fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#D8BFD8,stroke:#000,stroke-width:1px
```
