# basir/amazona architecture

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

- Interactive diagram: https://gitdiagram.com/basir/amazona
- Repository: https://github.com/basir/amazona

## Overview

#### Purpose and deployment shape
Amazona is a MERN marketplace/e-commerce system: product discovery, cart and checkout, PayPal payment, fulfillment, reviews, seller/admin operations, mapping, email receipts, and live support. The root Node process is the production entry point (`package.json`, `Procfile`); its API server also serves the built React application. Local development runs the API and React dev server separately.

#### Backend composition
`backend/server.js` initializes Express, environment/database connectivity, API routing, static upload/build serving, and realtime support infrastructure. Domain endpoints are partitioned by resource:
- Products, search/filtering, reviews, seller catalog: `backend/routers/productRouter.js`, `backend/models/productModel.js`
- Identity, registration, profiles, role management, seeds: `backend/routers/userRouter.js`, `backend/models/userModel.js`
- Checkout lifecycle, payment, delivery, reporting: `backend/routers/orderRouter.js`, `backend/models/orderModel.js`
- Multipart image ingestion into the local upload boundary: `backend/routers/uploadRouter.js`, `uploads`

#### Persistence, authorization, and integrations
MongoDB/Mongoose is the durable system of record, with schemas for users, products, and orders in `backend/models/`. Seed data originates in `backend/data.js`. JWT creation and authentication/role middleware are centralized in `backend/utils.js`; routers enforce customer, seller, and admin boundaries. Runtime configuration supplies MongoDB and third-party credentials. Material external services are MongoDB/Atlas, PayPal (client ID and checkout/payment flow), Google Maps, Mailgun order-email delivery, and Socket.IO-based chat. Heroku is the documented deployment target.

#### React application shell and navigation
`frontend/src/index.js` mounts the Redux-backed React application; `frontend/src/App.js` defines the route-level application shell and screens. Route guards separate authenticated, administrator, and seller capabilities through `frontend/src/components/PrivateRoute.js`, `frontend/src/components/AdminRoute.js`, and `frontend/src/components/SellerRoute.js`. Major user journeys are represented by screen modules such as catalog/product views, checkout/order views, profile/history, support, and administrative dashboards under `frontend/src/screens/`.

#### Client state and API orchestration
Redux is the client-side control plane: `frontend/src/store.js` combines domain reducers; async API calls live in `frontend/src/actions/`; request lifecycle and persisted user/cart/checkout state are represented in `frontend/src/reducers/` and `frontend/src/constants/`. Product browsing flows from screens through `productActions.js` to product APIs and back into product reducers. Equivalent action/reducer pipelines handle authentication, cart/shipping/payment, and orders (`frontend/src/actions/cartActions.js`, `frontend/src/actions/orderActions.js`, `frontend/src/actions/userActions.js`).

#### Primary business flow
Catalog/search screens load paginated, filtered products; product detail adds seller-constrained items to the cart. Checkout captures shipping and payment selections, then creates an order via the order API. The order screen loads PayPal configuration, completes payment, and refreshes payment/delivery state. Backend payment completion persists order changes and can send a Mailgun receipt. Customers then inspect history/profile; sellers manage their products/orders; admins manage users, products, orders, and dashboard data.

#### Realtime and client integration boundaries
The client communicates with the API via action-layer HTTP calls and carries JWT credentials for protected operations. `frontend/src/components/ChatBox.js` and `frontend/src/screens/SupportScreen.js` form the customer/support realtime surface backed by Socket.IO initialized from `backend/server.js`. Mapping is isolated to `frontend/src/screens/MapScreen.js` and checkout address capture, while product image upload crosses from product-edit UI to `backend/routers/uploadRouter.js` and the `uploads` filesystem.

Main entry points: [`backend/server.js`](https://github.com/basir/amazona/blob/master/backend/server.js) (Express server), [`backend/routers/orderRouter.js`](https://github.com/basir/amazona/blob/master/backend/routers/orderRouter.js) (Order API), [`backend/utils.js`](https://github.com/basir/amazona/blob/master/backend/utils.js) (JWT auth & roles), [`frontend/src/App.js`](https://github.com/basir/amazona/blob/master/frontend/src/App.js) (App routes & screens)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_react_bootstrap["React bootstrap<br/>React entry<br/>[index.js]"]
  node_app_shell["App routes &amp; screens<br/>React shell<br/>[App.js]"]
  node_route_guards["Capability route guards<br/>React guards<br/>[PrivateRoute.js]"]
  node_redux_store["Redux state<br/>Redux store<br/>[store.js]"]
  node_api_actions["API action layer<br/>Redux async actions<br/>[productActions.js]"]
  node_chat_support["Support chat<br/>React realtime UI<br/>[ChatBox.js]"]
  node_map_checkout["Address mapping<br/>React map screen<br/>[MapScreen.js]"]
end

subgraph group_api["Node API"]
  node_node_server["Express server<br/>Node entry point<br/>[server.js]"]
  node_auth_policy["JWT auth &amp; roles<br/>Express middleware<br/>[utils.js]"]
  node_product_api["Product API<br/>Express router<br/>[productRouter.js]"]
  node_user_api["User API<br/>Express router<br/>[userRouter.js]"]
  node_order_api["Order API<br/>Express router<br/>[orderRouter.js]"]
  node_upload_api["Image upload API<br/>Express router<br/>[uploadRouter.js]"]
end

subgraph group_data["Data &amp; integrations"]
  node_mongo_models[("Mongoose domain models<br/>Mongo schemas")]
  node_uploads["Uploaded images<br/>local filesystem"]
  node_mongodb[("MongoDB / Atlas<br/>external database")]
  node_paypal["PayPal<br/>payment service"]
  node_mailgun["Mailgun<br/>email service"]
  node_socketio["Socket.IO<br/>realtime transport"]
  node_google_maps["Google Maps<br/>mapping service"]
end

node_react_bootstrap -->|"mounts"| node_app_shell
node_react_bootstrap -->|"provides store"| node_redux_store
node_app_shell -->|"protects routes"| node_route_guards
node_app_shell -->|"dispatches"| node_api_actions
node_api_actions -->|"updates state"| node_redux_store
node_api_actions -->|"HTTP + JWT"| node_node_server
node_chat_support -->|"realtime messages"| node_socketio
node_map_checkout -->|"maps"| node_google_maps
node_node_server -->|"applies"| node_auth_policy
node_node_server -->|"routes"| node_product_api
node_node_server -->|"routes"| node_user_api
node_node_server -->|"routes"| node_order_api
node_node_server -->|"routes"| node_upload_api
node_node_server -->|"hosts"| node_socketio
node_auth_policy -.->|"authorizes"| node_product_api
node_auth_policy -.->|"authorizes"| node_user_api
node_auth_policy -.->|"authorizes"| node_order_api
node_product_api -->|"uses products"| node_mongo_models
node_user_api -->|"uses users"| node_mongo_models
node_order_api -->|"uses orders"| node_mongo_models
node_mongo_models -->|"persists"| node_mongodb
node_upload_api -->|"stores images"| node_uploads
node_order_api -->|"processes payment"| node_paypal
node_order_api -->|"sends receipts"| node_mailgun

click node_react_bootstrap "https://github.com/basir/amazona/blob/master/frontend/src/index.js"
click node_app_shell "https://github.com/basir/amazona/blob/master/frontend/src/App.js"
click node_route_guards "https://github.com/basir/amazona/blob/master/frontend/src/components/PrivateRoute.js"
click node_redux_store "https://github.com/basir/amazona/blob/master/frontend/src/store.js"
click node_api_actions "https://github.com/basir/amazona/blob/master/frontend/src/actions/productActions.js"
click node_chat_support "https://github.com/basir/amazona/blob/master/frontend/src/components/ChatBox.js"
click node_map_checkout "https://github.com/basir/amazona/blob/master/frontend/src/screens/MapScreen.js"
click node_node_server "https://github.com/basir/amazona/blob/master/backend/server.js"
click node_auth_policy "https://github.com/basir/amazona/blob/master/backend/utils.js"
click node_product_api "https://github.com/basir/amazona/blob/master/backend/routers/productRouter.js"
click node_user_api "https://github.com/basir/amazona/blob/master/backend/routers/userRouter.js"
click node_order_api "https://github.com/basir/amazona/blob/master/backend/routers/orderRouter.js"
click node_upload_api "https://github.com/basir/amazona/blob/master/backend/routers/uploadRouter.js"
click node_uploads "https://github.com/basir/amazona/tree/master/uploads"

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_react_bootstrap,node_app_shell,node_route_guards,node_redux_store,node_api_actions,node_chat_support,node_map_checkout toneBlue
class node_node_server,node_auth_policy,node_product_api,node_user_api,node_order_api,node_upload_api toneAmber
class node_mongo_models,node_uploads,node_mongodb,node_paypal,node_mailgun,node_socketio,node_google_maps toneMint
```

## Components

### React client

- [React bootstrap](https://github.com/basir/amazona/blob/master/frontend/src/index.js): React entry · Mounts the Redux-backed application. · `frontend/src/index.js`
- [App routes & screens](https://github.com/basir/amazona/blob/master/frontend/src/App.js): React shell · Hosts catalog, checkout, account, seller, and admin journeys. · `frontend/src/App.js`
- [Capability route guards](https://github.com/basir/amazona/blob/master/frontend/src/components/PrivateRoute.js): React guards · Separates authenticated, admin, and seller routes. · `frontend/src/components/PrivateRoute.js`
- [Redux state](https://github.com/basir/amazona/blob/master/frontend/src/store.js): Redux store · Combines persisted user, cart, checkout, and request state. · `frontend/src/store.js`
- [API action layer](https://github.com/basir/amazona/blob/master/frontend/src/actions/productActions.js): Redux async actions · Orchestrates product, cart, order, and user API calls. · `frontend/src/actions/productActions.js`
- [Support chat](https://github.com/basir/amazona/blob/master/frontend/src/components/ChatBox.js): React realtime UI · Customer and support chat surface. · `frontend/src/components/ChatBox.js`
- [Address mapping](https://github.com/basir/amazona/blob/master/frontend/src/screens/MapScreen.js): React map screen · Map and checkout address capture boundary. · `frontend/src/screens/MapScreen.js`

### Node API

- [Express server](https://github.com/basir/amazona/blob/master/backend/server.js): Node entry point · Initializes APIs, static React serving, uploads, and Socket.IO. · `backend/server.js`
- [JWT auth & roles](https://github.com/basir/amazona/blob/master/backend/utils.js): Express middleware · Centralizes token creation and customer, seller, admin authorization. · `backend/utils.js`
- [Product API](https://github.com/basir/amazona/blob/master/backend/routers/productRouter.js): Express router · Catalog, search, reviews, and seller catalog operations. · `backend/routers/productRouter.js`
- [User API](https://github.com/basir/amazona/blob/master/backend/routers/userRouter.js): Express router · Registration, profiles, roles, and seed operations. · `backend/routers/userRouter.js`
- [Order API](https://github.com/basir/amazona/blob/master/backend/routers/orderRouter.js): Express router · Checkout, payment, delivery, and reporting lifecycle. · `backend/routers/orderRouter.js`
- [Image upload API](https://github.com/basir/amazona/blob/master/backend/routers/uploadRouter.js): Express router · Multipart image ingestion boundary. · `backend/routers/uploadRouter.js`

### Data & integrations

- **Mongoose domain models**: Mongo schemas · Users, products, and orders are the durable domain record.
- [Uploaded images](https://github.com/basir/amazona/tree/master/uploads): local filesystem · `uploads`
- **MongoDB / Atlas**: external database · Production durable datastore.
- **PayPal**: payment service · Checkout configuration and payment completion.
- **Mailgun**: email service · Order receipt delivery.
- **Socket.IO**: realtime transport · Live support messaging transport.
- **Google Maps**: mapping service

## Connections

- React bootstrap → App routes & screens: mounts
- React bootstrap → Redux state: provides store
- App routes & screens → Capability route guards: protects routes
- App routes & screens → API action layer: dispatches
- API action layer → Redux state: updates state
- API action layer → Express server: HTTP + JWT
- Support chat → Socket.IO: realtime messages
- Address mapping → Google Maps: maps
- Express server → JWT auth & roles: applies
- Express server → Product API: routes
- Express server → User API: routes
- Express server → Order API: routes
- Express server → Image upload API: routes
- Express server → Socket.IO: hosts
- JWT auth & roles → Product API: authorizes
- JWT auth & roles → User API: authorizes
- JWT auth & roles → Order API: authorizes
- Product API → Mongoose domain models: uses products
- User API → Mongoose domain models: uses users
- Order API → Mongoose domain models: uses orders
- Mongoose domain models → MongoDB / Atlas: persists
- Image upload API → Uploaded images: stores images
- Order API → PayPal: processes payment
- Order API → Mailgun: sends receipts