Back to Projects

ECOMMERCE

ReactReact QueryReduxTailwind CSSShadcn UINodejsExpressPrismaMongoDB

FULLSTACK APP - Admin Panel with Data Tables - AI-powered assistant - Checkout Process - WhatsApp notifications - Filters for query parameters - Cursor Pagination - Clean Architecture

ECOMMERCE

Links

View on GitHub

Created

April 7, 2025

Project README

Detailed documentation about this project

Technologies

ReactTypeScriptViteTailwind CSSShadcn/UIReact Hook FormZodReduxTanstack React QueryTanstack React TableNodejsExpressJwtPrismaMongoDBOpenAIWhatsapp Web JsJestSupertest

Overview

VzCommerce is a lightweight, sales-focused ecommerce platform designed for small businesses that close deals through WhatsApp. Instead of forcing the entire checkout process inside the website, VzCommerce acts as a seamless bridge: customers browse a full product catalog, view price, stock and promotions, and once they decide to buy, the platform automatically routes the order to WhatsApp so the seller and customer can finalize payment, shipping, and details privately. On the admin side, sellers get a complete dashboard with real-time analytics powered by Chart.js, dynamic tables with pagination for managing products, and a dedicated orders panel. It also includes an integrated AI assistant specialized in digital business and sales to provide guidance, insights, and optimization tips.

What & Why

What

VzCommerce is a lightweight, sales-focused ecommerce platform designed for small businesses that close deals through WhatsApp.

Why

Many small sellers prefer finalizing their sales through WhatsApp, where they can negotiate, build trust, and adapt pricing or delivery on the fly. However, keeping a catalog updated manually, sending photos, prices, descriptions one by one is tedious and unscalable. VzCommerce was built to solve that gap: give customers a comfortable, organized place to explore the entire catalog, while preserving the seller's preferred workflow of closing the sale in private through WhatsApp.

The Challenge

The main challenge was to create an ecommerce platform that feels complete and professional, apply Clean Architecture with design patterns, and implement a robust testing strategy with +500 tests. At the same time, building a robust admin panel with real-time analytics, dynamic data tables, and an AI assistant required careful architecture, and clean, maintainable code.

Highlights

  • Product Listings: Display of products with details such as name, description, price, and images
  • Category Management: Categorizing products for easy navigation
  • Shopping Cart: Add, remove, and manage products in a shopping cart
  • Admin Authentication: Secure admin login
  • Admin Panel: Administrative interface for managing products, categories, and orders with Data-Tables (tanstack/react-table)
  • Checkout Process: Streamlined checkout process with token-based validation
  • AI Assistant: Private admin AI to help manage the store
  • WhatsApp Automated Message: WhatsApp notifications for order confirmations
  • Image Handling: Image transformation, WebP conversion, and cloudinary uploads, and lazy loading for optimized performance
  • Real-time Analytics: Track statistics of the store with Chartjs
  • Modular Components: Reusable UI elements and organized architecture for maintainability
  • Optimized Build Process: Streamlined workflows with Vite, TailwindCSS, and TypeScript configurations
  • Secure API & Authentication: Robust route protection, session management, and user authentication
  • State & Data Management: Centralized store with Redux Toolkit, React Query, and data validation schemas
  • Flexible Routing & Admin Tools: Organized navigation, admin dashboards, and private pages

Features

  • User authentication with JWT tokens and role-based access control (user/admin)
  • Complete shopping cart with persistent state using Redux
  • Advanced product search and filtering by category, price range, and query parameters
  • AI-powered assistant for product recommendations and customer support (OpenAI GPT-4.1)
  • WhatsApp notification system for order status updates via WhatsApp Web.js
  • Admin dashboard with analytics, data tables, and CRUD operations for products/categories/orders
  • Image upload and management for products with Cloudinary
  • Responsive design optimized for mobile and desktop
  • WhatsApp Web.js for session management with QR authentication
  • Message states: PENDING → SENT → RESPONDED → COMPLETED
  • AI Chat Interface in admin panel
  • AI Insights Cards for business analysis
  • Cloudinary direct upload with presets and automatic WebP conversion
  • react-cropper for image resizing
  • Browser-side compression before upload
  • Multiple images per product (gallery)
  • Real-time analytics with Recharts: Line Chart, Bar Chart, Pie Chart, Area Chart
  • Dynamic tables with TanStack Table, sorting, filtering, pagination

Pages

Public Pages

/- Home page with featured products and carousel
/products- All products list with filters
/promotion- Products on promotion
/featured- Featured products
/new- New arrivals
/categories/:category- Products filtered by category
/search- Search results page
/products/:id- Product detail page
/checkout/:token- Checkout page with token validation
/order/:id- Order confirmation page
/login- Admin login page

Private Pages (Admin)

/private/admin- Main admin dashboard
/private/admin/analytics- Real-time analytics with charts
/private/admin/products- Product management with data tables
/private/admin/categories- Category management
/private/admin/order- Order management
/private/admin/ai- AI assistant chat interface
/private/admin/settings- Store configuration

Architecture

Type: Clean Architecture

The backend follows Clean Architecture with 4 clearly defined layers: Domain (Entities, Interfaces, DTOs), Application (Use cases, Business logic services), Infrastructure (External implementations - Prisma, APIs, Adapters), and Presentation (Routes, Controllers, Middlewares).

Principles

  • Dependency Inversion: External layers depend on internal ones
  • Testability: Each layer can be tested in isolation
  • Separation of Concerns: Responsibilities clearly defined

Layers

Domain

Entities, Interfaces, DTOs (innermost layer)

Application

Use cases, Business logic services

Infrastructure

External implementations (Prisma, APIs, Adapters)

Presentation

Routes, Controllers, Middlewares

Design Patterns

PatternImplementationLocation
RepositoryData access abstractioninfrastructure/repositories/*
BuilderComplex object creationProductBuilder, OrderBuilder, OrderItemBuilder
AdapterInterface conversionOrderSendMessageToCustomer.impl.ts
FactoryTest data generationTest helpers
MiddlewareCross-cutting concernsAuthMiddleware, ValidationMiddleware
Dependency InjectionLoose couplingConstructor injection in services

State Management

Hybrid state management strategy that separates server state from client state

State TypeTechnologyUse Case
Server StateTanStack Query (React Query)Products, Categories, Orders, Auth data
Client StateRedux ToolkitShopping cart (needs persistence)
Form StateReact Hook FormAll forms with Zod validation
UI StateReact useStateLocal component state

React Query handles server state with automatic caching, background refetching, optimistic updates, and cache invalidation. Redux Toolkit is used exclusively for the shopping cart because it needs to persist across sessions (localStorage) and has complex synchronous logic with reducers.

Performance Optimizations

OptimizationImplementation
Lazy LoadingReact.lazy() + Suspense for routes and heavy components
Image Lazy LoadingCustom Lazy component with IntersectionObserver
Debounced SearchuseDebounce hook (300ms delay) to avoid excessive API calls
Skeleton LoadersVisual placeholders during data fetch
React Query CachingstaleTime: 5min, gcTime: 10min
Optimistic UpdatesImmediate UI updates with automatic rollback on error
Image OptimizationWebP conversion, Cloudinary CDN
Component MemoizationReact.memo where needed

Security

FeatureImplementation
JWT in CookieshttpOnly, secure, sameSite cookies
Helmet.jsHTTP security headers
CORSConfigurable allowed origins
Rate Limitingexpress-rate-limit (100 requests/15min)
bcryptjsPassword hashing
Zod ValidationInput validation on both client and server
Auth MiddlewareToken verification on protected routes

Testing Strategy

The backend has 59 test files with over 11,000 lines of test code

Test TypeCoverage
Unit TestsServices, DTOs, Entities
Integration TestsRepositories, Controllers
E2E TestsFull flows (auth → create → update → delete)
Black Box TestsTesting without internal code access
ModuleUnitIntegrationE2E
Auth✅✅✅
Products✅✅✅
Categories✅✅✅
Orders✅✅✅
Middlewares✅❌❌

API & Data Fetching

Query Parameters

Pagination:

pagelimit

Filters:

searchcategorypriceMinpriceMaxinStockfreeShippingfeaturedpromotionnewsize

Sorting:

sortBy (price | createdAt | discountPercentage)sortDir (asc | desc)

Custom Hooks (22+)

  • useProducts - Fetch products with filters
  • useProductsFilters - Filter state management
  • useProductById - Single product fetch
  • useProductMutations - CRUD operations
  • useCategories - Categories fetch
  • useCategoryMutations - Categories CRUD
  • useOrders, useOrderById - Orders fetch
  • useOrderMutations - Orders CRUD
  • useStoreCustomer - Store data
  • useAuthMutations - Login/Logout
  • useSession - Session verification
  • useCartActions - Cart management
  • useCheckout - Checkout process
  • useAIMutations - AI chat
  • useDebounce - Avoid excessive requests
  • useImageCropper - Image cropping
  • useMobile - Responsive detection
  • useCheckoutForm - Checkout form
  • useProductForm - Product form
  • useOrderForm - Order form
  • useInstallments - Installment calculation
  • useImageUpload - Cloudinary upload

Project Structure

Type: Monorepo

client/src/components- React components
client/src/guards- Route guards
client/src/hooks- Custom hooks (25+)
client/src/layouts- Layout components
client/src/lib- Utilities, axios, zod schemas
client/src/pages- Page components
client/src/types- TypeScript types
client/src/store- Redux store
client/src/utilities- Utility functions
client/src/data- API calls
client/src/routes- Application routes
server/src/AI- AI Assistant feature
server/src/Auth- Authentication
server/src/Categories- Categories feature
server/src/Checkout- Checkout feature
server/src/Orders- Orders feature
server/src/Products- Products feature
server/src/StoreCustomers- Store customers
server/src/shared- Shared modules
server/tests/context- Unit & integration tests
server/tests/apps- E2E & black box tests
server/tests/helpers- Factories, mocks, helpers
server/prisma- Prisma schema and migrations

Installation

  1. Clone the repository git clone https://github.com/ValentinZoia/e-commerce.git
  2. Navigate to the client directory cd e-commerce/client
  3. Install client dependencies npm install
  4. Navigate to the server directory cd ../server
  5. Install server dependencies npm install
  6. Set up the database Ensure MongoDB is running and configure DATABASE_URL in .env
  7. Generate Prisma client npm run prisma:generate

Learnings

Deepened understanding of state management at scale with Redux Toolkit and React Query; Learned how to implement Clean Architecture with clear separation of concerns (Controllers/Services/Repositories); Gained experience with AI integration patterns and API design for AI assistants; Improved skills in handling complex form validation and data transformation; Understood the importance of proper error handling and user feedback in e-commerce flows; Mastered WhatsApp Web.js integration for real-time notifications; Learned advanced MongoDB aggregation pipelines and indexed queries for efficient filtering; Gained experience building real-time analytics dashboards with Chart.js/Recharts.

Challenges

  • Implementing a seamless checkout flow with multiple payment states and error handling - solved by breaking down the process into clear steps with validation at each stage
  • Building an efficient product filtering system with multiple parameters - solved by using MongoDB aggregation pipelines and indexed queries
  • Creating a responsive admin dashboard with complex data tables - solved by implementing pagination, sorting, and search on both frontend and backend
  • Integrating WhatsApp notifications while handling API rate limits and message queuing

Screenshots

Back to all projects