@eventcatalog/create-eventcatalog 4.3.2 → 4.3.4-beta.0

package/templates/default/domains/Fulfilment/entities/stock-item/index.mdx

@@ -0,0 +1,36 @@
+---
+id: stock-item
+name: Stock Item
+version: 1.0.0
+identifier: stockItemId
+aggregateRoot: true
+summary: The inventory record for a product variant at a location.
+owners:
+  - fulfilment-platform
+properties:
+  - name: stockItemId
+    type: UUID
+    required: true
+    description: Unique stock item identifier.
+  - name: productId
+    type: UUID
+    required: true
+    description: Product held in stock.
+    references: product
+    relationType: stocks
+    referencesIdentifier: productId
+  - name: locationId
+    type: string
+    required: true
+    description: Warehouse or fulfilment location.
+  - name: availableQuantity
+    type: integer
+    required: true
+    description: Quantity available to reserve.
+---
+
+## Overview
+
+Stock Item is the Inventory System's view of available stock for a product at a fulfilment location.
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/entities/warehouse-pick/index.mdx

@@ -0,0 +1,35 @@
+---
+id: warehouse-pick
+name: Warehouse Pick
+version: 1.0.0
+identifier: pickId
+summary: A warehouse task to pick items for a completed order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: pickId
+    type: UUID
+    required: true
+    description: Unique warehouse pick identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being picked.
+    references: order
+    relationType: fulfils
+    referencesIdentifier: orderId
+  - name: assignedTo
+    type: string
+    required: false
+    description: Warehouse worker or automation lane assigned.
+  - name: status
+    type: string
+    required: true
+    description: Pick task status.
+---
+
+## Overview
+
+Warehouse Pick represents the operational task handled by the Warehouse System before an order can be packed and shipped.
+
+<EntityPropertiesTable />

package/templates/default/domains/Fulfilment/index.mdx

@@ -0,0 +1,83 @@
+---
+id: fulfilment
+name: Fulfilment
+version: 1.0.0
+summary: |
+  The Fulfilment domain gets a confirmed order to the customer. It reserves stock, picks and packs orders in the warehouse, and hands them to carriers for delivery.
+owners:
+  - fulfilment-platform
+systems:
+  - id: inventory-system
+    version: 1.0.0
+  - id: warehouse-system
+    version: 1.0.0
+  - id: shipping-system
+    version: 1.0.0
+  - id: carrier
+    version: 1.0.0
+entities:
+  - id: stock-item
+    version: 1.0.0
+  - id: inventory-reservation
+    version: 1.0.0
+  - id: warehouse-pick
+    version: 1.0.0
+  - id: shipment
+    version: 1.0.0
+badges:
+  - content: Core domain
+    backgroundColor: blue
+    textColor: blue
+    icon: RectangleGroupIcon
+  - content: Business Critical
+    backgroundColor: red
+    textColor: red
+    icon: ShieldCheckIcon
+---
+
+## Overview
+
+The **Fulfilment** domain is responsible for the physical side of an order — making sure stock is available, picking and packing it, and shipping it to the customer. It owns three internal systems and integrates with external carriers:
+
+<Tiles>
+  <Tile
+    icon="ArchiveBoxIcon"
+    href="/docs/systems/inventory-system/1.0.0"
+    title="Inventory System"
+    description="Tracks and reserves stock for orders."
+  />
+  <Tile
+    icon="BuildingStorefrontIcon"
+    href="/docs/systems/warehouse-system/1.0.0"
+    title="Warehouse System"
+    description="Picks and packs orders ready for shipping."
+  />
+  <Tile
+    icon="TruckIcon"
+    href="/docs/systems/shipping-system/1.0.0"
+    title="Shipping System"
+    description="Hands packed orders to carriers for delivery."
+  />
+  <Tile
+    icon="GlobeAltIcon"
+    href="/docs/systems/carrier/1.0.0"
+    title="Carrier"
+    description="External carrier that delivers shipments to customers."
+  />
+</Tiles>
+
+### How the systems work together
+
+When an order is completed, the **Warehouse System** picks and packs it, having relied on the **Inventory System** to reserve stock earlier in checkout. Once packed, the **Shipping System** creates a shipment with an external **Carrier**, which delivers it to the customer and reports progress back.
+
+## System Diagram
+
+The systems in this domain, how they relate, and the people who interact with them.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The components that make up this domain.
+
+<NodeGraph />

package/templates/default/domains/Fulfilment/systems/carrier/index.mdx

@@ -0,0 +1,52 @@
+---
+id: carrier
+name: Carrier
+version: 1.0.0
+scope: external
+summary: |
+  External carrier that delivers shipments to customers. It accepts shipment requests and reports delivery progress back.
+owners:
+  - fulfilment-platform
+services:
+  - id: carrier-shipping-api
+  - id: carrier-tracking-api
+relationships:
+  - id: shipping-system
+    label: delivers shipments for
+badges:
+  - content: External
+    backgroundColor: yellow
+    textColor: yellow
+    icon: GlobeAltIcon
+---
+
+## Overview
+
+The **Carrier** is the external delivery company Acme Inc uses to ship orders to customers. It is owned and operated by a third party — modelled here as an **external system** so the catalog shows how the [[system|shipping-system]] integrates with it.
+
+It receives [[command|create-shipment]] and reports progress back via [[event|shipment-created]], [[event|shipment-delivered]] and [[event|shipment-failed]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type    | Responsibility                                    |
+| --------------------------------- | ------- | ------------------------------------------------- |
+| [[service\|carrier-shipping-api]] | Service | Accepts shipment requests and dispatches parcels. |
+| [[service\|carrier-tracking-api]] | Service | Reports delivery progress back to Acme Inc.       |
+
+## Messages this system publishes
+
+- [[event\|shipment-created]] — a shipment has been created and dispatched.
+- [[event\|shipment-delivered]] — a shipment was delivered to the customer.
+- [[event\|shipment-failed]] — a shipment could not be delivered.

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierShippingAPI/index.mdx

@@ -0,0 +1,40 @@
+---
+id: carrier-shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  The carrier's API for creating shipments. Acme Inc's Shipping System calls it to dispatch packed orders.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the carrier's external interface for creating shipments. The [[system|shipping-system]] sends [[command|create-shipment]], and the carrier dispatches the parcel and begins reporting progress through its [[service|carrier-tracking-api]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Shipment creation requests"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: shipment-created
+name: Shipment Created
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been created and dispatched.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentCreated` is published by the carrier's [[service|carrier-tracking-api]] when a shipment has been created and dispatched. Acme Inc consumes it to give the customer a tracking number and expected delivery date.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentCreated/schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentCreated",
+  "description": "Published when a shipment has been created and dispatched",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "trackingNumber": { "type": "string" },
+    "carrier": { "type": "string" },
+    "estimatedDelivery": { "type": "string", "format": "date" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "trackingNumber", "createdAt"]
+}

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/index.mdx

@@ -0,0 +1,29 @@
+---
+id: shipment-delivered
+name: Shipment Delivered
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment has been delivered to the customer.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentDelivered` is published by the carrier's [[service|carrier-tracking-api]] when a shipment reaches the customer. This is the happy-path end of the fulfilment journey — Acme Inc consumes it to close out the order and prompt the customer for feedback.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentDelivered/schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentDelivered",
+  "description": "Published when a shipment has been delivered to the customer",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "deliveredAt": { "type": "string", "format": "date-time" },
+    "signedBy": { "type": "string", "description": "Name of the person who accepted delivery, if captured" }
+  },
+  "required": ["shipmentId", "orderId", "deliveredAt"]
+}

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/index.mdx

@@ -0,0 +1,29 @@
+---
+id: shipment-failed
+name: Shipment Failed
+version: 1.0.0
+summary: |
+  Published by the carrier when a shipment could not be delivered.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ShipmentFailed` is published by the carrier's [[service|carrier-tracking-api]] when a shipment cannot be delivered — for example a failed delivery attempt or a lost parcel. Acme Inc consumes it to trigger a redelivery, refund, or customer follow-up.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/events/ShipmentFailed/schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ShipmentFailed",
+  "description": "Published when a shipment could not be delivered",
+  "type": "object",
+  "properties": {
+    "shipmentId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["FAILED_DELIVERY", "LOST", "DAMAGED", "RETURNED_TO_SENDER"]
+    },
+    "failedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["shipmentId", "orderId", "reason", "failedAt"]
+}

package/templates/default/domains/Fulfilment/systems/carrier/services/CarrierTrackingAPI/index.mdx

@@ -0,0 +1,44 @@
+---
+id: carrier-tracking-api
+version: 1.0.0
+name: Tracking API
+summary: |
+  The carrier's API for reporting delivery progress. It notifies Acme Inc when a shipment is created, delivered, or fails.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: shipment-created
+    version: 1.0.0
+  - id: shipment-delivered
+    version: 1.0.0
+  - id: shipment-failed
+    version: 1.0.0
+repository:
+  language: External
+  url: 'https://github.com/acme/carrier-integration'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Tracking API** is how the carrier reports delivery progress back to Acme Inc. After a shipment is created via the [[service|carrier-shipping-api]], it emits [[event|shipment-created]], then [[event|shipment-delivered]] on success or [[event|shipment-failed]] if delivery cannot be completed.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Shipment lifecycle events"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/index.mdx

@@ -0,0 +1,35 @@
+---
+id: inventory-database
+name: Inventory Database
+version: 1.0.0
+summary: PostgreSQL database that is the system of record for stock levels and reservations.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for stock levels and reservations
+classification: internal
+retention: 3y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Inventory Database** is the authoritative store for stock levels at Acme Inc. The [[service|inventory-service]] reads from and writes to it as stock is reserved and released.
+
+### What does it store?
+
+- **Stock** — one row per product: available quantity and reserved quantity.
+- **Reservations** — one row per reservation: id, order, items and status.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Inventory Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>

package/templates/default/domains/Fulfilment/systems/inventory-system/containers/inventory-database/schema.sql

@@ -0,0 +1,26 @@
+-- Inventory Database — system of record for stock levels and reservations
+
+CREATE TABLE stock (
+    product_id  UUID PRIMARY KEY,
+    available   INTEGER NOT NULL DEFAULT 0 CHECK (available >= 0),
+    reserved    INTEGER NOT NULL DEFAULT 0 CHECK (reserved >= 0),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservations (
+    reservation_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id       UUID,
+    cart_id        UUID,
+    status         TEXT NOT NULL DEFAULT 'HELD'
+                     CHECK (status IN ('HELD', 'RELEASED', 'CONSUMED')),
+    created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE reservation_items (
+    reservation_id UUID NOT NULL REFERENCES reservations (reservation_id) ON DELETE CASCADE,
+    product_id     UUID NOT NULL,
+    quantity       INTEGER NOT NULL CHECK (quantity > 0),
+    PRIMARY KEY (reservation_id, product_id)
+);
+
+CREATE INDEX idx_reservations_order ON reservations (order_id);

package/templates/default/domains/Fulfilment/systems/inventory-system/index.mdx

@@ -0,0 +1,49 @@
+---
+id: inventory-system
+name: Inventory System
+version: 1.0.0
+summary: |
+  Internal system that tracks stock and reserves it for orders. It is the source of truth for available inventory and confirms whether stock can be reserved.
+owners:
+  - fulfilment-platform
+services:
+  - id: inventory-service
+containers:
+  - id: inventory-database
+relationships:
+  - id: warehouse-system
+    label: provides stock for
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Inventory System** owns stock levels at Acme Inc. During checkout it receives [[command|reserve-inventory]] and confirms whether stock is available — replying with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] (when a reservation is no longer needed) and serves [[query|get-stock-level]] lookups from the [[container|inventory-database]].
+
+## Context Diagram
+
+How this system relates to the other systems around it.
+
+<ContextDiagram />
+
+## Resource Diagram
+
+The services, data stores and messages that make up this system.
+
+<NodeGraph />
+
+## What's inside
+
+| Component                         | Type       | Responsibility                                                                           |
+| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
+| [[service\|inventory-service]]    | Service    | Reserves and releases stock, serves stock-level queries, and publishes inventory events. |
+| [[container\|inventory-database]] | Data store | PostgreSQL system of record for stock levels and reservations.                           |
+
+## Messages this system publishes
+
+- [[event\|inventory-reserved]] — stock was successfully reserved for an order.
+- [[event\|inventory-unavailable]] — stock could not be reserved.

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/index.mdx

@@ -0,0 +1,32 @@
+---
+id: release-inventory
+name: Release Inventory
+version: 1.0.0
+summary: |
+  Command to release a previously held inventory reservation.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /reservations/{reservationId}/release
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`ReleaseInventory` is handled by the [[service|inventory-service]]. It releases a reservation that is no longer needed — for example when checkout fails after stock was reserved, or an order is cancelled.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/commands/ReleaseInventory/schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ReleaseInventory",
+  "description": "Command to release a previously held inventory reservation",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "reason": {
+      "type": "string",
+      "enum": ["CHECKOUT_FAILED", "ORDER_CANCELLED", "EXPIRED"]
+    }
+  },
+  "required": ["reservationId"]
+}

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/index.mdx

@@ -0,0 +1,29 @@
+---
+id: inventory-reserved
+name: Inventory Reserved
+version: 1.0.0
+summary: |
+  Published when stock has been successfully reserved for an order.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`InventoryReserved` is published by the [[service|inventory-service]] when stock for an order has been successfully reserved. The Ordering domain's checkout saga relies on this to continue placing the order.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/events/InventoryReserved/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryReserved",
+  "description": "Published when stock has been successfully reserved for an order",
+  "type": "object",
+  "properties": {
+    "reservationId": { "type": "string", "format": "uuid" },
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "quantity": { "type": "integer", "minimum": 1 }
+        },
+        "required": ["productId", "quantity"]
+      }
+    },
+    "reservedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["reservationId", "items", "reservedAt"]
+}