# krishnap2k4/insiteecom architecture

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

- Interactive diagram: https://gitdiagram.com/krishnap2k4/insiteecom
- Repository: https://github.com/krishnap2k4/insiteecom

## Overview

1. This is a single Next.js 16 monorepo-style application, not separate frontend/backend services. The App Router hosts three main surfaces: the public storefront, the protected admin dashboard, and the API layer.

2. The `app/(root)/(website)` subtree is the customer-facing storefront. It contains product discovery, category/brand browsing, product detail pages, cart/checkout, account pages, orders, returns, wishlist, profile, support/contact, and policy content. These pages are the primary consumer UI.

3. The `app/(root)/(admin)` subtree is the business back office. It covers catalog management, inventory, orders, shipments, refunds, returns, reviews, customers, customer groups, roles/permissions, campaigns, coupons, newsletter, media, CMS, settings, maintenance, and support tooling. Most admin pages are thin route shells around reusable forms, tables, and dialogs in `components/Application/Admin`.

4. The `app/api` subtree is the backend boundary. It exposes route handlers for auth, catalog, cart, orders, payment, reviews, account data, admin operations, notifications, support conversations, newsletters, maintenance tasks, and utility endpoints like sitemap/robots and cloudinary signatures. This is the main integration point for both website and admin UIs.

5. Persistence is centered on MongoDB via Mongoose models in `models/`. The schema set is broad: products, variants, categories, brands, carts, orders, payments, returns, refunds, reviews, users, roles/permissions, settings, notifications, conversations/messages, inventory, invoices, redirects, subscribers, and more. This makes the data layer the core source of truth for both commerce and operational workflows.

6. Shared business logic lives in `lib/`. This includes database connection handling, auth helpers, API client utilities, cart/order/catalog/coupon/review/shipping helpers, permissions and redirects, logging, rate limiting, soft-delete behavior, invoice PDF generation, email rendering/sending, and Cloudinary helpers. In architecture terms, `lib/` is the service layer between route handlers/UI and the database/integrations.

7. Frontend state is split by concern. `store/` holds Redux reducers for auth, cart, and wishlist, while `hooks/` provides reusable client-side logic such as auth gating, fetch/mutation wrappers, site settings, and window/mobile detection. This means some state is persistent client state, while most server data is fetched through API calls.

8. The UI component system is also layered. `components/ui` contains low-level primitives, `components/Application/Website` contains storefront composites, and `components/Application/Admin` contains dashboard-specific widgets, forms, editors, datatables, and media controls. This keeps shared interaction patterns separated from page routing.

9. Authentication and authorization are enforced in multiple places. `app/api/auth/*` handles login, registration, OTP, reset-password, and email verification flows, while `middleware.js` protects admin and account routes. Roles, permissions, and customer groups in the model layer support the authorization model used by admin endpoints and UI gating.

10. Several external services materially shape the architecture: Razorpay for payment creation and webhook processing, Cloudinary for media upload/hosting, Nodemailer plus email templates for transactional mail, and MongoDB for persistence. These are not optional helpers; they drive checkout, image/document handling, and customer lifecycle communications.

11. Commerce workflows are end-to-end and span UI, API, and data. Typical flows are: storefront browsing → cart mutations → checkout/payment endpoints → order save/webhook confirmation → order status/shipment/refund/return management in admin → customer order history and invoice/download pages. Reviews, wishlist, addresses, and returns follow similar client/API/model loops.

12. Operational and content workflows are first-class. Admin routes and APIs exist for newsletter exports, media management, CMS, support conversation moderation, review moderation, and maintenance scripts such as catalog/order/coupon migrations and RBAC seeding. This indicates the repo is designed as an ecommerce operations platform, not just a shopping site.

13. Cross-cutting concerns are centralized rather than duplicated. Route constants live in `routes/`, shared notifications and audit logging live in `lib/`, and email event templates live in `email/`. Public SEO endpoints like `robots.txt` and `sitemap.xml` are also implemented in-app, reinforcing that Next.js is used as the full delivery/runtime layer.

14. For diagramming, the clearest boundaries are: browser/UI surfaces, App Router route groups, API route handlers, shared service utilities, MongoDB/Mongoose models, and third-party integrations. The dominant data flow is UI → API → lib/service logic → models/database, with outbound side effects to email, payments, media, and logging systems.

Main entry points: [`app/api`](https://github.com/krishnap2k4/insiteecom/tree/main/app/api) (API Layer), [`models`](https://github.com/krishnap2k4/insiteecom/tree/main/models) (Mongo Models), [`app/(root)/(website)`](https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(website)) (Storefront), [`app/(root)/(admin)`](https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(admin)) (Admin Panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Router"]
  node_ui_website["Storefront<br/>route group"]
  node_ui_admin["Admin Panel<br/>route group"]
  node_ui_auth["Auth Flows<br/>route group"]
  node_api_root["API Layer<br/>route handlers"]
end

subgraph group_group_ui["UI Layer"]
  node_ui_storefront_components["Storefront UI<br/>components"]
  node_ui_admin_components["Admin UI<br/>components"]
  node_ui_primitives["UI Primitives<br/>shared components"]
  node_ui_shell["App Shell<br/>layout/providers<br/>[layout.jsx]"]
end

subgraph group_group_service["Shared Services"]
  node_svc_auth["Auth Service<br/>auth/guards<br/>[authentication.js]"]
  node_svc_catalog["Catalog Service<br/>commerce logic<br/>[catalog.js]"]
  node_svc_orders["Order Service<br/>commerce logic<br/>[orders.js]"]
  node_svc_comms["Comms Service<br/>notifications/email<br/>[sendMail.js]"]
  node_svc_permissions["Access Control<br/>rbac/permissions<br/>[permissions.js]"]
  node_svc_media["Media/Storage<br/>upload helpers<br/>[cloudinary.js]"]
  node_svc_runtime["Runtime Utils<br/>infra helpers"]
end

subgraph group_group_data["Data Layer"]
  node_data_models[("Mongo Models<br/>mongoose schemas")]
end

subgraph group_group_ext["Integrations"]
  node_ext_payment{{"Razorpay<br/>payment gateway"}}
  node_ext_cloudinary{{"Cloudinary<br/>media platform"}}
  node_ext_email{{"Email Provider<br/>smtp/mail"}}
  node_ext_mongo[("MongoDB<br/>database")]
end

node_ui_shell -->|"wraps"| node_ui_website
node_ui_shell -->|"wraps"| node_ui_admin
node_ui_shell -->|"wraps"| node_ui_auth
node_ui_website -->|"renders"| node_ui_storefront_components
node_ui_admin -->|"renders"| node_ui_admin_components
node_ui_website -->|"calls"| node_api_root
node_ui_admin -->|"calls"| node_api_root
node_ui_auth -->|"authenticates"| node_api_root
node_api_root -->|"uses"| node_svc_runtime
node_api_root -->|"uses"| node_svc_auth
node_api_root -->|"uses"| node_svc_catalog
node_api_root -->|"uses"| node_svc_orders
node_api_root -->|"uses"| node_svc_comms
node_api_root -->|"uses"| node_svc_permissions
node_api_root -->|"uses"| node_svc_media
node_svc_runtime -->|"connects to"| node_data_models
node_svc_auth -->|"reads/writes"| node_data_models
node_svc_catalog -->|"reads/writes"| node_data_models
node_svc_orders -->|"reads/writes"| node_data_models
node_svc_comms -->|"reads/writes"| node_data_models
node_svc_permissions -->|"reads/writes"| node_data_models
node_svc_media -->|"uploads"| node_ext_cloudinary
node_svc_orders -->|"charges"| node_ext_payment
node_svc_comms -->|"sends"| node_ext_email
node_svc_runtime -->|"persists"| node_ext_mongo
node_ui_admin -.->|"gated by"| node_svc_permissions
node_ui_website -.->|"gated by"| node_svc_auth

click node_ui_website "https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(website)"
click node_ui_admin "https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(admin)"
click node_ui_auth "https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/auth"
click node_api_root "https://github.com/krishnap2k4/insiteecom/tree/main/app/api"
click node_ui_storefront_components "https://github.com/krishnap2k4/insiteecom/tree/main/components/Application/Website"
click node_ui_admin_components "https://github.com/krishnap2k4/insiteecom/tree/main/components/Application/Admin"
click node_ui_primitives "https://github.com/krishnap2k4/insiteecom/tree/main/components/ui"
click node_ui_shell "https://github.com/krishnap2k4/insiteecom/blob/main/app/layout.jsx"
click node_svc_auth "https://github.com/krishnap2k4/insiteecom/blob/main/lib/authentication.js"
click node_svc_catalog "https://github.com/krishnap2k4/insiteecom/blob/main/lib/catalog.js"
click node_svc_orders "https://github.com/krishnap2k4/insiteecom/blob/main/lib/orders.js"
click node_svc_comms "https://github.com/krishnap2k4/insiteecom/blob/main/lib/sendMail.js"
click node_svc_permissions "https://github.com/krishnap2k4/insiteecom/blob/main/lib/permissions.js"
click node_svc_media "https://github.com/krishnap2k4/insiteecom/blob/main/lib/cloudinary.js"
click node_svc_runtime "https://github.com/krishnap2k4/insiteecom/blob/main/lib/databaseConnection.js"
click node_data_models "https://github.com/krishnap2k4/insiteecom/tree/main/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui_website,node_ui_admin,node_ui_auth,node_api_root toneBlue
class node_ui_storefront_components,node_ui_admin_components,node_ui_primitives,node_ui_shell toneAmber
class node_svc_auth,node_svc_catalog,node_svc_orders,node_svc_comms,node_svc_permissions,node_svc_media,node_svc_runtime toneMint
class node_data_models toneRose
class node_ext_payment,node_ext_cloudinary,node_ext_email,node_ext_mongo toneIndigo
```

## Components

### App Router

Next.js route groups and API boundary

- [Storefront](https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(website)): route group · Customer-facing browsing, product, cart, checkout, account, and policy pages · `app/(root)/(website)`
- [Admin Panel](https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/(admin)): route group · Protected back office for catalog, orders, customers, CMS, support, and operations · `app/(root)/(admin)`
- [Auth Flows](https://github.com/krishnap2k4/insiteecom/tree/main/app/(root)/auth): route group · Login, registration, password reset, and email verification screens · `app/(root)/auth`
- [API Layer](https://github.com/krishnap2k4/insiteecom/tree/main/app/api): route handlers · Main backend boundary for commerce, admin, auth, and utility endpoints · `app/api`

### UI Layer

Shared components and route surfaces

- [Storefront UI](https://github.com/krishnap2k4/insiteecom/tree/main/components/Application/Website): components · Website-specific composites for cart, product pages, filters, wishlist, and user panels · `components/Application/Website`
- [Admin UI](https://github.com/krishnap2k4/insiteecom/tree/main/components/Application/Admin): components · Dashboard widgets, forms, tables, editors, media controls, and navigation · `components/Application/Admin`
- [UI Primitives](https://github.com/krishnap2k4/insiteecom/tree/main/components/ui): shared components · Low-level design system controls reused across website and admin · `components/ui`
- [App Shell](https://github.com/krishnap2k4/insiteecom/blob/main/app/layout.jsx): layout/providers · Global layout, providers, loading states, and error handling · `app/layout.jsx`

### Shared Services

Business logic, helpers, and client/server utilities

- [Auth Service](https://github.com/krishnap2k4/insiteecom/blob/main/lib/authentication.js): auth/guards · Session helpers, authorization checks, middleware gating, and OTP flows · `lib/authentication.js`
- [Catalog Service](https://github.com/krishnap2k4/insiteecom/blob/main/lib/catalog.js): commerce logic · Product, category, brand, search, redirect, and shop-the-look helpers · `lib/catalog.js`
- [Order Service](https://github.com/krishnap2k4/insiteecom/blob/main/lib/orders.js): commerce logic · Cart, checkout, orders, invoices, shipping, refunds, and returns helpers · `lib/orders.js`
- [Comms Service](https://github.com/krishnap2k4/insiteecom/blob/main/lib/sendMail.js): notifications/email · Email rendering/sending, templates, notifications, conversations, and audit logging · `lib/sendMail.js`
- [Access Control](https://github.com/krishnap2k4/insiteecom/blob/main/lib/permissions.js): rbac/permissions · Permission catalog, role helpers, and customer/admin authorization rules · `lib/permissions.js`
- [Media/Storage](https://github.com/krishnap2k4/insiteecom/blob/main/lib/cloudinary.js): upload helpers · Cloudinary helpers, public IDs, and media workflows · `lib/cloudinary.js`
- [Runtime Utils](https://github.com/krishnap2k4/insiteecom/blob/main/lib/databaseConnection.js): infra helpers · Database connection, API client, rate limiting, settings, logging, and shared utilities · `lib/databaseConnection.js`

### Data Layer

Mongoose models and database source of truth

- [Mongo Models](https://github.com/krishnap2k4/insiteecom/tree/main/models): mongoose schemas · Products, users, orders, payments, inventory, support, settings, and other source-of-truth collections · `models`

### Integrations

External systems used by checkout, media, and email

- **Razorpay**: payment gateway · Payment order creation and webhook confirmation
- **Cloudinary**: media platform · Image and file hosting plus signed uploads
- **Email Provider**: smtp/mail · Transactional and notification delivery through Nodemailer templates
- **MongoDB**: database · Primary persistence backend used through Mongoose

## Connections

- App Shell → Storefront: wraps · Global app shell hosts storefront routes
- App Shell → Admin Panel: wraps · Global app shell hosts admin routes
- App Shell → Auth Flows: wraps · Global app shell hosts auth screens
- Storefront → Storefront UI: renders · Storefront pages are composed from website components
- Admin Panel → Admin UI: renders · Admin route shells use reusable dashboard components
- Storefront → API Layer: calls · Storefront interacts with backend endpoints for browsing and commerce
- Admin Panel → API Layer: calls · Admin UI uses route handlers for CRUD and operations
- Auth Flows → API Layer: authenticates · Auth pages submit to login, registration, OTP, and reset endpoints
- API Layer → Runtime Utils: uses · Route handlers rely on shared runtime utilities and API client helpers
- API Layer → Auth Service: uses · Authentication routes and guards use auth helpers
- API Layer → Catalog Service: uses · Catalog-related handlers share catalog and search logic
- API Layer → Order Service: uses · Cart, checkout, payment, shipping, refund, and return handlers use order logic
- API Layer → Comms Service: uses · Support, notifications, newsletters, and email flows use comms helpers
- API Layer → Access Control: uses · Admin endpoints enforce permissions and role rules
- API Layer → Media/Storage: uses · Media endpoints rely on upload and signature helpers
- Runtime Utils → Mongo Models: connects to · Database connection and shared utilities operate over Mongoose models
- Auth Service → Mongo Models: reads/writes · Auth and middleware state depends on user, OTP, role, and permission data
- Catalog Service → Mongo Models: reads/writes · Catalog helpers manage products, categories, brands, redirects, and shop-the-look records
- Order Service → Mongo Models: reads/writes · Commerce workflows persist carts, orders, payments, shipments, returns, refunds, and invoices
- Comms Service → Mongo Models: reads/writes · Comms workflows persist notifications, conversations, messages, templates, logs, and subscribers
- Access Control → Mongo Models: reads/writes · RBAC uses roles, permissions, customer groups, and audit records
- Media/Storage → Cloudinary: uploads · Media helpers integrate with Cloudinary
- Order Service → Razorpay: charges · Checkout and webhook flows integrate with Razorpay
- Comms Service → Email Provider: sends · Transactional mail and notifications are delivered through email templates and SMTP
- Runtime Utils → MongoDB: persists · Primary persistence is MongoDB through Mongoose
- Admin Panel → Access Control: gated by · Admin surface is constrained by roles and permissions
- Storefront → Auth Service: gated by · Account areas depend on auth/session checks
