Cali StoreFull-Stack E-Commerce Platform

Cali Store: Engineering a Full-Stack E-Commerce Platform

Developing Cali Store, a full-stack e-commerce platform, presented a significant engineering challenge: orchestrating numerous complex subsystems into a cohesive, production-grade experience. This case study details the architectural decisions, technical implementations, and problem-solving strategies employed to build a robust storefront, an intuitive admin panel, secure payment processing, reliable email delivery, and a consistent data model.

Core Architecture and Key Technologies

For the frontend, I chose Next.js with the App Router, leveraging server and client components to optimize rendering and data fetching. This allowed for dynamic server-side rendering for SEO and faster initial loads, while client components enabled rich interactivity. The backend and database interaction were managed by Drizzle ORM, providing a type-safe way to interact with a PostgreSQL database hosted on Neon. Neon's serverless architecture offered scalability and performance benefits crucial for an e-commerce platform. Client-side data management and caching were handled by TanStack Query, specifically its optimistic update feature, which dramatically improved perceived performance by updating the UI instantly before the server confirmed the operation.

💡 The combination of Next.js App Router, Drizzle ORM, and TanStack Query provided a robust and performant foundation for the entire application, enabling rapid development with strong type safety.

Order Lifecycle and Payment Processing

Managing the order lifecycle was a critical area. A 10-item cart capacity was enforced at both the database (via a CHECK constraint) and UI levels. Order creation was primarily driven by Stripe webhooks. This approach ensures that orders are only officially created and processed after successful payment confirmation from Stripe, preventing data inconsistencies. We implemented logic to reuse a 'pending' order state if a user initiated checkout but didn't complete it, allowing them to resume their purchase. The webhook handler was designed to be idempotent and robust, handling potential retries and ensuring reliable order creation.

Transactional and Authentication Emails

A dual-pronged email strategy was adopted. Nodemailer was used for transactional emails like order confirmations and shipping updates, integrated directly into the backend workflow. For authentication-related emails (e.g., OTP verification, password resets), Brevo was integrated, offering a dedicated service for these sensitive communications. To ensure deliverability and provide visibility, a comprehensive `email_logs` table was implemented. This table tracks all outgoing emails, their status, and timestamps. An admin UI was built to monitor these logs and manually trigger retries for failed deliveries, crucial for maintaining customer trust and communication.

async function handleStripeWebhook(payload, signature) {
  // Verify signature and process event
  const event = stripe.webhooks.constructEvent(payload, signature, process.env.STRIPE_WEBHOOK_SECRET);

  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      await createOrderFromPayment(paymentIntent);
      break;
    // ... other event types
    default:
      console.log(`Unhandled event type ${event.type}`);
  }
  return { statusCode: 200 };
}

Admin Capabilities and Analytics

The admin panel provides comprehensive control over the store. This includes managing products, categories, promotional banners, and discount coupons. Order management allows for viewing, updating status, and processing returns. A real-time analytics dashboard was a key feature, with aggregations performed directly at the database level using PostgreSQL's powerful querying capabilities to ensure performance. To maintain accountability, all admin actions are logged, with cursor-based pagination implemented for efficient retrieval of historical data.

Customer Profile and Frontend Enhancements

The customer profile section offers a unified view of their interactions with Cali Store, including order history, current cart, wishlist items, product reviews, available coupons, and account settings. Account management is secured with OTP email verification. Beyond core functionality, Cali Store incorporates modern web features: PWA support for app-like experiences, a cookie consent manager, full dark mode support, and engaging scroll animations powered by GSAP and Three.js for a visually rich user interface.

📌 Enforcing constraints at both the database and UI levels is crucial for data integrity in e-commerce systems.

Conclusion

Cali Store represents a robust, production-ready e-commerce platform built with modern, performant technologies. The focus on architectural clarity, reliable data handling, and a rich user experience, both for customers and administrators, was paramount throughout its development.