Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astrxnomo/shop-microservers/llms.txt

Use this file to discover all available pages before exploring further.

The Catalog service is the product database for Shop Microservers. It serves a read-only product listing to anonymous users and exposes a stock-decrement endpoint that the orders service calls internally during checkout. Product data is persisted in PostgreSQL and includes category, pricing, stock count, and an image URL. On first boot the service automatically seeds 12 sample products across five categories so the storefront is immediately populated without any manual setup.

​
Overview

Runtime

Express on port 3001 inside Docker. Gateway prefix: /api/catalog/.

Database

PostgreSQL — database name catalog_db. Schema managed by Prisma.

Authentication

No authentication required for read endpoints. The stock-update endpoint is called only by the orders service internally.

Auto-seeding

12 products are seeded idempotently on first startup via src/lib/seed.ts.

​
Endpoints

MethodPathAuthDescription
GET/productsNoneList all products
GET/products/:idNoneGet a single product by ID
PATCH/products/:id/stockNone*Decrement the stock count for a product
* The PATCH /products/:id/stock endpoint has no authentication middleware, but it is not publicly advertised to end users. It is called exclusively by the orders service over Docker’s internal network during the checkout flow. Exposing it to the public gateway is intentional for service-to-service simplicity in this architecture — production deployments should restrict it to internal traffic only.

​
Data Model

model Product {
  id        String   @id @default(cuid())
  name      String
  price     Float
  imageUrl  String
  stock     Int      @default(0)
  category  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

​
Auto-Seeding

On first boot, seedIfEmpty() in src/lib/seed.ts checks whether any products already exist. If the table is empty, it inserts all 12 products in a single createMany call: 
export async function seedIfEmpty() {
  const count = await prisma.product.count();
  if (count > 0) return;
  await prisma.product.createMany({ data: PRODUCTOS });
  console.log(`${PRODUCTOS.length} productos creados.`);
}
The 12 seed products span five categories:
CategoryProducts
ElectrónicaAuriculares Inalámbricos Pro, Teclado Mecánico RGB, Hub USB-C 7 en 1, Reloj Inteligente Serie 5, Base de Carga Inalámbrica
CalzadoZapatillas de Correr X200
AccesoriosBilletera de Cuero Slim, Mochila 30L Impermeable
Hogar y CocinaBotella Térmica Acero Inox, Molino de Café Eléctrico, Lámpara LED de Escritorio
DeportesTapete de Yoga Antideslizante

​
Stock Management

The PATCH /products/:id/stock endpoint accepts a decrement integer and reduces the stock field by that amount. The request body is validated with Zod: 
export const StockDecrementSchema = z.object({
  decrement: z.number().int().positive(),
});
The service layer guards against overselling: 
export async function decrementStock(id: string, decrement: number) {
  const product = await prisma.product.findUnique({ where: { id } });
  if (!product) throw new AppError("Product not found", 404);
  if (product.stock < decrement)
    throw new AppError("Insufficient stock", 409);
  return prisma.product.update({
    where: { id },
    data: { stock: { decrement } },
  });
}
A 409 Insufficient stock error during checkout will cause the entire order to fail. The orders service propagates this error back to the client.

​
Response Shape

All catalog responses follow the platform-wide envelope: 
{
  "success": true,
  "data": [
    {
      "id": "clxyz123",
      "name": "Auriculares Inalámbricos Pro",
      "price": 89.99,
      "imageUrl": "https://images.unsplash.com/...",
      "stock": 50,
      "category": "Electrónica",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
For single-product endpoints the data field is a single Product object rather than an array.

​
Error Cases

HTTP StatusCondition
404Product ID does not exist
409Requested decrement exceeds available stock
400Request body fails Zod validation

​
API Reference

GET /products

Retrieve all products.

GET /products/:id

Retrieve a single product by ID.

PATCH /products/:id/stock

Decrement product stock (internal).

Build docs developers (and LLMs) love

Get started for freeTalk to us