Atlas Commerce
Full-Stack E-Commerce Platform with Vue 3 & NestJS
🎯 Project Overview & Objective
A full-stack e-commerce system featuring a Vue 3 storefront and admin UI, Pinia state management with local cart persistence, a NestJS REST API with Prisma ORM, PostgreSQL database, and WhatsApp cash-on-delivery checkout.
⚡ The Engineering Challenge
Regional e-commerce businesses need fast, mobile-first storefronts coupled with robust backend inventory control and regional checkout adaptations (such as WhatsApp ordering and Cash on Delivery). Off-the-shelf monolithic platforms often incur high recurring plugin fees, slow mobile loading speeds, and restrictive checkout workflows.
🏗️ Architecture & System Design
Frontend Architecture
Vue 3 Composition API with Vite for sub-second build times, Pinia state management with LocalStorage cart persistence, and responsive mobile-first CSS.
Backend & Service Layer
NestJS enterprise REST API utilizing modular architecture (AuthModule, ProductsModule, OrdersModule, PrismaModule) with Class-Validator DTOs and dependency injection.
Database & Persistence
PostgreSQL database managed through Prisma ORM with declarative schema migrations, automated foreign key constraints, and relational integrity.
API & Communication
Clean RESTful API exposing categorized catalog endpoints, administrative inventory CRUD, and order intake routes with typed DTO validation.
Auth, Permissions & Security
Passport JWT authentication guards protecting administrative routes, password hashing with bcrypt, and parameterized queries preventing SQL injection.
System Architecture Data Flow
+-----------------------------------------------------------------------------+
| STOREFRONT & ADMIN CLIENT |
| Vue 3 (Composition API) + Vite + Pinia State Management |
| - Category Catalog & Search - Persistent Local Cart Store |
| - WhatsApp Checkout Dispatch - JWT-Guarded Merchant Admin UI |
+--------------------------------------|--------------------------------------+
| REST API (/api/v1 - JSON Payloads)
v
+-----------------------------------------------------------------------------+
| NESTJS ENTERPRISE BACKEND |
| Modular Architecture (AuthModule, ProductsModule, OrdersModule) |
| - Class-Validator DTO Pipes - Passport JWT Auth Guards |
| - Product & Order Services - Dependency Injection Container |
+--------------------------------------|--------------------------------------+
| Type-Safe Prisma Queries
v
+------------------------------------+ +------------------------------------+
| DATABASE LAYER | | ORDER DISPATCH SINK |
| PostgreSQL Database | | WhatsApp Business Deep-Link |
| - Prisma Automated Migrations | | - Pre-Formatted Markdown Order |
| - Categories, Products, Variants | | - Cash on Delivery Coordination |
+------------------------------------+ +------------------------------------+ 🚀 Implemented Capabilities
Decoupled Vue 3 & Vite Storefront
Lightweight, snappy client interface featuring instant category filtering, full-text product search, and responsive mobile product cards.
Persistent Pinia Cart & WhatsApp Checkout
Client-side cart state hydrated from LocalStorage, supporting quantity modifications, variant selections, and formatted one-click WhatsApp order dispatch.
Modular NestJS Backend & Prisma ORM
Enterprise backend architecture with strict separation of controllers, services, and repositories, backed by Prisma migrations on PostgreSQL.
Administrative Catalog & Order Management
Secured admin dashboard for adding products, uploading media, updating stock quantities, and tracking incoming order statuses.
🛠️ Engineering Challenges & Solutions
Cross-Layer Type Safety and DTO Validation
Maintaining data consistency between incoming client payload shapes, NestJS backend services, and Prisma database models across decoupled repositories.
Defined shared TypeScript interfaces and leveraged NestJS ValidationPipes with Class-Validator decorators to reject malformed requests at the controller boundary before hitting the database.
Cart State Hydration Without Flashing
Loading stored cart items from client LocalStorage during Vue 3 component mounting can cause visual layout shift and hydration mismatches.
Implemented Pinia store plugin architecture that reads and validates LocalStorage items synchronously during store initialization with fallback error guards.
⚖️ Technical Decisions & Architectural Trade-offs
NestJS with Prisma ORM vs Express with Raw SQL
Selected NestJS for enterprise modularity, dependency injection, and Prisma for type-safe database queries with declarative migrations and automated relational integrity.
Higher initial boilerplate and stricter TypeScript compilation compared to minimal Express setups.
Pinia Store with LocalStorage Plugin vs Vuex
Selected Pinia for Vue 3 Composition API ergonomics, smaller bundle footprint, and synchronous LocalStorage cart hydration.
Required custom error boundary guards to catch corrupted client LocalStorage JSON payloads.
WhatsApp Checkout vs Mandatory Payment Gateway
Adapted checkout to regional merchant patterns using direct WhatsApp order message composition alongside Cash on Delivery, significantly reducing cart abandonment.
Order confirmation requires merchant-buyer chat confirmation rather than instantaneous automated credit card webhooks.
🧪 Testing Strategy & Verification
Quality Strategy: DTO validation testing, Prisma schema migration verification, and cart state hydration tests.
Verified Test Scenarios
- NestJS ValidationPipe rejecting invalid product/order payloads with structured 400 Bad Request responses.
- End-to-end cart state persistence across page refreshes and browser tab closures.
- Admin JWT guard verification ensuring unauthorized requests cannot mutate inventory or catalog data.
- Formatted WhatsApp checkout URI generation with URL-encoded order line items and pricing totals.
📈 Results & Technical Learnings
Verified Implemented Outcomes
- Delivered a complete full-stack e-commerce solution with decoupled Vue 3 frontend and NestJS backend.
- Verified database migrations, seed scripts, and admin authentication workflows.
- Open-source codebase available on GitHub at bouhouchhamza/atlas_ecom.
Architectural Takeaways
- NestJS combined with Prisma provides unparalleled developer velocity and architectural predictability for full-stack TypeScript systems.
- Adapting checkout methods to regional preferences (such as WhatsApp ordering) significantly reduces checkout friction compared to mandatory credit card walls.
🧰 Complete Technology Stack
Need a Similar System or Application?
I collaborate with businesses and agencies to engineer scalable web backends, interactive client applications, and custom automation workflows.