---

🍀 Clover Ecom Microservices (Monorepo)

A full-stack e-commerce ecosystem built to learn and practice Microservices Architecture, Event-Driven Systems, and Monorepo Management. This project is a Monorepo managed by Turborepo, coordinating a collection of specialized microservices.

The Concept

This project is a playground for learning how to scale applications by breaking them into smaller, specialized services. Instead of one giant app, it separate services that communicate through a message broker (Kafka).

• Admin Dashboard: Manages the store catalog in PostgreSQL. Creating a product triggers a Kafka event that automatically synchronizes the product and pricing with Stripe.
• Client Storefront: A Next.js 15 app using Zustand for state management. Checkout success triggers events to persist transaction data into MongoDB.
• Shared Packages: Central internal library system within the monorepo to standardize database schemas, Kafka producers, and TypeScript types across all services.
• Stripe Webhooks: Uses ngrok to tunnel real-time Stripe events to the local environment for local testing.

System Architecture

This project is a Monorepo managed by Turborepo:

Component	Path	Description
Frontend	/apps/web	Next.js 15 application using the App Router for both admin and client interfaces.
Auth Service	/apps/services/auth	Express-based authentication service integrated with Clerk for identity management.
Product Service	/apps/services/products	Product and catalog management service using Prisma with PostgreSQL.
Order Service	/apps/services/orders	Transactional order service built with Fastify, persisting data in MongoDB.
Email Service	/apps/services/email	Background worker built with Hono that handles email delivery via Nodemailer.
Messaging	/packages/core/kafka	Centralized event bus using Apache Kafka for inter-service communication (e.g., user.created → email notification).

🚧 Architecture Documentation (Planned Improvements)

The current documentation intentionally avoids over-detailing early-stage decisions. The following improvements are planned to better represent the system architecture:

TODO:

• Add architecture diagrams
• Visualize Kafka event flows (e.g. product.created, order.created, payment.successful)
• Document service boundaries and ownership (DDD-inspired)
• Clarify sync vs async communication rules
• Add sequence diagrams for critical flows:
  • Product creation → Stripe sync
  • Checkout → Payment → Order → Email
• Document failure handling and retries in Kafka consumers

Tech Stack

Layer	Technologies
Monorepo	Turborepo, pnpm Workspaces
Frontend	Next.js, TailwindCSS, Lucide Icons
Backend Frameworks	Express, Fastify, Hono
Databases	PostgreSQL (Prisma), MongoDB (Mongoose)
Messaging	Apache Kafka (kafkajs)
Payments	Stripe
Identity	Clerk Auth
Tooling	TypeScript, Zod, Vitest, Docker

---

Getting Started

Prerequisites

• Node.js 20+
• pnpm
• Docker Desktop (for Kafka & Databases)
• Stripe account (test mode)
• ngrok (for Stripe webhooks)

Installation

• TODO

Event Map (Kafka Topics)

Topic	Produced By	Consumed By	Description
user.created	Auth Service	Email Service	Send welcome email
product.created	Product Service	Payment Service	Create Stripe product
order.created	Order Service	Email Service	Order confirmation
payment.successful	Payment Service	Order, Email	Finalize order
...

🧪 Testing

We use Vitest for unit and testing.

# Run all tests
pnpm test

# Run tests for a specific package
pnpm --filter @repo/db-product test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.