# luis-git-ac/ecommerce-web architecture

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

- Interactive diagram: https://gitdiagram.com/luis-git-ac/ecommerce-web
- Repository: https://github.com/luis-git-ac/ecommerce-web

## Overview

1. **Repository shape**
   - This is a two-app monorepo: `frontend/` is a React SPA, `backend/` is an Express/TypeScript REST API.
   - They are intentionally decoupled and communicate over HTTP via typed “repository” clients on the frontend and route/controller/service layers on the backend.

2. **High-level request flow**
   - User interaction starts in the React app.
   - Frontend pages/components call API wrappers in `src/services/*`.
   - The backend validates/authenticates the request, applies business logic in module services, persists or reads from MongoDB, and may call external services like Stripe or Cloudinary.
   - Some flows return data immediately; others complete asynchronously via webhooks, especially payments.

3. **Backend runtime and core infrastructure**
   - The backend is Node.js + Express + TypeScript.
   - Cross-cutting setup lives in `src/app.ts`, `src/server.ts`, `src/config/*`, and `src/middlewares/*`.
   - Common infrastructure includes environment configuration, database connection, logging, error normalization, rate limiting, and auth middleware.
   - The backend is organized around REST routes, with each module owning its own controller/service/data model boundaries.

4. **Backend domain modules**
   - The main business domains are `auth`, `products`, `cart`, `orders`, `payments`, `content`, and `admin`.
   - Each module typically has routes, controllers, DTOs, services, and in many cases MongoDB schemas or repositories.
   - `products` includes a repository abstraction and a `product-image-delivery` service, indicating product media is handled as a distinct concern.
   - `content` stores non-commerce data such as blog posts, contact messages, newsletter subscribers, and club leads.

5. **Persistence and data model**
   - MongoDB is the primary application datastore, with Mongoose-style schemas under each module.
   - The data model is split by domain: users, products, carts, orders, and content collections are isolated in their own schema files.
   - This separation supports independent querying and keeps the service layer focused on domain logic rather than shared tables/collections.
   - `backend/src/modules/media` appears to be reserved for media-related repository/service work, but the current implementation is minimal.

6. **Authentication and authorization**
   - Auth is JWT-based, with a user schema, auth controller/service, and a token service.
   - The auth middleware protects private routes, while admin-specific endpoints are separated into the `admin` module.
   - This suggests a layered access model: public catalog/content endpoints, authenticated user endpoints, and privileged admin operations.

7. **Payments and order lifecycle**
   - Payments are integrated with Stripe in test mode, and the backend owns the payment creation/checkout logic.
   - The payment module has a dedicated controller/service and separate routes, which keeps checkout logic out of the orders module.
   - Webhook handling is covered by integration tests, indicating the order state is updated asynchronously after Stripe events are received.
   - In practice, the payment flow likely creates a checkout session, redirects the user externally, then reconciles order status through webhook callbacks.

8. **External services and media**
   - Cloudinary is used for image hosting/delivery, mainly around product media.
   - The backend includes scripts for inventorying, uploading, and reporting IA/product images, which means media operations are part of the operational architecture, not just runtime serving.
   - Stripe and Cloudinary are the two major external SaaS dependencies that materially affect the system’s architecture.

9. **Frontend application structure**
   - The frontend is a Vite-built React application with page-based routing and modular UI composition.
   - `src/pages/*` contains route-level screens, `src/components/*` contains reusable layout/section/UI pieces, and `src/features/*` holds feature-specific logic like product fetching.
   - Global state is handled with React contexts for auth and cart, which centralizes session and shopping-state behavior across pages.
   - The app is structured for a content-heavy storefront: home, shop, product detail, cart, checkout, blog, account, admin, legal, and support pages.

10. **Frontend data access and state boundaries**
   - API access is abstracted through repository-style clients in `src/services/*` rather than direct fetch calls scattered through components.
   - `useProducts` and related feature hooks indicate data-fetching logic is separated from presentation.
   - There are also local mocks for blog and products, which suggests the frontend can be developed and tested without depending on a live backend for every workflow.

11. **Testing and quality gates**
   - Backend tests are primarily integration-oriented: auth, cart/orders, payments webhook, product queries, and system behavior.
   - Frontend uses component tests plus Playwright end-to-end coverage for the shop flow.
   - This test split mirrors the architecture: backend validates domain and integration boundaries, frontend validates user journeys and UI behavior.

12. **Operational scripts**
   - The backend scripts folder contains seeders, smoke tests, demo resets, and media upload utilities, supporting reproducible environments and demo readiness.
   - The frontend scripts focus on image optimization and bundle/budget reporting, which reflects a performance-conscious SPA deployment model.
   - These scripts are important to the repo’s operational architecture because they prepare data, validate flows, and manage asset quality outside normal runtime paths.

13. **Important boundaries to capture in a diagram**
   - Frontend UI boundary: pages/components/hooks/contexts.
   - API boundary: Express routes/controllers/services.
   - Domain boundary: auth, products, cart, orders, payments, content, admin.
   - External boundary: MongoDB Atlas, Stripe, Cloudinary.
   - Asynchronous boundary: Stripe webhooks updating order/payment state after checkout completes.

14. **Overall architectural picture**
   - The system is a conventional but well-separated commerce platform: a React storefront consuming a domain-modular REST backend.
   - Core commerce state lives on the backend; the frontend is primarily a presentation and interaction layer with local UI state for auth/cart.
   - The hardest coupling points are payments and media, both of which are externalized to Stripe and Cloudinary and then reconciled back into MongoDB through backend services.

Main entry points: [`backend/src/routes/system.routes.ts`](https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/routes/system.routes.ts) (System routes), [`frontend/src/pages`](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/pages) (Pages), [`backend/src/app.ts`](https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/app.ts) (App setup), [`backend/src/modules/products`](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/products) (Products module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_app["App shell<br/>React/Vite SPA<br/>[App.tsx]"]
  node_frontend_pages["Pages<br/>route screens"]
  node_frontend_components["UI components<br/>presentational UI"]
  node_frontend_features["Feature hooks<br/>data hooks"]
  node_frontend_state{{"App state<br/>React contexts"}}
  node_frontend_services["API clients<br/>repository clients"]
end

subgraph group_backend["Backend API"]
  node_backend_server["Server bootstrap<br/>Node/Express entrypoint<br/>[server.ts]"]
  node_backend_app["App setup<br/>Express config<br/>[app.ts]"]
  node_backend_config["Config core<br/>infra config"]
  node_backend_common["Common middleware<br/>cross-cutting"]
  node_backend_routes["System routes<br/>route assembly<br/>[system.routes.ts]"]
  node_backend_auth["Auth module<br/>JWT auth"]
  node_backend_products["Products module<br/>catalog domain"]
  node_backend_cart["Cart module<br/>cart domain"]
  node_backend_orders["Orders module<br/>order domain"]
  node_backend_payments["Payments module<br/>Stripe checkout"]
  node_backend_content["Content module<br/>CMS-like domain"]
  node_backend_admin["Admin module<br/>privileged ops"]
end

subgraph group_external["External services"]
  node_backend_mongo[("MongoDB<br/>primary datastore")]
  node_stripe(("Stripe<br/>payments SaaS"))
  node_cloudinary(("Cloudinary<br/>media SaaS"))
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_pages -->|"composes"| node_frontend_components
node_frontend_pages -->|"uses"| node_frontend_features
node_frontend_pages -->|"reads/writes"| node_frontend_state
node_frontend_features -->|"calls"| node_frontend_services
node_frontend_services -->|"HTTP"| node_backend_routes
node_backend_server -->|"boots"| node_backend_app
node_backend_app -->|"loads"| node_backend_config
node_backend_app -->|"applies"| node_backend_common
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"exposes"| node_backend_auth
node_backend_routes -->|"exposes"| node_backend_products
node_backend_routes -->|"exposes"| node_backend_cart
node_backend_routes -->|"exposes"| node_backend_orders
node_backend_routes -->|"exposes"| node_backend_payments
node_backend_routes -->|"exposes"| node_backend_content
node_backend_routes -->|"exposes"| node_backend_admin
node_backend_auth -->|"reads/writes"| node_backend_mongo
node_backend_products -->|"reads/writes"| node_backend_mongo
node_backend_products -->|"delivers media"| node_cloudinary
node_backend_cart -->|"reads/writes"| node_backend_mongo
node_backend_orders -->|"reads/writes"| node_backend_mongo
node_backend_payments -->|"checkout/webhooks"| node_stripe
node_backend_payments -->|"updates"| node_backend_orders
node_backend_content -->|"reads/writes"| node_backend_mongo
node_backend_admin -->|"reads/writes"| node_backend_mongo

click node_frontend_app "https://github.com/luis-git-ac/ecommerce-web/blob/main/frontend/src/App.tsx"
click node_frontend_pages "https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/components"
click node_frontend_features "https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/features"
click node_frontend_state "https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/store"
click node_frontend_services "https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/services"
click node_backend_server "https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/server.ts"
click node_backend_app "https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/app.ts"
click node_backend_config "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/config"
click node_backend_common "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/common"
click node_backend_routes "https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/routes/system.routes.ts"
click node_backend_auth "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/auth"
click node_backend_products "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/products"
click node_backend_cart "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/cart"
click node_backend_orders "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/orders"
click node_backend_payments "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/payments"
click node_backend_content "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/content"
click node_backend_admin "https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/admin"

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_frontend_app,node_frontend_pages,node_frontend_components,node_frontend_features,node_frontend_state,node_frontend_services toneBlue
class node_backend_server,node_backend_app,node_backend_config,node_backend_common,node_backend_routes,node_backend_auth,node_backend_products,node_backend_cart,node_backend_orders,node_backend_payments,node_backend_content,node_backend_admin toneAmber
class node_backend_mongo,node_stripe,node_cloudinary toneMint
```

## Components

### Frontend SPA

React storefront and user-facing application layer

- [App shell](https://github.com/luis-git-ac/ecommerce-web/blob/main/frontend/src/App.tsx): React/Vite SPA · Entry shell and client-side routing · `frontend/src/App.tsx`
- [Pages](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/pages): route screens · Route-level storefront and account screens · `frontend/src/pages`
- [UI components](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/components): presentational UI · Reusable layout, section, and widget components · `frontend/src/components`
- [Feature hooks](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/features): data hooks · Feature-specific client logic such as product fetching · `frontend/src/features`
- [App state](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/store): React contexts · Shared auth and cart state across the SPA · `frontend/src/store`
- [API clients](https://github.com/luis-git-ac/ecommerce-web/tree/main/frontend/src/services): repository clients · Typed HTTP wrappers for backend modules · `frontend/src/services`

### Backend API

Express/TypeScript REST API and domain modules

- [Server bootstrap](https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/server.ts): Node/Express entrypoint · App wiring, server startup, and route registration · `backend/src/server.ts`
- [App setup](https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/app.ts): Express config · Express app composition and middleware setup · `backend/src/app.ts`
- [Config core](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/config): infra config · Environment, database, cloud, and logging setup · `backend/src/config`
- [Common middleware](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/common): cross-cutting · Auth, rate limiting, and shared HTTP errors · `backend/src/common`
- [System routes](https://github.com/luis-git-ac/ecommerce-web/blob/main/backend/src/routes/system.routes.ts): route assembly · Top-level non-domain route composition · `backend/src/routes/system.routes.ts`
- [Auth module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/auth): JWT auth · Login, token issuance, and protected user identity · `backend/src/modules/auth`
- [Products module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/products): catalog domain · Product queries, repository, and image delivery · `backend/src/modules/products`
- [Cart module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/cart): cart domain · Shopping cart persistence and business logic · `backend/src/modules/cart`
- [Orders module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/orders): order domain · Order creation and lifecycle state · `backend/src/modules/orders`
- [Payments module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/payments): Stripe checkout · Payment session creation and webhook reconciliation · `backend/src/modules/payments`
- [Content module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/content): CMS-like domain · Blog, contact, newsletter, and club lead data · `backend/src/modules/content`
- [Admin module](https://github.com/luis-git-ac/ecommerce-web/tree/main/backend/src/modules/admin): privileged ops · Admin-only operations and controls · `backend/src/modules/admin`

### External services

Third-party systems and persisted infrastructure

- **MongoDB**: primary datastore · Domain collections and persistence layer
- **Stripe**: payments SaaS · External checkout and webhook provider
- **Cloudinary**: media SaaS · Product image hosting and delivery

## Connections

- App shell → Pages: renders · App shell routes users into page-level screens
- Pages → UI components: composes · Pages assemble shared layout and section components
- Pages → Feature hooks: uses · Pages pull data through feature hooks
- Pages → App state: reads/writes · Pages share auth and cart state through contexts
- Feature hooks → API clients: calls · Feature hooks fetch via typed repository clients
- API clients → System routes: HTTP · Frontend clients call the REST API boundary
- Server bootstrap → App setup: boots · Server starts the configured Express application
- App setup → Config core: loads · Application wiring depends on environment and infrastructure config
- App setup → Common middleware: applies · Cross-cutting middleware is mounted on the app
- App setup → System routes: mounts · Top-level route assembly is registered on Express
- System routes → Auth module: exposes · Auth endpoints handle login and token flows
- System routes → Products module: exposes · Catalog routes serve product discovery and media logic
- System routes → Cart module: exposes · Cart routes manage shopping-session state
- System routes → Orders module: exposes · Order routes manage purchase records and status
- System routes → Payments module: exposes · Payment routes create checkout and receive callbacks
- System routes → Content module: exposes · Content routes serve blog and lead-capture flows
- System routes → Admin module: exposes · Admin routes isolate privileged operations
- Auth module → MongoDB: reads/writes · User identity and tokens are backed by MongoDB
- Products module → MongoDB: reads/writes · Product catalog data is stored in MongoDB
- Products module → Cloudinary: delivers media · Product media is hosted and served via Cloudinary
- Cart module → MongoDB: reads/writes · Cart state persists in MongoDB
- Orders module → MongoDB: reads/writes · Order records and lifecycle state persist in MongoDB
- Payments module → Stripe: checkout/webhooks · Stripe handles payment sessions and async webhook events
- Payments module → Orders module: updates · Payment outcomes reconcile order state
- Content module → MongoDB: reads/writes · Content and lead data are stored in MongoDB
- Admin module → MongoDB: reads/writes · Admin operations act on persisted domain data
