Introduction
Project Overview
HeartsyBox is a modern, full-featured e-commerce platform built around one core idea making gift-giving effortless, personal, and memorable. Whether a customer already knows what they want, needs a hand-crafted custom box built step by step, or has no idea where to start, HeartsyBox guides them through the entire experience from discovery to doorstep delivery.
The platform allows customers to browse a curated catalog of gifts, select from pre-made themed gift boxes, or build a fully personalized gift box from scratch choosing sweets, flowers, packaging, and adding a heartfelt personal message. For the undecided shopper, HeartsyBox features an intelligent Gift Picker quiz that asks a few simple questions and recommends the perfect gift based on the recipient's personality, occasion, and interests.
Behind the scenes, a powerful admin panel gives the business team full control over products, orders, blog content, and promotional discount codes all without touching a line of code. The platform is built on the MERN stack, integrated with Stripe for payments, Cloudinary for media, and SendGrid for transactional emails.
Mechanism
Project Description
HeartsyBox is a comprehensive online gifting platform that redefines how people shop for gifts. It bridges the gap between a customer's intent and the perfect gift through three distinct shopping paths, each designed for a different type of buyer.
The problem it solves
Finding the right gift is universally hard. Most people spend hours searching online only to end up with something generic that feels impersonal. HeartsyBox eliminates this friction by offering three clearly defined paths quick ready-made boxes for the decisive shopper, a guided builder for the creative one, and a smart quiz for anyone who needs a starting point.
Three shopping paths
- Ready-made gift boxes — pre-assembled themed boxes for quick, hassle-free gifting. Customers see exactly what's inside and add to cart instantly.
- Custom box builder — a guided, 6-step journey where the customer builds a fully personalized box from scratch, choosing every detail from sweets to packaging.
- Gift Picker quiz — an interactive questionnaire that asks about the recipient and occasion, then recommends the most suitable gift automatically.
The 6-step custom box builder
HeartsyBox's signature feature — a guided creation experience:
- Step 1 — Sweets & treatsChoose from a curated selection of sweets, snacks, and treat items to include in the box.
- Step 2 — Flowers & add onsSelect fresh flowers, dried arrangements, or complementary add on items.
- Step 3 — Main gift item & colorPick the centrepiece gift item and choose from available color variants.
- Step 4 — PackagingChoose the paper type and envelope style the wrapping that frames the entire gift.
- Step 5 — PersonalizationAdd the recipient's name, a monogram, or special dates to make it uniquely theirs.
- Step 6 — Review & checkoutSee the complete box summary, apply a voucher code, and proceed to secure Stripe payment.
End-to-end customer journey
From landing on the site, a customer browses or filters the catalog, selects or builds their box, goes through a clean two-step checkout that collects sender and recipient details plus a personal message, pays securely via Stripe, and receives an instant personalized order confirmation email via SendGrid. The admin team is also notified immediately so fulfillment can begin without delay.
Primary Industry
- Online Retail & E-Commerce
- Gifting & Personalization
- Occasion-Based Shopping (Birthdays, Anniversaries, Weddings)
- Corporate & Bulk Gifting
- Subscription & Curated Box Services
- Direct-to-Consumer (DTC) Brands
Roles
Who the End Users Are
Designed for gift-givers at every stage from the person who knows exactly what they want to the one who needs full guidance and for the admin team managing the entire operation.
| User Type | Description |
|---|---|
| Gift Shoppers | Individuals shopping for birthdays, anniversaries, holidays, weddings, baby showers, and any celebration. The core customer base. |
| Bulk / Corporate Buyers | Companies or individuals ordering curated boxes for events, client appreciation, or staff recognition. |
| Occasion-Driven Buyers | Customers who shop for a specific person type (mother, friend, partner, child) or interest group and need guidance on what to pick. |
| Admin / Business Team | The Heartsy team managing products, orders, vouchers, and blog content via the admin panel no code required. |
Target demographics: adults aged 18–55 who shop online, seeking thoughtful personalized alternatives to generic gifts across personal and professional occasions.
Core Features
Gift Catalog & Browsing
Full library of gifts filterable by recipient type (him, her, kids), occasion, celebration type, age group, and personal interests. Full product pages with images, pricing, and personalization options.
Ready-Made Gift Boxes
Curated pre-assembled themed boxes with a clear contents list. Customers see exactly what's inside and add to cart instantly — no configuration needed.
Custom Gift Box Builder
6-step guided creation journey: sweets → flowers → main gift & color → packaging → personalization → review. Progress saved to the browser so customers never lose their work.
Gift Picker Quiz
Interactive questionnaire about the recipient (age, relationship, interests, occasion) that recommends the most suitable gift. Acts as a built-in personal shopping assistant.
Persistent Shopping Cart
Cart remembers items across sessions with all personalization details intact — colors, names, monograms. Supports quantity changes and item removal.
Secure Checkout & Payment
Clean two-step checkout collecting sender and recipient details, personal message, and voucher codes. Payment processed securely via Stripe.
Order Confirmation & Emails
Personalized confirmation page and branded email via SendGrid after each successful order. Admin team notified instantly for immediate fulfillment.
Blog / Content Hub
Built-in blog with rich text content, images, and videos — used to share gifting ideas, occasion guides, and brand stories. Fully managed from the admin panel.
Product Management (Admin)
Add, edit, or remove products with multiple images, category tags, personalization pricing, color variants, and scope settings controlling which page each product appears on.
Order Management (Admin)
Full order dashboard with customer details, personalized item uploads, payment status, message history, and order lifecycle tracking.
Voucher & Coupon Management
Create percentage-based discount codes with custom validity date ranges — applied at checkout by customers in real time.
Admin Authentication
JWT-secured admin login with bcrypt-hashed credentials. Role-based access ensures only authorized team members can manage platform data.
Technologies Used
Frontend (customer-facing interface)
| Technology | Purpose |
|---|---|
| React 18 | Core UI framework for building the interactive interface |
| React Router v6 | Page navigation and URL routing |
| TanStack React Query v5 | Smart data fetching, caching, and synchronization |
| Bootstrap 5 | Responsive grid layout and base UI components |
| Ant Design (antd) | Advanced UI components for forms, tables, modals, and spinners |
| Styled Components | Component-level custom styling |
| Axios | HTTP client for communicating with the backend API |
| Stripe.js | Secure payment processing on the client side |
| React Slick | Image carousels and product sliders |
| React Helmet | SEO meta tag management per page |
| React Toastify | User-facing notifications (success, error, info) |
| React Quill / Draft.js | Rich text editing for blog content |
| React Dropzone | Drag-and-drop image uploads |
| FontAwesome + React Icons | Icon library |
| DOMPurify | Sanitizes HTML to prevent XSS attacks |
Backend (server & API)
| Technology | Purpose |
|---|---|
| Node.js | JavaScript runtime environment for the server |
| Express.js | Web framework for building the REST API |
| MongoDB | NoSQL database for storing all application data |
| Mongoose | ODM structure and validation for MongoDB documents |
| JSON Web Tokens (JWT) | Secure admin authentication and session management |
| bcrypt | Password hashing for secure admin credential storage |
| Multer | Handling multipart file uploads |
| Cloudinary SDK | Cloud image and video storage and delivery |
| SendGrid | Transactional email delivery (order confirmations) |
| Stripe SDK | Server-side payment session creation and verification |
| dotenv | Environment variable management |
| CORS | Cross-origin request handling between client and server |
DevOps & tooling
| Technology / tool | Purpose |
|---|---|
| Concurrently | Run frontend and backend simultaneously in development |
| Nodemon | Auto-restart server on file changes during development |
| Git | Version control |
Programming language
| Technology / tool | Purpose |
|---|---|
| JavaScript (ES6+) | Used across the entire stack frontend (React/JSX) and backend (Node.js/Express) |
Architecture Overview
HeartsyBox follows a classic MERN stack architecture MongoDB, Express.js, React, and Node.js. The frontend runs as a Single Page Application and communicates exclusively with the backend through a RESTful JSON API. All external services connect through the server, keeping API keys and secrets away from the browser.
High-level architecture
Client (React SPA) ←→ REST API (Express / Node.js) ←→ MongoDB Atlas
│ │
Cloudinary Stripe
(Images) (Payments)
│ │
SendGrid ← Stripe Webhooks
(Emails)- Frontend is a React SPA, all routing handled client-side via React Router v6
- Backend exposes a RESTful API consumed exclusively by the frontend
- Database hosted on MongoDB Atlas, a cloud-managed, high-availability NoSQL database
- Authentication is stateless using JWT tokens stored securely on the client
- Images and videos stored on Cloudinary with an organized folder structure
- Payments handled end-to-end by Stripe, session creation server-side, verification via webhook
- Emails delivered via SendGrid with branded HTML templates for customers and admins
- Custom box builder saves in-progress state to the browser, no server round-trip needed mid-build
Database Models
The platform stores data across 5 core MongoDB models, structured and validated via Mongoose.
| Model | What It Stores |
|---|---|
| Product | Gift items with title, price, images, color variants, category filters, personalization options, and scope flags controlling which page the product appears on |
| Order | Full order record, products, quantities, personalization details, sender/recipient info, personal message, payment status, and applied coupon codes |
| Coupon | Discount codes with percentage value and date-range validity for checkout application |
| Blog | Blog posts with rich text content, embedded images and video, author info, and publish/suspend status |
| User | Admin accounts with hashed password and role-based access for the admin panel |
External Integrations
Stripe
Secure online payment processing
Checkout session created server side; payment verification via Stripe webhooks. Customers never leave the platform during payment.
Cloudinary
Cloud media storage & delivery
Product images, blog media, and customer uploaded personalization images stored and served from Cloudinary with organized folder structure.
SendGrid
Transactional email delivery
Automated order confirmation emails sent to customers and purchase alerts to the admin team using branded HTML templates.
MongoDB Atlas
Cloud-hosted database
Managed cloud database ensuring high availability, automatic backups, and horizontal scalability as order and product volume grows.
Design & Brand Identity
HeartsyBox's visual identity is warm, feminine, and elegant, designed to align with gifting, celebration, and emotional connection. Every design decision reinforces the feeling of opening something special.
| Primary Color | Warm terracotta / rose-brown — #d29e84 |
| Secondary Color | Slate blue-gray — #415161 |
| Accent Color | Sienna brown — #a0522d |
| Heading Font | Tangerin — elegant serif typeface |
| Body Font | Euclid Circular A — modern, clean sans-serif |
| Design Style | Warm, feminine, elegant — aligned with gifting and celebration aesthetics |
| Responsive | Fully mobile-responsive with dedicated mobile navigation and filter UI |
- "Send the Perfect Gift, Everytime."
- "Delivering Quality Gifts for you and your loved ones."
- "Gifts for all occasions."
Project Summary
| Project Type | E-Commerce / Gifting Platform |
| Architecture | MERN Stack (MongoDB, Express, React, Node.js) |
| Primary Language | JavaScript (ES6+) |
| Frontend Framework | React 18 + React Router v6 |
| Backend Framework | Node.js + Express.js |
| Database | MongoDB (hosted on Atlas) |
| Authentication | JWT + bcrypt |
| Payment | Stripe |
| SendGrid | |
| Image Storage | Cloudinary |
| Responsive | Yes, fully mobile optimized |
| Admin Panel | Yes, full CMS-like control, no code required |
| End Users | Gift shoppers, occasion buyers, corporate buyers, admin team |
| Key Differentiator | Custom box builder + smart Gift Picker quiz |
- 5 core MongoDB models covering the full gifting and order lifecycle
- 6-step custom box builder with browser-persisted progress state
- Smart Gift Picker quiz acting as a built-in personal shopping assistant
- 4 external service integrations: Stripe, Cloudinary, SendGrid, MongoDB Atlas
- Full admin panel, products, orders, vouchers, and blog managed without code
- DOMPurify on all rich text content to prevent XSS attacks
- Fully mobile-responsive with dedicated mobile navigation and filter experience
HeartsyBox is a production-ready gifting platform that transforms the way people shop for gifts online. With its guided custom box builder, intelligent Gift Picker, and seamless checkout experience, it turns a frustrating process into a delightful, personalized journey from the first click to the final delivery.