Full-Stack

Commercial E-commerce Ecosystem

1. Executive Summary & Impact

Developed a production-ready, modular e-commerce ecosystem to automate retail operations for a bird nest product shop. The architecture utilizes a Monorepo to unify a high-performance customer storefront with a secure administrative command center, reducing deployment overhead and ensuring code consistency across the entire stack.

2. Technical Architecture & Design Patterns

I engineered this commercial ecosystem using a Decoupled Monorepo Architecture managed via TurboRepo and pnpm workspaces. The system is strategically split into specialized layers to ensure maximum developer velocity, strict type safety, and a secure, "stateless" backend.

1. The Monorepo Core (monorepo/packages)

Shared LogicCentralizes TypeScript interfaces, constants, and utility functions.
ImpactThis ensures 100% type safety between the Next.js storefront, the React-Admin panel, and the NestJS API. If a data structure changes in the backend, the frontend is immediately aware, preventing runtime errors.

2. The Client & Identity Layer (monorepo/web & monorepo/admin)

The "Front Desk" (Next.js)Hosted on Vercel, this app serves as both the customer storefront and the Identity Provider (IdP).
Authentication AuthorityBy utilizing Better-Auth natively within Next.js, the system handles logins and sessions at the "edge." It issues JWTs (Digital Keys) that grant users access to the rest of the ecosystem.

3. The Business API Layer (monorepo/api)

The "Resource Server" (NestJS)Hosted on Render, this standalone API is the engine for all core business logic.
Decoupled SecurityIt does not share a session database with the frontend. Instead, it operates as a secure resource server that verifies incoming requests cryptographically.
System Architecture
Click to enlarge

Functional Flow Analysis

The interactions in the system are categorized by their specific functional purpose:

A. Security & Verification (The Cryptographic Handshake)

A1 & A2 (Identity Issuance)Users authenticate via the Next.js/Better-Auth layer to receive a JWT.
A3 (JWKS Handshake)To verify these tokens, the NestJS API uses a jwks-rsa client.
The "Senior" DetailInstead of requesting verification for every call, the API fetches and caches the public signing keys from the Auth API. This reduces network overhead and ensures that token verification is nearly instantaneous and highly resilient.

B. Authorized Business Logic Flow

B1 & B2 (Stateless Requests)The Web app and Admin panel send requests to NestJS with the JWT attached. The API’s custom AuthGuard verifies the signature against the cached keys and enforces Role-Based Access Control (RBAC) before allowing any data modification.

C. Infrastructure & Persistence Flow

C1 & C2 (Data Integrity)The system uses PostgreSQL with TypeORM. Specifically, the API utilizes QueryRunners to manage manual transactions, ensuring that complex multi-table updates (like orders and inventory) are atomic.
C3, C4 & C5 (External Integrations)High-resolution media is managed through Vercel Blob Storage, while transactional communications are automated via Resend.

3. Key Features & Implementation

  • •Secure Authentication: Unified session strategy using better-auth (Next.js) and JWT verification (NestJS) with jose and jwks-rsa.
  • •Role-Based Access Control (RBAC): Custom AuthGuards to protect sensitive administrative endpoints.
  • •Scalable Media Handling: Integrated Vercel Blob for secure image storage with automated cleanup logic.
  • •Automated Communications: Integrated Resend for transactional email triggers (order confirmations, status updates).

4. Challenges & Solutions

Challenge:

Secure Distributed Authentication: Maintaining a unified session across a decoupled Next.js storefront and a standalone NestJS API.

Solution:

Built a custom verification layer in NestJS using a jwks-rsa client to validate JWTs issued by the Next.js/Better-Auth server. By implementing caching and rate-limiting on the key-retrieval process, the system ensures secure, high-speed authorization without a shared session database.

Challenge:

Transactional Data Integrity: Ensuring consistency across multiple relational tables during complex business operations like order placement or inventory updates.

Solution:

Leveraged TypeORM’s QueryRunner for manual transaction control. This guarantees atomic operations, ensuring that if any step of a multi-table update fails, the entire database state is rolled back to prevent orphaned records or inventory mismatches.

Challenge:

Secure & Scalable Media Management: Handling large image uploads from the Admin Panel directly to Vercel Blob without exposing the API to heavy file buffering or unauthorized storage access.

Solution:

Implemented a Token-based Upload Flow. The NestJS API acts as a gatekeeper, generating secure, short-lived Client Upload Tokens. This allows the Admin Panel to upload directly to Vercel Blob from the browser—reducing API load—while the backend maintains strict control over file permissions and ensures transactional cleanup of orphaned files.

5. Tech Stack Summary

Frontend

Next.js,React,React-admin,Tailwind CSS

Backend

NestJS,TypeORM,PostgreSQL,Node.js

Auth & Security

better-auth,JWT (jose, jwks-rsa),Custom RBAC Guards

Infrastructure

TurboRepo,pnpm,Vercel Blob,Resend,Vercel/Render

Project Gallery

Scroll to explore