How luis-git-ac/ecommerce-web works
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: system.routes.ts System routes · pages Pages · app.ts App setup · products Products module
Components 21
Frontend SPA
React storefront and user-facing application layer
- App shell · Entry shell and client-side routing
frontend/src/App.tsx - Pages · Route-level storefront and account screens
frontend/src/pages - UI components · Reusable layout, section, and widget components
frontend/src/components - Feature hooks · Feature-specific client logic such as product fetching
frontend/src/features - App state · Shared auth and cart state across the SPA
frontend/src/store - API clients · Typed HTTP wrappers for backend modules
frontend/src/services
Backend API
Express/TypeScript REST API and domain modules
- Server bootstrap · App wiring, server startup, and route registration
backend/src/server.ts - App setup · Express app composition and middleware setup
backend/src/app.ts - Config core · Environment, database, cloud, and logging setup
backend/src/config - Common middleware · Auth, rate limiting, and shared HTTP errors
backend/src/common - System routes · Top-level non-domain route composition
backend/src/routes/system.routes.ts - Auth module · Login, token issuance, and protected user identity
backend/src/modules/auth - Products module · Product queries, repository, and image delivery
backend/src/modules/products - Cart module · Shopping cart persistence and business logic
backend/src/modules/cart - Orders module · Order creation and lifecycle state
backend/src/modules/orders - Payments module · Payment session creation and webhook reconciliation
backend/src/modules/payments - Content module · Blog, contact, newsletter, and club lead data
backend/src/modules/content - Admin module · Admin-only operations and controls
backend/src/modules/admin
External services
Third-party systems and persisted infrastructure
- MongoDB · Domain collections and persistence layer
- Stripe · External checkout and webhook provider
- Cloudinary · Product image hosting and delivery
Connections 26
- 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