@eventcatalog/create-eventcatalog 4.3.3 → 4.3.4

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

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

@@ -0,0 +1,53 @@
+---
+id: warehouse-service
+version: 1.0.0
+name: Warehouse Service
+summary: |
+  Orchestrates picking and packing in the warehouse. It reacts to completed orders, creates picking jobs, and signals when an order is ready to ship.
+styles:
+  icon: /icons/languages/java.svg
+owners:
+  - fulfilment-platform
+receives:
+  - id: order-completed
+    version: 1.0.0
+sends:
+  - id: order-ready-for-shipping
+    version: 1.0.0
+writesTo:
+  - id: warehouse-database
+readsFrom:
+  - id: warehouse-database
+repository:
+  language: Java
+  url: 'https://github.com/acme/warehouse-service'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **Warehouse Service** runs warehousing. When the Ordering domain publishes [[event|order-completed]], it creates a picking job in the [[container|warehouse-database]] for the [[service|picking-worker]] to work through. Once the order is packed it publishes [[event|order-ready-for-shipping]] for the [[system|shipping-system]].
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Ready-for-shipping signal"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Completed orders to fulfil"
+  />
+</Tiles>
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={8} />
+
+<Footer />

package/templates/default/domains/Fulfilment/ubiquitous-language.mdx

@@ -0,0 +1,44 @@
+---
+dictionary:
+  - id: Fulfilment
+    name: Fulfilment
+    summary: 'Everything that gets a confirmed order physically to the customer — stock, packing and shipping.'
+    icon: PackageCheck
+  - id: Stock
+    name: Stock
+    summary: 'The quantity of a product physically available to sell.'
+    description: |
+      Stock is owned by the Inventory System. Each product has an available quantity and a reserved
+      quantity. Stock is the source of truth for whether an order can be fulfilled.
+    icon: Boxes
+  - id: Reservation
+    name: Reservation
+    summary: 'A temporary hold on stock for a specific order, taken during checkout.'
+    description: |
+      A reservation guarantees stock is set aside for an order while payment is taken. It is held,
+      then either consumed when the order ships or released if checkout fails.
+    icon: BookmarkCheck
+  - id: Picking
+    name: Picking
+    summary: "Collecting an order's items from the warehouse shelves."
+    icon: Hand
+  - id: Packing
+    name: Packing
+    summary: 'Boxing up a picked order into one or more parcels ready for shipping.'
+    icon: Package
+  - id: Shipment
+    name: Shipment
+    summary: 'A packed order handed to a carrier for delivery, tracked from dispatch to delivery.'
+    description: |
+      A shipment is created with an external carrier once an order is packed. Its lifecycle —
+      created, delivered or failed — is reported back by the carrier.
+    icon: Truck
+  - id: Carrier
+    name: Carrier
+    summary: 'The external delivery company that transports shipments to customers.'
+    icon: Globe
+  - id: Tracking Number
+    name: Tracking Number
+    summary: "A code from the carrier that lets the customer follow a shipment's progress."
+    icon: ScanBarcode
+---

package/templates/default/domains/Ordering/entities/checkout-session/index.mdx

@@ -0,0 +1,36 @@
+---
+id: checkout-session
+name: Checkout Session
+version: 1.0.0
+identifier: checkoutSessionId
+aggregateRoot: true
+summary: The orchestration state for turning a checked-out cart into an order.
+owners:
+  - ordering-platform
+properties:
+  - name: checkoutSessionId
+    type: UUID
+    required: true
+    description: Unique checkout session identifier.
+  - name: cartId
+    type: UUID
+    required: true
+    description: Cart being checked out.
+    references: cart
+    relationType: startsFrom
+    referencesIdentifier: cartId
+  - name: status
+    type: string
+    required: true
+    description: Current checkout state.
+  - name: startedAt
+    type: datetime
+    required: true
+    description: Time checkout orchestration started.
+---
+
+## Overview
+
+Checkout Session tracks the saga managed by [[service|checkout-orchestrator]] across inventory reservation, payment authorization and order creation.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order/index.mdx

@@ -0,0 +1,36 @@
+---
+id: order
+name: Order
+version: 1.0.0
+identifier: orderId
+aggregateRoot: true
+summary: The durable customer order created after successful checkout.
+owners:
+  - ordering-platform
+properties:
+  - name: orderId
+    type: UUID
+    required: true
+    description: Unique order identifier.
+  - name: customerId
+    type: UUID
+    required: true
+    description: Customer who placed the order.
+    references: customer-profile
+    relationType: belongsTo
+    referencesIdentifier: customerId
+  - name: status
+    type: string
+    required: true
+    description: Current order lifecycle state.
+  - name: totalAmount
+    type: decimal
+    required: true
+    description: Total order value at creation.
+---
+
+## Overview
+
+Order is the main aggregate in [[system|order-management-system]]. It emits order lifecycle events used by Fulfilment and support workflows.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order-line/index.mdx

@@ -0,0 +1,38 @@
+---
+id: order-line
+name: Order Line
+version: 1.0.0
+identifier: orderLineId
+summary: A purchased product and quantity within an order.
+owners:
+  - ordering-platform
+properties:
+  - name: orderLineId
+    type: UUID
+    required: true
+    description: Unique order line identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order this line belongs to.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product purchased.
+    references: product
+    relationType: references
+    referencesIdentifier: productId
+  - name: quantity
+    type: integer
+    required: true
+    description: Quantity purchased.
+---
+
+## Overview
+
+Order Line snapshots the products bought at checkout. It should not replace the Catalog domain's authoritative product data.
+
+<EntityPropertiesTable />

package/templates/default/domains/Ordering/entities/order-status-history/index.mdx

@@ -0,0 +1,35 @@
+---
+id: order-status-history
+name: Order Status History
+version: 1.0.0
+identifier: orderStatusHistoryId
+summary: Audit history of order lifecycle state changes.
+owners:
+  - ordering-platform
+properties:
+  - name: orderStatusHistoryId
+    type: UUID
+    required: true
+    description: Unique status history record.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order whose status changed.
+    references: order
+    relationType: belongsTo
+    referencesIdentifier: orderId
+  - name: status
+    type: string
+    required: true
+    description: New order status.
+  - name: changedAt
+    type: datetime
+    required: true
+    description: Time the status changed.
+---
+
+## Overview
+
+Order Status History provides an audit trail for customer support, fulfilment exceptions and order lifecycle debugging.
+
+<EntityPropertiesTable />