# sesto-dev/next-prisma-tailwind-ecommerce architecture

> Architecture diagram of the GitHub repository sesto-dev/next-prisma-tailwind-ecommerce, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sesto-dev/next-prisma-tailwind-ecommerce
- Repository: https://github.com/sesto-dev/next-prisma-tailwind-ecommerce

## Overview

##### Project Type and Purpose
- This is a monorepo hosting a full-stack e-commerce platform, composed of two separate Next.js 14 applications:
- Admin Panel (apps/admin)
- Storefront (apps/storefront)
- Both apps use React Server Components, the App Router, Prisma ORM (PostgreSQL backend), TailwindCSS for styling, and share utility packages under `packages/`.

##### High-Level File Structure Analysis
- Root
- Configuration files (.eslintrc.js, bun.lockb, package.json, etc.)
- `apps/` – two Next.js apps
- `packages/` – shared libraries (mail, oauth, sms, zarinpal, slugify, regex, rng)
- Each app (`admin` and `storefront`) contains:
- `src/app/` – UI pages and API routes
- `src/components/`, `src/hooks/`, `src/lib/`, `src/providers/`, `src/types/` – logical layers
- `prisma/schema.prisma` & ORM client wrapper (`lib/prisma.ts`)
- `middleware.ts` – authentication (JWT in httpOnly cookies)
- Shared packages implement cross-cutting services (email/SMS sending, OAuth, payment gateway integration, utility functions).

##### Main Components
a. Frontend & BFF Layers (for each app)
– Next.js App Router (UI pages)
– React Server Components & server actions
– API routes (`src/app/api/.../route.ts`)
– JWT middleware (auth guard)
b. Data Layer
– Prisma ORM
– PostgreSQL database
– Seed scripts (admin app)
c. Shared Services (external or via `packages/`)
– Email service (Cloudinary for file uploads, react-email templates, SMTP transport via mail package)
– SMS service (via sms package)
– OAuth providers (Google, Apple via oauth package)
– Payment gateway (Zarinpal package)
d. Deployment Units
– Two separate Vercel (or Docker) deployments for Admin and Storefront
– Monorepo CI/CD pulling from shared root

##### Relationships and Data Flows
- User → Browser → Next.js UI
- UI → (HTTP) → Next.js API Routes
- API → Prisma client → PostgreSQL (CRUD: products, orders, users, payments, blogs)
- API → External packages → External services (email, SMS, OAuth, payments)
- Middleware intercepts requests → validates JWT → injects `X-USER-ID` header → downstream handlers
- Shared packages called both by Admin and Storefront servers

##### Architectural Patterns & Design Principles
- Backend-For-Frontend (each Next.js app serves its own BFF)
- Monorepo modularity (shared packages for DRY code)
- Layered architecture (UI → API → Services → Data)
- Server Components for performance and partial hydration
- Secure cookie-based JWT auth via middleware

##### Detail & Labels
- API route groups (e.g., `/api/products`, `/api/auth/otp`)
- Middleware JWT validation and header injection
- Prisma schema and client instantiation (lib/prisma.ts)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Browser[(Browser)]:::external

    subgraph "Admin Next.js App (apps/admin)"
        direction TB
        AdminUI["UI & App Router"]:::frontend
        AdminRSC["React Server Components & Actions"]:::frontend
        AdminAPI["API Routes"]:::api
        AdminMiddleware["JWT Middleware"]:::middleware
        AdminPrisma["Prisma Client"]:::database
        AdminSeed["Seed Scripts"]:::database
    end

    subgraph "Storefront Next.js App (apps/storefront)"
        direction TB
        StorefrontUI["UI & App Router"]:::frontend
        StorefrontRSC["React Server Components & Actions"]:::frontend
        StorefrontAPI["API Routes"]:::api
        StorefrontMiddleware["JWT Middleware"]:::middleware
        StorefrontPrisma["Prisma Client"]:::database
    end

    subgraph "Shared Packages (packages/)"
        direction TB
        Mail["Email Service"]:::package
        SMS["SMS Service"]:::package
        OAuth["OAuth Providers"]:::package
        Zarinpal["Payment Gateway"]:::package
        Utils["Utilities"]:::package
    end

    PrismaSchema["Prisma ORM"]:::database
    Database[(PostgreSQL)]:::db

    Cloudinary[(Cloudinary)]:::external
    SMTP[(SMTP)]:::external
    SMSService[(SMS Gateway)]:::external
    Google[(Google OAuth)]:::external
    Apple[(Apple OAuth)]:::external
    Payments[(Zarinpal API)]:::external

    Monorepo["Monorepo CI/CD"]:::package

    %% Flows
    Browser -->|"HTTP"| AdminUI
    Browser -->|"HTTP"| StorefrontUI

    AdminUI -->|"App Router"| AdminAPI
    StorefrontUI -->|"App Router"| StorefrontAPI

    AdminAPI -->|"invokes"| AdminMiddleware
    StorefrontAPI -->|"invokes"| StorefrontMiddleware
    AdminMiddleware -->|"validates JWT"| AdminAPI
    StorefrontMiddleware -->|"validates JWT"| StorefrontAPI

    AdminAPI -->|"Prisma Client"| AdminPrisma
    StorefrontAPI -->|"Prisma Client"| StorefrontPrisma

    AdminPrisma --> PrismaSchema
    StorefrontPrisma --> PrismaSchema
    PrismaSchema --> Database

    AdminAPI -->|"sendMail()"| Mail
    StorefrontAPI -->|"sendMail()"| Mail
    Mail --> SMTP

    AdminAPI -->|"sendSMS()"| SMS
    StorefrontAPI -->|"sendSMS()"| SMS
    SMS --> SMSService

    AdminAPI -->|"oauth()"| OAuth
    StorefrontAPI -->|"oauth()"| OAuth
    OAuth --> Google
    OAuth --> Apple

    AdminAPI -->|"payment()"| Zarinpal
    StorefrontAPI -->|"payment()"| Zarinpal
    Zarinpal --> Payments

    Mail --> Monorepo
    SMS --> Monorepo
    OAuth --> Monorepo
    Zarinpal --> Monorepo
    Utils --> Monorepo

    Monorepo --> AdminUI
    Monorepo --> StorefrontUI

    %% Click Events
    click AdminUI "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/apps/admin/src/app"
    click AdminRSC "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/apps/admin/src/actions"
    click AdminAPI "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/apps/admin/src/app/api"
    click AdminMiddleware "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/apps/admin/src/middleware.ts"
    click AdminPrisma "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/apps/admin/src/lib/prisma.ts"
    click AdminSeed "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/apps/admin/prisma/seed.ts"
    click StorefrontUI "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/apps/storefront/src/app"
    click StorefrontAPI "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/apps/storefront/src/app/api"
    click StorefrontMiddleware "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/apps/storefront/src/middleware.ts"
    click StorefrontPrisma "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/apps/storefront/src/lib/prisma.ts"
    click Mail "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/packages/mail"
    click SMS "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/packages/sms/src/index.ts"
    click OAuth "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/packages/oauth"
    click Zarinpal "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/tree/main/packages/zarinpal"
    click Monorepo "https://github.com/sesto-dev/next-prisma-tailwind-ecommerce/blob/main/package.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef api fill:#b3e6ff,stroke:#333,stroke-width:1px
    classDef middleware fill:#99ddff,stroke:#333,stroke-width:1px
    classDef database fill:#d4f5d4,stroke:#333,stroke-width:1px
    classDef db fill:#a3d3a3,stroke:#333,stroke-width:1px
    classDef package fill:#e0ccff,stroke:#333,stroke-width:1px
    classDef external fill:#ffd699,stroke:#333,stroke-width:1px
```
