# imshivendra29/shopnext architecture

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

- Interactive diagram: https://gitdiagram.com/imshivendra29/shopnext
- Repository: https://github.com/imshivendra29/shopnext

## Overview

1. This is a single ASP.NET Core 8 Web API organized as a layered e-commerce backend. The primary runtime path is HTTP request → middleware → controller → service → repository → EF Core DbContext → relational database.

2. The API layer is split into feature controllers: Auth, User, Product, Category, Cart, Order, Review, Address, Banner, OTP, and Payment. Controllers stay thin and primarily translate HTTP requests into DTOs and delegate all business rules to services.

3. The service layer is the main business boundary. Each domain area has an interface and implementation pair, which keeps controllers isolated from persistence and external integrations. This layer contains the core rules for login/register, profile management, cart merging, checkout, review ownership, default address logic, OTP verification, and payment lifecycle checks.

4. Persistence is handled by a repository + Unit of Work pattern on top of Entity Framework Core. The database context is `ShopNextDbContext`, with repositories for each aggregate area such as users, products, categories, carts, orders, reviews, banners, and OTP records. The Unit of Work acts as the transaction/cohesion boundary for multi-entity operations like checkout and order creation.

5. The domain model is centered on commerce entities: `User`, `Product`, `Category`, `Cart`, `CartItem`, `Order`, `OrderItem`, `Review`, `Address`, `Banner`, `Payment`, and `OtpVerification`. DTOs are used heavily to separate API contracts from persistence models, especially for create/update inputs and response shaping.

6. Authentication and authorization are JWT-based. `JwtHelper` is responsible for token creation/claims, while protected endpoints use bearer auth and role-based checks. The README and code structure indicate user/admin distinctions, with admin-only write access for catalog and banner operations.

7. Several external integrations materially shape the architecture:
   - Cloudinary for server-side image uploads for products, categories, banners, and user profile photos.
   - Razorpay for online payment initiation and signature verification.
   - Redis for caching/rate-limit/OTP-related workflows.
   - SMS/OTP delivery is represented by the OTP module, with rate-limited verification behavior.

8. OTP and rate limiting are first-class security subsystems. The repo includes dedicated rate-limit policy constants, rate-limiter extensions, and Redis-backed cache services. OTP verification is stored hashed, time-limited, and request-capped, and checkout requires phone verification before order placement.

9. Order and payment flow is intentionally server-authoritative. Cart contents are converted into order snapshots at checkout so pricing cannot be manipulated from the client. Payment initiation pulls the amount from persisted order data, not from the request, and payment verification validates the Razorpay signature before updating payment/order state.

10. The API is hardened with centralized exception handling via `ErrorHandlingMiddleware`, producing consistent error responses. This middleware sits early in the pipeline so failures from controllers, services, repositories, or external services are normalized before reaching clients.

11. The repository also includes `docs/deployment.md` and `docs/ratelimit.md`, plus a Dockerfile, which indicates the app is designed to be containerized and deployed as a standalone backend service. Swagger/OpenAPI is part of the delivery surface for manual testing and API discovery.

12. One architecture note for diagram accuracy: the README says SQL Server, but the migration names and compiled dependencies show PostgreSQL/Npgsql artifacts as well. So the safest diagram is “EF Core-backed relational database” with provider-specific configuration likely present or having changed over time, rather than hard-coding only one database vendor.

Main entry points: [`Controllers`](https://github.com/imshivendra29/shopnext/tree/main/Controllers) (Feature controllers), [`Data/UnitOfWork.cs`](https://github.com/imshivendra29/shopnext/blob/main/Data/UnitOfWork.cs) (Unit of Work), [`Program.cs`](https://github.com/imshivendra29/shopnext/blob/main/Program.cs) (Program), [`Services/Implementations/AuthService.cs`](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/AuthService.cs) (Auth & OTP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host"]
  node_program["Program<br/>startup<br/>[Program.cs]"]
end

subgraph group_api["API"]
  node_controllers["Feature controllers<br/>api layer"]
  node_dtos["DTO contracts<br/>api models"]
end

subgraph group_app["Application"]
  node_auth_otp_svc["Auth & OTP<br/>[AuthService.cs]"]
  node_catalog_svc["Catalog<br/>[ProductService.cs]"]
  node_cart_svc["Cart<br/>[CartService.cs]"]
  node_order_svc["Orders<br/>[OrderService.cs]"]
  node_account_svc["Users & address<br/>[UserService.cs]"]
  node_review_svc["Reviews<br/>[ReviewService.cs]"]
  node_payment_svc["Payments<br/>[RazorpayService.cs]"]
end

subgraph group_persist["Persistence"]
  node_uow_repo["Unit of Work<br/>data access<br/>[UnitOfWork.cs]"]
  node_repositories["Repositories<br/>repository layer"]
  node_dbcontext[("DbContext<br/>ef core")]
  node_database[("Relational DB<br/>database")]
end

subgraph group_domain["Domain"]
  node_models["Domain models<br/>entities"]
end

subgraph group_infra["Integrations"]
  node_cloudinary["Cloudinary<br/>image storage"]
  node_razorpay["Razorpay<br/>payment gateway<br/>[RazorpayService.cs]"]
  node_redis["Redis cache"]
end

subgraph group_cross["Cross-cutting"]
  node_error_mw["Error middleware"]
  node_rate_limit["Rate limiting<br/>policy/extensions"]
  node_jwt_helper["JWT helper<br/>auth helper<br/>[JwtHelper.cs]"]
end

node_program -->|"adds"| node_error_mw
node_program -->|"configures"| node_rate_limit
node_program -->|"wires"| node_jwt_helper
node_program -->|"maps"| node_controllers
node_controllers -->|"uses"| node_dtos
node_controllers -->|"calls"| node_auth_otp_svc
node_controllers -->|"calls"| node_catalog_svc
node_controllers -->|"calls"| node_cart_svc
node_controllers -->|"calls"| node_order_svc
node_controllers -->|"calls"| node_account_svc
node_controllers -->|"calls"| node_review_svc
node_controllers -->|"calls"| node_payment_svc
node_auth_otp_svc -->|"issues"| node_jwt_helper
node_auth_otp_svc -->|"stores"| node_redis
node_auth_otp_svc -->|"persists"| node_uow_repo
node_catalog_svc -->|"uploads"| node_cloudinary
node_catalog_svc -->|"persists"| node_uow_repo
node_cart_svc -->|"persists"| node_uow_repo
node_order_svc -->|"persists"| node_uow_repo
node_order_svc -->|"verifies"| node_razorpay
node_order_svc -->|"checks"| node_redis
node_account_svc -->|"uploads"| node_cloudinary
node_account_svc -->|"persists"| node_uow_repo
node_review_svc -->|"persists"| node_uow_repo
node_payment_svc -->|"integrates"| node_razorpay
node_uow_repo -->|"coordinates"| node_repositories
node_repositories -->|"uses"| node_dbcontext
node_dbcontext -->|"writes"| node_database
node_dbcontext -->|"maps"| node_models
node_repositories -->|"queries"| node_models
node_controllers -.->|"fails through"| node_error_mw

click node_program "https://github.com/imshivendra29/shopnext/blob/main/Program.cs"
click node_error_mw "https://github.com/imshivendra29/shopnext/blob/main/Middleware/ErrorHandlingMiddleware.cs"
click node_rate_limit "https://github.com/imshivendra29/shopnext/blob/main/Extensions/RateLimiterExtensions.cs"
click node_jwt_helper "https://github.com/imshivendra29/shopnext/blob/main/Helpers/JwtHelper.cs"
click node_controllers "https://github.com/imshivendra29/shopnext/tree/main/Controllers"
click node_dtos "https://github.com/imshivendra29/shopnext/tree/main/DTOs"
click node_auth_otp_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/AuthService.cs"
click node_catalog_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/ProductService.cs"
click node_cart_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/CartService.cs"
click node_order_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/OrderService.cs"
click node_account_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/UserService.cs"
click node_review_svc "https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/ReviewService.cs"
click node_payment_svc "https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Payment/Implementations/RazorpayService.cs"
click node_uow_repo "https://github.com/imshivendra29/shopnext/blob/main/Data/UnitOfWork.cs"
click node_repositories "https://github.com/imshivendra29/shopnext/tree/main/Repositories/Implementations"
click node_dbcontext "https://github.com/imshivendra29/shopnext/blob/main/Data/ShopNextDbContext.cs"
click node_models "https://github.com/imshivendra29/shopnext/tree/main/Models"
click node_cloudinary "https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Cloudinary/Implementations/CloudinaryService.cs"
click node_razorpay "https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Payment/Implementations/RazorpayService.cs"
click node_redis "https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Redis/RedisCacheService.cs"

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_program,node_error_mw,node_rate_limit,node_jwt_helper toneBlue
class node_controllers,node_dtos toneAmber
class node_auth_otp_svc,node_catalog_svc,node_cart_svc,node_order_svc,node_account_svc,node_review_svc,node_payment_svc toneMint
class node_uow_repo,node_repositories,node_dbcontext,node_database toneRose
class node_models toneIndigo
class node_cloudinary,node_razorpay,node_redis toneTeal
```

## Components

### Host

Application startup and composition root

- [Program](https://github.com/imshivendra29/shopnext/blob/main/Program.cs): startup · Composes DI, middleware, auth, rate limits, and endpoint pipeline · `Program.cs`

### API

HTTP entrypoints and request translation

- [Feature controllers](https://github.com/imshivendra29/shopnext/tree/main/Controllers): api layer · Thin HTTP controllers for auth, catalog, cart, order, review, address, banner, OTP, and payment · `Controllers`
- [DTO contracts](https://github.com/imshivendra29/shopnext/tree/main/DTOs): api models · Request and response shapes that decouple HTTP contracts from persistence models · `DTOs`

### Application

Business services and workflow orchestration

- [Auth & OTP](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/AuthService.cs): service · Login/register, JWT issuance, OTP verification, and security rules · `Services/Implementations/AuthService.cs`
- [Catalog](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/ProductService.cs): service · Product, category, and banner workflows including image handling · `Services/Implementations/ProductService.cs`
- [Cart](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/CartService.cs): service · Cart merge, item updates, and shopping cart rules · `Services/Implementations/CartService.cs`
- [Orders](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/OrderService.cs): service · Checkout, snapshot creation, order lifecycle, and payment coordination · `Services/Implementations/OrderService.cs`
- [Users & address](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/UserService.cs): service · Profile updates, password changes, default address logic, and address management · `Services/Implementations/UserService.cs`
- [Reviews](https://github.com/imshivendra29/shopnext/blob/main/Services/Implementations/ReviewService.cs): service · Review ownership and product feedback rules · `Services/Implementations/ReviewService.cs`
- [Payments](https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Payment/Implementations/RazorpayService.cs): service · Razorpay initiation and signature verification for server-authoritative payment flow · `Infrastructure/Payment/Implementations/RazorpayService.cs`

### Persistence

EF Core data access and transaction boundary

- [Unit of Work](https://github.com/imshivendra29/shopnext/blob/main/Data/UnitOfWork.cs): data access · Cohesion and transaction boundary across repositories · `Data/UnitOfWork.cs`
- [Repositories](https://github.com/imshivendra29/shopnext/tree/main/Repositories/Implementations): repository layer · Aggregate repositories for users, products, categories, carts, orders, reviews, banners, and OTP records · `Repositories/Implementations`
- [DbContext](https://github.com/imshivendra29/shopnext/blob/main/Data/ShopNextDbContext.cs): ef core · ShopNextDbContext persistence model and change tracking · `Data/ShopNextDbContext.cs`
- **Relational DB**: database · EF Core-backed relational store with provider-specific configuration

### Domain

Core commerce entities and contracts

- [Domain models](https://github.com/imshivendra29/shopnext/tree/main/Models): entities · User, product, cart, order, review, address, banner, payment, and OTP entities · `Models`

### Integrations

External services and platform adapters

- [Cloudinary](https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Cloudinary/Implementations/CloudinaryService.cs): image storage · Server-side image uploads for products, categories, banners, and profiles · `Infrastructure/Cloudinary/Implementations/CloudinaryService.cs`
- [Razorpay](https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Payment/Implementations/RazorpayService.cs): payment gateway · Online payment provider for initiation and verification · `Infrastructure/Payment/Implementations/RazorpayService.cs`
- [Redis cache](https://github.com/imshivendra29/shopnext/blob/main/Infrastructure/Redis/RedisCacheService.cs): cache · Caching, OTP, and rate-limit backing store · `Infrastructure/Redis/RedisCacheService.cs`

### Cross-cutting

Shared security, caching, and runtime concerns

- [Error middleware](https://github.com/imshivendra29/shopnext/blob/main/Middleware/ErrorHandlingMiddleware.cs): middleware · Normalizes exceptions into consistent API responses · `Middleware/ErrorHandlingMiddleware.cs`
- [Rate limiting](https://github.com/imshivendra29/shopnext/blob/main/Extensions/RateLimiterExtensions.cs): policy/extensions · Policy constants and limiter extensions for request caps · `Extensions/RateLimiterExtensions.cs`
- [JWT helper](https://github.com/imshivendra29/shopnext/blob/main/Helpers/JwtHelper.cs): auth helper · Creates bearer tokens and claims for authenticated users · `Helpers/JwtHelper.cs`

## Connections

- Program → Error middleware: adds · Registers centralized exception handling
- Program → Rate limiting: configures · Adds request limiting policies and extensions
- Program → JWT helper: wires · Registers authentication/token services
- Program → Feature controllers: maps · Exposes API endpoints through the HTTP pipeline
- Feature controllers → DTO contracts: uses · Accepts and returns typed request/response contracts
- Feature controllers → Auth & OTP: calls · Delegates auth and OTP workflows
- Feature controllers → Catalog: calls · Delegates product, category, and banner operations
- Feature controllers → Cart: calls · Delegates cart operations
- Feature controllers → Orders: calls · Delegates checkout and order placement
- Feature controllers → Users & address: calls · Delegates profile and address operations
- Feature controllers → Reviews: calls · Delegates review operations
- Feature controllers → Payments: calls · Delegates payment initiation and verification
- Auth & OTP → JWT helper: issues · Builds bearer tokens and claims
- Auth & OTP → Redis cache: stores · Uses cache for OTP and request-capped flows
- Auth & OTP → Unit of Work: persists · Reads/writes user and OTP state through repositories
- Catalog → Cloudinary: uploads · Stores product, category, banner, and profile images
- Catalog → Unit of Work: persists · Coordinates catalog writes and reads
- Cart → Unit of Work: persists · Updates cart aggregates and items
- Orders → Unit of Work: persists · Creates order snapshots and commits multi-entity changes
- Orders → Razorpay: verifies · Initiates and verifies payment lifecycle state
- Orders → Redis cache: checks · Relies on verification and throttling related cache state
- Users & address → Cloudinary: uploads · Handles profile photo updates
- Users & address → Unit of Work: persists · Updates user and address records
- Reviews → Unit of Work: persists · Stores and validates review ownership
- Payments → Razorpay: integrates · Uses gateway client for payment operations
- Unit of Work → Repositories: coordinates · Provides transaction and cohesion boundary
- Repositories → DbContext: uses · Implements data access on top of EF Core
- DbContext → Relational DB: writes · Persists commerce data to relational storage
- DbContext → Domain models: maps · Tracks entity sets and relationships
- Repositories → Domain models: queries · Reads and mutates domain entities
- Feature controllers → Error middleware: fails through · Unhandled errors are normalized by middleware
