# fahadbinsiddique/e-commerce-ordering-payment-system architecture

> Architecture diagram of the GitHub repository fahadbinsiddique/e-commerce-ordering-payment-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fahadbinsiddique/e-commerce-ordering-payment-system
- Repository: https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system

## Overview

#### Purpose and Entry Points
Production-style e-commerce system: Django REST API plus Next.js storefront. Backend HTTP entry points are routed through `backend/config/urls.py`, served via `backend/config/asgi.py` or `backend/config/wsgi.py`; Django commands start at `backend/manage.py`. The frontend uses Next.js App Router from `frontend/app/layout.jsx` and `frontend/app/page.jsx`.

#### Client, Session, and API Boundary
The Next.js client provides catalog, cart, checkout, order/payment history, and admin-facing pages. Route protection is enforced at the frontend edge by `frontend/middleware.js`. Zustand maintains browser-side authentication and cart state in `frontend/store/auth-store.js` and `frontend/store/cart-store.js`; API calls are centralized through `frontend/lib/api.js` and domain service modules such as `frontend/services/paymentService.js`.

#### Identity and Catalog Domain
JWT authentication is implemented by the accounts API, centered on the custom user model and serializers/views: `backend/accounts/models.py`, `backend/accounts/views.py`, `backend/accounts/urls.py`. Categories form a hierarchy used by catalog and recommendation traversal; products support CRUD plus filtering/pagination. Core boundaries are `backend/categories/models.py`, `backend/products/models.py`, and `backend/products/views.py`. Administrative writes are restricted while storefront reads feed product pages and order creation.

#### Order Creation and Pricing
Order APIs receive cart lines, persist orders and price-snapshotted order items, and expose user order lifecycle operations. The order domain resides in `backend/orders/models.py`, `backend/orders/views.py`, and `backend/orders/serializers.py`. Total computation is deliberately separated into `backend/services/order/order_calculator.py`, using deterministic Decimal rounding rather than trusting client totals. This creates the boundary between mutable catalog pricing and immutable order pricing.

#### Payment Orchestration and Fulfillment
Payments are provider-neutral at the API/model layer (`backend/payments/views.py`, `backend/payments/models.py`) and delegated to a strategy abstraction (`backend/services/payment/base.py`, `backend/services/payment/factory.py`). Concrete Stripe and bKash integrations live in `backend/services/payment/stripe.py` and `backend/services/payment/bkash.py`. Checkout returns either Stripe client-confirmation data or a bKash redirect URL. Provider notifications enter `backend/payments/webhooks.py`; lifecycle handling marks payments/orders successful and invokes stock fulfillment.

#### Transaction Safety and External Services
Successful payment triggers exactly-once stock reduction through atomic, row-locked inventory logic in `backend/services/stock/stock_manager.py`. PostgreSQL is the production relational store; Redis backs recommendation caching. Stripe is an SDK/webhook integration with signature validation; bKash is a tokenized-checkout REST integration whose callback is re-verified server-side. Runtime settings separate development, production, and testing in `backend/config/settings/base.py`, `backend/config/settings/production.py`, and `backend/config/settings/testing.py`.

#### Recommendations and Deployment Topology
Recommendations traverse category relationships with DFS and cache category/result data in Redis, exposed through `backend/recommendations/views.py` and implemented in `backend/recommendations/services.py`. Docker Compose runs backend, PostgreSQL, and Redis via `docker-compose.yml`; the backend image is defined by `backend/Dockerfile`. The frontend is independently deployable to Vercel (`frontend/vercel.json`), while externally reachable webhook delivery may use ngrok.

Main entry points: [`backend/config/urls.py`](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/config/urls.py) (HTTP routes), [`backend/payments/webhooks.py`](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/payments/webhooks.py) (Provider webhooks), [`frontend/app/layout.jsx`](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/app/layout.jsx) (App Router pages), [`backend/products/views.py`](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/products/views.py) (Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js Storefront"]
  node_next_app["App Router pages<br/>Next.js UI<br/>[layout.jsx]"]
  node_frontend_guard["Route protection<br/>Next.js middleware<br/>[middleware.js]"]
  node_browser_state["Auth &amp; cart state<br/>Zustand stores<br/>[auth-store.js]"]
  node_api_client["API client &amp; services<br/>frontend API boundary<br/>[api.js]"]
end

subgraph group_backend["Django Backend"]
  node_django_routes["HTTP routes<br/>Django URL config<br/>[urls.py]"]
  node_accounts["Accounts &amp; JWT<br/>Django API domain<br/>[views.py]"]
  node_catalog["Catalog<br/>products API domain<br/>[views.py]"]
  node_categories["Category hierarchy<br/>Django model<br/>[models.py]"]
  node_orders["Orders<br/>Django API domain<br/>[views.py]"]
  node_payments["Payments API<br/>provider-neutral API<br/>[views.py]"]
  node_webhooks["Provider webhooks<br/>Django webhook handler<br/>[webhooks.py]"]
  node_recommendations["Recommendations API<br/>Django API domain<br/>[views.py]"]
end

subgraph group_services["Domain Services"]
  node_order_calculator["Order calculator<br/>pricing service"]
  node_payment_factory["Payment strategy factory<br/>payment service<br/>[factory.py]"]
  node_stripe_adapter["Stripe adapter<br/>payment provider strategy<br/>[stripe.py]"]
  node_bkash_adapter["bKash adapter<br/>payment provider strategy<br/>[bkash.py]"]
  node_stock_manager["Atomic stock fulfillment<br/>inventory service<br/>[stock_manager.py]"]
  node_recommendation_service["Category DFS &amp; cache<br/>recommendation service<br/>[services.py]"]
end

subgraph group_external["Data &amp; Providers"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_redis[("Redis<br/>cache")]
  node_stripe{{"Stripe<br/>payment provider"}}
  node_bkash{{"bKash<br/>payment provider"}}
end

node_next_app -->|"protected routes"| node_frontend_guard
node_next_app -->|"reads and updates"| node_browser_state
node_next_app -->|"API requests"| node_api_client
node_api_client -->|"HTTPS"| node_django_routes
node_django_routes -->|"auth endpoints"| node_accounts
node_django_routes -->|"catalog endpoints"| node_catalog
node_django_routes -->|"order endpoints"| node_orders
node_django_routes -->|"checkout endpoints"| node_payments
node_django_routes -->|"provider callbacks"| node_webhooks
node_django_routes -->|"recommendation endpoints"| node_recommendations
node_catalog -->|"uses hierarchy"| node_categories
node_accounts -->|"users"| node_postgres
node_catalog -->|"products"| node_postgres
node_orders -->|"server-side totals"| node_order_calculator
node_orders -->|"orders and snapshots"| node_postgres
node_payments -->|"selects provider"| node_payment_factory
node_payment_factory -->|"Stripe strategy"| node_stripe_adapter
node_payment_factory -->|"bKash strategy"| node_bkash_adapter
node_stripe_adapter -->|"create/confirm payment"| node_stripe
node_bkash_adapter -->|"create redirect checkout"| node_bkash
node_stripe -->|"signed events"| node_webhooks
node_bkash -->|"callbacks"| node_webhooks
node_webhooks -->|"successful payment"| node_stock_manager
node_stock_manager -->|"row-locked inventory update"| node_postgres
node_recommendations -->|"compute results"| node_recommendation_service
node_recommendation_service -->|"DFS traversal"| node_categories
node_recommendation_service -->|"cache results"| node_redis

click node_next_app "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/app/layout.jsx"
click node_frontend_guard "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/middleware.js"
click node_browser_state "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/store/auth-store.js"
click node_api_client "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/lib/api.js"
click node_django_routes "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/config/urls.py"
click node_accounts "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/accounts/views.py"
click node_catalog "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/products/views.py"
click node_categories "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/categories/models.py"
click node_orders "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/orders/views.py"
click node_payments "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/payments/views.py"
click node_webhooks "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/payments/webhooks.py"
click node_recommendations "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/recommendations/views.py"
click node_order_calculator "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/order/order_calculator.py"
click node_payment_factory "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/factory.py"
click node_stripe_adapter "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/stripe.py"
click node_bkash_adapter "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/bkash.py"
click node_stock_manager "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/stock/stock_manager.py"
click node_recommendation_service "https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/recommendations/services.py"

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_next_app,node_frontend_guard,node_browser_state,node_api_client toneBlue
class node_django_routes,node_accounts,node_catalog,node_categories,node_orders,node_payments,node_webhooks,node_recommendations toneAmber
class node_order_calculator,node_payment_factory,node_stripe_adapter,node_bkash_adapter,node_stock_manager,node_recommendation_service toneMint
class node_postgres,node_redis,node_stripe,node_bkash toneRose
```

## Components

### Next.js Storefront

- [App Router pages](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/app/layout.jsx): Next.js UI · Catalog, cart, checkout, history, and admin pages. · `frontend/app/layout.jsx`
- [Route protection](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/middleware.js): Next.js middleware · `frontend/middleware.js`
- [Auth & cart state](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/store/auth-store.js): Zustand stores · `frontend/store/auth-store.js`
- [API client & services](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/frontend/lib/api.js): frontend API boundary · `frontend/lib/api.js`

### Django Backend

- [HTTP routes](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/config/urls.py): Django URL config · `backend/config/urls.py`
- [Accounts & JWT](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/accounts/views.py): Django API domain · Custom-user authentication API. · `backend/accounts/views.py`
- [Catalog](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/products/views.py): products API domain · Product CRUD, filtering, and pagination. · `backend/products/views.py`
- [Category hierarchy](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/categories/models.py): Django model · `backend/categories/models.py`
- [Orders](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/orders/views.py): Django API domain · Persists orders and price-snapshotted items. · `backend/orders/views.py`
- [Payments API](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/payments/views.py): provider-neutral API · `backend/payments/views.py`
- [Provider webhooks](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/payments/webhooks.py): Django webhook handler · Validates notifications and advances payment lifecycle. · `backend/payments/webhooks.py`
- [Recommendations API](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/recommendations/views.py): Django API domain · `backend/recommendations/views.py`

### Domain Services

- [Order calculator](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/order/order_calculator.py): pricing service · Uses deterministic Decimal rounding for server totals. · `backend/services/order/order_calculator.py`
- [Payment strategy factory](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/factory.py): payment service · `backend/services/payment/factory.py`
- [Stripe adapter](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/stripe.py): payment provider strategy · `backend/services/payment/stripe.py`
- [bKash adapter](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/payment/bkash.py): payment provider strategy · `backend/services/payment/bkash.py`
- [Atomic stock fulfillment](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/services/stock/stock_manager.py): inventory service · Row-locked, exactly-once stock reduction. · `backend/services/stock/stock_manager.py`
- [Category DFS & cache](https://github.com/fahadbinsiddique/e-commerce-ordering-payment-system/blob/main/backend/recommendations/services.py): recommendation service · `backend/recommendations/services.py`

### Data & Providers

- **PostgreSQL**: relational database · Production system of record.
- **Redis**: cache · Recommendation cache.
- **Stripe**: payment provider · SDK and signed webhook integration.
- **bKash**: payment provider · Tokenized checkout and callback integration.

## Connections

- App Router pages → Route protection: protected routes
- App Router pages → Auth & cart state: reads and updates
- App Router pages → API client & services: API requests
- API client & services → HTTP routes: HTTPS
- HTTP routes → Accounts & JWT: auth endpoints
- HTTP routes → Catalog: catalog endpoints
- HTTP routes → Orders: order endpoints
- HTTP routes → Payments API: checkout endpoints
- HTTP routes → Provider webhooks: provider callbacks
- HTTP routes → Recommendations API: recommendation endpoints
- Catalog → Category hierarchy: uses hierarchy
- Accounts & JWT → PostgreSQL: users
- Catalog → PostgreSQL: products
- Orders → Order calculator: server-side totals
- Orders → PostgreSQL: orders and snapshots
- Payments API → Payment strategy factory: selects provider
- Payment strategy factory → Stripe adapter: Stripe strategy
- Payment strategy factory → bKash adapter: bKash strategy
- Stripe adapter → Stripe: create/confirm payment
- bKash adapter → bKash: create redirect checkout
- Stripe → Provider webhooks: signed events
- bKash → Provider webhooks: callbacks
- Provider webhooks → Atomic stock fulfillment: successful payment
- Atomic stock fulfillment → PostgreSQL: row-locked inventory update
- Recommendations API → Category DFS & cache: compute results
- Category DFS & cache → Category hierarchy: DFS traversal
- Category DFS & cache → Redis: cache results