@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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"]
+}

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

@@ -0,0 +1,29 @@
+---
+id: inventory-unavailable
+name: Inventory Unavailable
+version: 1.0.0
+summary: |
+  Published when stock could not be 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
+
+`InventoryUnavailable` is published by the [[service|inventory-service]] when stock for an order cannot be reserved. The Ordering domain's checkout saga uses it to fail checkout and cancel 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/InventoryUnavailable/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "InventoryUnavailable",
+  "description": "Published when stock could not be reserved for an order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "cartId": { "type": "string", "format": "uuid" },
+    "unavailableItems": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "productId": { "type": "string", "format": "uuid" },
+          "requested": { "type": "integer", "minimum": 1 },
+          "available": { "type": "integer", "minimum": 0 }
+        },
+        "required": ["productId", "requested", "available"]
+      }
+    },
+    "checkedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["unavailableItems", "checkedAt"]
+}

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

@@ -0,0 +1,67 @@
+---
+id: inventory-service
+version: 1.0.0
+name: Inventory Service
+summary: |
+  The system of record for stock. Reserves and releases inventory, serves stock-level queries, and publishes events when stock is reserved or unavailable.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: reserve-inventory
+    version: 1.0.0
+  - id: release-inventory
+    version: 1.0.0
+  - id: get-stock-level
+    version: 1.0.0
+sends:
+  - id: inventory-reserved
+    version: 1.0.0
+  - id: inventory-unavailable
+    version: 1.0.0
+writesTo:
+  - id: inventory-database
+readsFrom:
+  - id: inventory-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/inventory-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Inventory Service** is the heart of the Inventory System. It receives [[command|reserve-inventory]] during checkout and replies with [[event|inventory-reserved]] or [[event|inventory-unavailable]]. It also handles [[command|release-inventory]] and serves [[query|get-stock-level]] reads, all backed by the [[container|inventory-database]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} messages`}
+    description="Inventory outcomes"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} messages`}
+    description="Inventory commands and queries"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                   |
+| ---------------- | ----------------------------------------------------------------------------- |
+| Reservations     | Handles [[command\|reserve-inventory]] and [[command\|release-inventory]].    |
+| Lookups          | Serves [[query\|get-stock-level]] from the [[container\|inventory-database]]. |
+| Event publishing | Emits [[event\|inventory-reserved]] and [[event\|inventory-unavailable]].     |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/index.mdx

@@ -0,0 +1,32 @@
+---
+id: get-stock-level
+name: Get Stock Level
+version: 1.0.0
+summary: |
+  Query to fetch the current available stock level for a product.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /stock/{productId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetStockLevel` is handled by the [[service|inventory-service]]. It returns the current available stock for a product, read directly from the [[container|inventory-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/inventory-system/services/InventoryService/queries/GetStockLevel/schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetStockLevel",
+  "description": "Query to fetch the current available stock level for a product, and the level returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" }
+      },
+      "required": ["productId"]
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "productId": { "type": "string", "format": "uuid" },
+        "available": { "type": "integer", "minimum": 0 },
+        "reserved": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["productId", "available"]
+    }
+  },
+  "required": ["request", "response"]
+}

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

@@ -0,0 +1,47 @@
+---
+id: shipping-system
+name: Shipping System
+version: 1.0.0
+summary: |
+  Internal system that hands packed orders to carriers. It reacts to ready-for-shipping orders and creates shipments with an external carrier.
+owners:
+  - fulfilment-platform
+services:
+  - id: shipping-api
+  - id: carrier-adapter
+relationships:
+  - id: carrier
+    label: creates shipments with
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Shipping System** connects Acme Inc to its carriers. When the [[system|warehouse-system]] publishes [[event|order-ready-for-shipping]], the [[service|shipping-api]] selects a carrier and the [[service|carrier-adapter]] sends a [[command|create-shipment]] to the external [[system|carrier]] to dispatch the parcel.
+
+## 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\|shipping-api]]    | Service | Receives ready-for-shipping orders and selects a carrier.       |
+| [[service\|carrier-adapter]] | Service | Translates and sends shipment requests to the external carrier. |
+
+## Messages this system sends
+
+- [[command\|create-shipment]] — create a shipment with the carrier.

package/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/index.mdx

@@ -0,0 +1,32 @@
+---
+id: create-shipment
+name: Create Shipment
+version: 1.0.0
+summary: |
+  Command to create a shipment with a carrier for a packed order.
+owners:
+  - fulfilment-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /shipments
+  statusCodes: ['201', '400', '422']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CreateShipment` is sent by the [[service|carrier-adapter]] to the external [[system|carrier]] to dispatch a packed order. The carrier responds asynchronously with [[event|shipment-created]] and later [[event|shipment-delivered]] or [[event|shipment-failed]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/shipping-system/services/CarrierAdapter/commands/CreateShipment/schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CreateShipment",
+  "description": "Command to create a shipment with a carrier for a packed order",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "carrier": { "type": "string", "description": "The carrier to ship with" },
+    "service": {
+      "type": "string",
+      "enum": ["STANDARD", "EXPRESS", "NEXT_DAY"]
+    },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "destination": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    }
+  },
+  "required": ["orderId", "destination"]
+}