1. Overall Architecture
2. Technologies Overview
3. Platform Highlights
4. TypeScript Across the Stack
5. Backend
6. Frontend
7. Admin Panel
8. Shared Packages
9. Architecture Principles
10. Docker & Development Environment
11. Codebase Overview
12. Production Readiness
13. Git Pre-commit Checks with Husky
14. Continuous Integration (CI)

This section provides a comprehensive overview of the wexCommerce platform architecture, covering:

• Backend (Backend server)
• Frontend (Customer Web App)
• Admin Panel (Admin Dashboard)

• Secure Authentication: JWT-based auth ensures secure and stateless login flows for all users (customers, admins).
• Payment Integration: Seamless payments with support for both Stripe and PayPal, including web flow.
• Internationalization (i18n): Multi-language support is built-in using a shared translation structure for consistency across all platforms.
• Live Availability and Scheduling: Real-time product availability, pricing, and conflict-free checkout logic.
• Reusable Components: A large collection of shared UI components across frontend and admin apps to ensure consistent UX and reduce duplication.
• Docker-based workflow: All apps are containerized using Docker, allowing consistent development and production environments across teams and deployments.

This architecture empowers developers to scale the product efficiently, onboard new features with confidence, and deliver a seamless experience to both end users and administrators.

All core components of wexCommerce are written in TypeScript, including backend APIs and web apps. Shared types and interfaces live in a centralized package to maintain consistency between the different apps.

• Shared types are defined in: ./packages/wexcommerce-types
• Ensures consistent request/response models across all clients

The wexCommerce Backend is a modular, scalable REST API built using Node.js, Express, and MongoDB, following the Model-View-Controller (MVC) architectural pattern. It serves as the central data and business logic layer for all platform clients, including the customer-facing frontend web app, and the admin panel.

This unified API architecture ensures consistent data handling, centralized security, and maintainable code across the ecosystem. The backend is designed to be:

• Modular: Clean folder structure and reusable components (controllers, models, middlewares)
• Extensible: Easy to add new features, such as additional payment providers or modules
• Secure: JWT-based authentication, middleware-based authorization, and robust request validation
• Scalable: Supports high concurrency and real-time updates with efficient MongoDB queries and indexing

In addition to core CRUD operations, the backend also handles:

• User authentication and authorization
• Payment processing via Stripe and PayPal
• Booking availability and scheduling
• Location-based search and filtering
• Push notification triggers
• Multi-language support through dynamic i18n content

The backend also includes setup scripts for data seeding, environment configuration, and test coverage to streamline development, testing, and deployment.

• Uses JWT for user authentication (access & refresh tokens)
• Public and private routes protected via middleware
• Input validation, sanitization, and error handling via middlewares

• src/app.ts: Express app creation, middleware registration
• src/index.ts: Entry point and server bootstrap
• src/monitoring/instrument.ts: Sentry integration and initialization
• src/payment/stripe.ts: Stripe integration (checkout, webhooks)
• src/payment/paypal.ts: PayPal integration

/backend
├── src/
│   ├── config/           # Environment configs
│   ├── controllers/      # Business logic
│   ├── lang/             # i18n translations
│   ├── middlewares/      # Auth, error handling, etc.
│   ├── models/           # Mongoose models
│   ├── monitoring/       # Sentry setup
│   ├── payment/          # Stripe, PayPal, and payment integration handlers
│   ├── routes/           # Express route handlers
│   ├── setup/            # Setup and reset scripts
│   ├── utils/            # Common utilities
│   ├── app.ts            # App instance
│   └── index.ts          # API bootstrap
├── __tests__/            # Jest integration tests

The Frontend Web App is built with Next.js and MUI, offering a smooth shopping experience for customers.

• Live search (products)
• Real-time availability and pricing
• Secure Stripe & PayPal checkout
• User account management

/frontend
├── src/
│   ├── app/              # Route-level pages
│   ├── components/       # Reusable UI components
│   ├── config/           # Environment configs
│   ├── context/          # React Contexts
│   ├── lib/              # server actions
│   ├── lang/             # localization
│   ├── styles/           # CSS
│   ├── types/            # TypeScript Types
│   ├── utils/            # Common utilities
│   ├── middleware.ts     # Middlewares

The Admin Panel provides management tools for platform admins, also built with Next.js and MUI for fast loading and rich interactions.

• Manage products, users, orders, settings
• View platform-wide orders and stats

/admin
├── src/
│   ├── app/              # Route-level pages
│   ├── components/       # Reusable UI components
│   ├── config/           # Environment configs
│   ├── context/          # React Contexts
│   ├── lib/              # server actions
│   ├── lang/             # localization
│   ├── styles/           # CSS
│   ├── types/            # TypeScript Types
│   ├── utils/            # Common utilities
│   ├── middleware.ts     # Middlewares

wexCommerce uses a monorepo layout with shared packages:

/packages
├── wexcommerce-types/      # Shared TypeScript interfaces and models
├── wexcommerce-helper/     # Common utilities (dates, formatting, etc.)
├── reactjs-social-login/   # Social login utility (Google, Apple, Facebook, etc.)

These packages are used across backend, frontend, and admin panel for consistency.

• Modularity: Each component is cleanly separated and easy to maintain.
• Type-Safety: Powered by TypeScript, with shared types and validation.
• Reusability: Core logic is abstracted into shared packages.
• Internationalization: Supports multiple languages with i18n.
• Security: Enforced via JWT, role-based access, and validation layers.

wexCommerce provides a Docker-first setup to support a smooth and consistent development and deployment experience:

• Backend
  • Uses nodemon inside Docker for automatic server restarts on file changes.
  • Fast feedback loop while writing API logic or working with MongoDB.
• Frontend & Admin Panel
  • Built using Next.js with Hot Module Replacement (HMR) enabled.
  • Mounted as bind volumes in Docker to reflect code changes instantly.
• MongoDB
  • Runs as a container alongside the backend for easy local setup.
  • Runs as a containerized NoSQL database.
  • Exposed for local connection (e.g., on localhost:27018).
• Mongo Express
  • A lightweight web-based MongoDB admin UI.
  • Accessible at http://localhost:8084.
  • Lets developers browse collections, documents, and manage data easily.

Docker Compose manages all services in development mode using a docker-compose.dev.yml file.

docker compose -f docker-compose.dev.yml up

For more information, checkout Docker documentation for development.

• Optimized Dockerfiles for each component (backend, frontend, admin panel).
• Production builds are minified and served using lightweight Node or static servers (e.g., nginx for frontend).
• Environment variables are injected securely via .env.docker.

Docker Compose handles orchestration in production using docker-compose.yml.

docker compose -f docker-compose.yml up -d

For more information, checkout Docker documentation for production.

wexCommerce is a mature, full-featured platform with a large and well-structured codebase. As of now, the repository contains over 54,000 lines of code across the backend, frontend, admin panel, shared packages, and test suites.

This scale reflects:

• Deep feature coverage across all platforms
• Extensive use of modular components
• Comprehensive TypeScript type safety
• High test coverage for critical backend functionality
• Production-ready integrations for Stripe, PayPal, and internationalization

Despite the size, the monorepo structure and strong architectural guidelines ensure the codebase remains organized, maintainable, and contributor-friendly.

wexCommerce is designed for real-world use in production environments. It includes:

• Secure JWT-based authentication with role-based access
• Verified Stripe and PayPal payment workflows
• Comprehensive Docker setup for both development and production
• Admin dashboard
• Fully internationalized UI with support for multiple languages
• Backend test coverage exceeding 80%, with CI pipelines and code quality checks
• Modular monorepo architecture for scalable maintenance and feature growth

To maintain high code quality and consistency across the project, wexCommerce uses Husky to run automated checks before each commit. This ensures all code that enters the repository meets predefined standards and avoids common issues early in the development cycle.

These checks are enforced for all codebases — backend, frontend, and admin panel.

• Detects problems before code is committed
• Keeps code style consistent across contributors
• Avoids broken builds or runtime type errors
• Prevents performance regressions from large files

The logic for these checks is implemented in a custom script located at:

/pre-commit.js

This script:

• Runs tasks concurrently per workspace (e.g., frontend, backend)
• Adapts to Docker environments if needed
• Supports selective linting and type-checking
• Logs summaries and failures clearly

You can manually run the checks using:

npm run pre-commit

This is useful if you want to validate your code before pushing without triggering a full commit. Note that you need to stage the files first.

The script intelligently detects whether it’s running inside Docker and adjusts paths and behavior accordingly to ensure correct execution.

The Husky hook is defined in:

/.husky/pre-commit

It simply executes:

node pre-commit.js

If any of the checks fail, the commit will be aborted. This helps ensure that only safe, clean, and performant code is added to the repository.

wexCommerce uses GitHub Actions for automated Continuous Integration (CI), ensuring code is always tested and built correctly before merging. The CI workflows help catch issues early and enforce project standards across contributions.

• File: .github/workflows/build.yml
• Purpose: Builds all packages and apps in the monorepo to ensure there are no runtime or dependency errors.

What it does:

• Installs dependencies
• Builds shared packages and each app (backend, frontend, admin panel)
• Verifies successful compilation

This workflow helps maintain consistency and guarantees that the entire project is in a shippable state.

• File: .github/workflows/test.yml
• Purpose: Runs all integration tests using Jest.

What it does:

• Installs dependencies
• Runs Jest test suites
• Generates and reports test coverage

This workflow ensures that new commits do not break existing functionality and that the codebase remains reliable and maintainable.

wexCommerce ensures that the backend test coverage remains consistently above 80%, providing strong guarantees for API correctness and stability. Coverage reports are automatically uploaded to:

• 📊 Coveralls
• 📈 Codecov

These platforms provide detailed insights into tested and untested code paths and highlight coverage trends. This encourages contributors to write meaningful tests and maintain a high standard across the codebase.

If the coverage upload to Coveralls or Codecov fails (e.g., due to service downtime or a network issue), the CI workflow is designed to continue and not fail the build, so development is not blocked. However, the repository owner is automatically notified by email when this happens. These services generate a hidden post internally to alert maintainers of the failure, allowing follow-up without interrupting team productivity.

Combined with the Husky pre-commit checks, CI workflows serve as a second layer of protection, verifying that even if something is missed locally, it will be caught during pull request checks.

These CI pipelines are triggered automatically on push and pull_request events targeting the main branch.