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

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

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

@@ -0,0 +1,40 @@
+---
+id: carrier-adapter
+version: 1.0.0
+name: Carrier Adapter
+summary: |
+  Translates Acme Inc shipment requests into the external carrier's format and sends them to create a shipment.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: create-shipment
+    version: 1.0.0
+repository:
+  language: Go
+  url: 'https://github.com/acme/carrier-adapter'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Carrier Adapter** is the anti-corruption layer between Acme Inc and its carriers. It takes a shipment request from the [[service|shipping-api]], maps it to the external [[system|carrier]]'s API, and sends a [[command|create-shipment]] to dispatch the parcel.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="The create-shipment command"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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

@@ -0,0 +1,40 @@
+---
+id: shipping-api
+version: 1.0.0
+name: Shipping API
+summary: |
+  Receives ready-for-shipping orders, selects a carrier, and kicks off shipment creation.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/shipping-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Shipping API** is the entry point to the Shipping System. It consumes [[event|order-ready-for-shipping]] from the [[system|warehouse-system]], selects an appropriate carrier, and hands off to the [[service|carrier-adapter]] to create the shipment.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Ready-for-shipping orders"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

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

@@ -0,0 +1,35 @@
+---
+id: warehouse-database
+name: Warehouse Database
+version: 1.0.0
+summary: PostgreSQL database that stores picking jobs and their status.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for picking and packing jobs
+classification: internal
+retention: 1y
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **Warehouse Database** stores the picking and packing jobs for the warehouse. The [[service|warehouse-service]] creates jobs and the [[service|picking-worker]] updates them as orders are picked.
+
+### What does it store?
+
+- **Picking Jobs** — one row per order being fulfilled: order, status and timestamps.
+- **Picking Job Items** — the items to pick for each job.
+
+### Schema
+
+<AccordionGroup>
+  <Accordion title="Warehouse Database schema">
+    <Schema file="schema.sql" lang="sql" title="schema.sql" />
+  </Accordion>
+</AccordionGroup>

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

@@ -0,0 +1,21 @@
+-- Warehouse Database — picking and packing jobs
+
+CREATE TABLE picking_jobs (
+    job_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    order_id    UUID NOT NULL,
+    status      TEXT NOT NULL DEFAULT 'CREATED'
+                  CHECK (status IN ('CREATED', 'PICKING', 'PACKED')),
+    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE picking_job_items (
+    job_id      UUID NOT NULL REFERENCES picking_jobs (job_id) ON DELETE CASCADE,
+    product_id  UUID NOT NULL,
+    quantity    INTEGER NOT NULL CHECK (quantity > 0),
+    picked      BOOLEAN NOT NULL DEFAULT false,
+    PRIMARY KEY (job_id, product_id)
+);
+
+CREATE INDEX idx_picking_jobs_order  ON picking_jobs (order_id);
+CREATE INDEX idx_picking_jobs_status ON picking_jobs (status);

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

@@ -0,0 +1,53 @@
+---
+id: warehouse-system
+name: Warehouse System
+version: 1.0.0
+summary: |
+  Internal system that picks and packs orders in the warehouse. It reacts to completed orders, organises picking, and signals when an order is packed and ready to ship.
+owners:
+  - fulfilment-platform
+services:
+  - id: warehouse-service
+  - id: picking-worker
+containers:
+  - id: warehouse-database
+relationships:
+  - id: shipping-system
+    label: hands packed orders to
+  - id: inventory-system
+    label: consumes reserved stock from
+badges:
+  - content: Internal
+    backgroundColor: gray
+    textColor: gray
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Warehouse System** turns a completed order into a packed parcel. When the Ordering domain publishes [[event|order-completed]], the [[service|warehouse-service]] creates a picking job, the [[service|picking-worker]] works through it, and the system publishes [[event|order-packed]] and then [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+## 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\|warehouse-service]]    | Service    | Receives completed orders and orchestrates picking and packing. |
+| [[service\|picking-worker]]       | Service    | Works through picking jobs on the warehouse floor.              |
+| [[container\|warehouse-database]] | Data store | PostgreSQL store of picking jobs and their status.              |
+
+## Messages this system publishes
+
+- [[event\|order-packed]] — an order has been picked and packed.
+- [[event\|order-ready-for-shipping]] — a packed order is ready to be shipped.

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/index.mdx

@@ -0,0 +1,29 @@
+---
+id: order-packed
+name: Order Packed
+version: 1.0.0
+summary: |
+  Published when an order has been picked and packed in the warehouse.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderPacked` is published by the [[service|picking-worker]] when an order has been fully picked and packed. The [[service|warehouse-service]] consumes it to mark the order ready and publish [[event|order-ready-for-shipping]].
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/events/OrderPacked/schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderPacked",
+  "description": "Published when an order has been picked and packed in the warehouse",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "pickingJobId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "packedAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "packedAt"]
+}

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/PickingWorker/index.mdx

@@ -0,0 +1,44 @@
+---
+id: picking-worker
+version: 1.0.0
+name: Picking Worker
+summary: |
+  Works through picking jobs on the warehouse floor and signals when an order has been picked and packed.
+styles:
+  icon: /icons/languages/go.svg
+owners:
+  - fulfilment-platform
+sends:
+  - id: order-packed
+    version: 1.0.0
+readsFrom:
+  - id: warehouse-database
+writesTo:
+  - id: warehouse-database
+repository:
+  language: Go
+  url: 'https://github.com/acme/picking-worker'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Picking Worker** processes picking jobs created by the [[service|warehouse-service]]. As warehouse staff pick and pack each order, the worker updates the job in the [[container|warehouse-database]] and publishes [[event|order-packed]] when the order is complete.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="The order-packed event"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/index.mdx

@@ -0,0 +1,29 @@
+---
+id: order-ready-for-shipping
+name: Order Ready For Shipping
+version: 1.0.0
+summary: |
+  Published when a packed order is ready to be handed to a carrier for shipping.
+owners:
+  - fulfilment-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`OrderReadyForShipping` is published by the [[service|warehouse-service]] once an order has been packed. The [[system|shipping-system]] consumes it to create a shipment with a carrier.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Fulfilment/systems/warehouse-system/services/WarehouseService/events/OrderReadyForShipping/schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "OrderReadyForShipping",
+  "description": "Published when a packed order is ready to be handed to a carrier",
+  "type": "object",
+  "properties": {
+    "orderId": { "type": "string", "format": "uuid" },
+    "customerId": { "type": "string", "format": "uuid" },
+    "parcelCount": { "type": "integer", "minimum": 1 },
+    "shippingAddress": {
+      "type": "object",
+      "properties": {
+        "line1": { "type": "string" },
+        "city": { "type": "string" },
+        "postcode": { "type": "string" },
+        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
+      },
+      "required": ["line1", "city", "postcode", "country"]
+    },
+    "readyAt": { "type": "string", "format": "date-time" }
+  },
+  "required": ["orderId", "shippingAddress", "readyAt"]
+}