Shop Microservers

Shop Microservers is a full-stack e-commerce application designed to demonstrate a real-world, decoupled microservices architecture. Each business domain (auth, catalog, cart, orders) lives in its own service, with its own database and its own deployment lifecycle, while a single gateway exposes a cohesive HTTP interface to the frontend.

Architecture and Tech Stack

Core Architecture

• Pattern: Microservices with database-per-service (each service owns its data).
• Gateway: Nginx as a reverse proxy and single entry point (port 80).
• Communication: Internal HTTP over a Docker bridge network (shop), using service names as hostnames.
• Orchestration: Docker Compose with health checks and health-based dependencies (condition: service_healthy).
• API contract: Uniform { success, data, error } response across all services.

Layered Diagram

                       ┌─────────────────┐
                       │   Gateway Nginx │  :80  (only exposed port)
                       └────────┬────────┘
            ┌───────────┬───────┼─────────┬───────────┐
            │           │       │         │           │
        ┌───▼──┐   ┌────▼───┐   │   ┌─────▼──┐   ┌────▼─────┐
        │ auth │   │catalog │   │   │  cart  │   │  orders  │
        │ 3004 │   │  3001  │   │   │  3002  │   │   3003   │
        └───┬──┘   └────┬───┘   │   └────┬───┘   └────┬─────┘
            │           │       │        │            │
       ┌────▼────┐  ┌───▼────┐  │   ┌────▼────┐  ┌────▼────┐
       │ auth_db │  │catalog │  │   │  redis  │  │orders_db│
       │  (PG)   │  │db (PG) │  │   │  (KV)   │  │  (PG)   │
       └─────────┘  └────────┘  │   └─────────┘  └─────────┘
                       ┌────────▼────────┐
                       │ frontend (Next) │  :3000
                       └─────────────────┘

Services and Responsibilities

8 containers in total: gateway, frontend, 4 microservices, 3 PostgreSQL, and 1 Redis.

Tech Stack

• Backend: Node.js + TypeScript, Express, Prisma ORM, Zod (validation).
• Frontend: Next.js 15 (App Router), React 19, Tailwind CSS 3, Radix UI, lucide-react.
• Databases: PostgreSQL 16 (auth, catalog, orders — one per service) and Redis 7 (cart).
• Gateway: Nginx (reverse proxy).
• Orchestration: Docker Compose.

Key Features

True database-per-service

Every stateful service has its own PostgreSQL instance (auth_db, catalog_db, orders_db), removing shared-database coupling. The schema is applied via Prisma when each container starts.

Orchestrated checkout flow

The orders service orchestrates the purchase transaction:

1. Reads the user's cart by calling cart (fetchCart).
2. Decrements stock item by item by calling catalog (decrementStock).
3. Persists the order with its items into orders_db.
4. Clears the cart by calling cart (clearCart).

Ephemeral Redis cart

The cart lives in Redis under the key cart:{userId} with a 7-day TTL and no disk persistence: lightweight, fast, and disposable by design.

Shared-secret JWT auth

The JWT_SECRET is shared via environment variable across auth, cart, and orders, so any service can verify tokens without calling back to auth.

Technical Highlights

• Gateway as the only surface: The frontend never calls services directly — everything goes through Nginx, routed by prefix (/api/<service>/).
• Cascading health checks: The gateway depends on all 4 microservices being healthy; each service waits for its database to be healthy before starting.
• Auto-seeded catalog: Seeds 12 products automatically on first boot (idempotent).
• Validation as a boundary: Zod validates input in each service before touching the database.
• Uniform error handling: AppError + error middleware → consistent { success, data, error } responses.

Main Endpoints

Data Model

• auth_db → User (id, email, passwordHash, createdAt).
• catalog_db → Product (id, name, price, imageUrl, stock, category).
• orders_db → Order (status PENDING → CONFIRMED → SHIPPED → DELIVERED / CANCELLED) and OrderItem.
• redis → per-user carts, no persistence.

How to Run

cp .env.example .env
docker compose up --build

The app becomes available at http://localhost (or http://localhost:${GATEWAY_PORT}).

Project Structure

shopflow-microservices/
├── docker-compose.yml        # Orchestrates the 8 containers
├── gateway/                  # Nginx (reverse proxy)
├── frontend/                 # Next.js 15 (login, catalog, cart, orders)
└── services/
    ├── auth/                 # Express + Prisma → auth_db
    ├── catalog/              # Express + Prisma → catalog_db
    ├── cart/                 # Express + ioredis → redis
    └── orders/               # Express + Prisma → orders_db (checkout orchestrator)

Notes

This report reflects the current architecture with independent databases per service (auth, catalog, and orders), internal HTTP communication over Docker, and an Nginx gateway as the single entry point. The design emphasizes decoupling, health checks, and a uniform API contract across all services.

ShopFlow — Luis Felipe Giraldo Ortega