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

package/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/openapi.yml

@@ -0,0 +1,164 @@
+openapi: 3.0.3
+info:
+  title: Customer API
+  version: 1.0.0
+  description: |
+    Public-facing API for the Customer Management System. It is the entry point
+    for registering, updating and reading customers. Every change is persisted
+    to the customer database and published as a customer change event.
+  contact:
+    name: Customer Platform
+    email: customer-platform@acme.test
+servers:
+  - url: https://api.acme.test
+    description: Production
+tags:
+  - name: Customers
+    description: Manage and read customer profiles.
+paths:
+  /customers:
+    post:
+      operationId: registerCustomer
+      summary: Register a customer
+      description: Registers a new customer. On success a `CustomerRegistered` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RegisterCustomerRequest'
+      responses:
+        '201':
+          description: The customer was registered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '409':
+          description: A customer with the same email already exists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /customers/{customerId}:
+    parameters:
+      - name: customerId
+        in: path
+        required: true
+        description: Unique identifier of the customer.
+        schema:
+          type: string
+          format: uuid
+    get:
+      operationId: getCustomer
+      summary: Get a customer
+      description: Returns the current state of a single customer by their identifier.
+      tags:
+        - Customers
+      responses:
+        '200':
+          description: The customer was found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    patch:
+      operationId: updateCustomer
+      summary: Update a customer
+      description: Applies a partial update to an existing customer. On success a `CustomerUpdated` event is published.
+      tags:
+        - Customers
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateCustomerRequest'
+      responses:
+        '200':
+          description: The customer was updated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Customer'
+        '400':
+          description: The request body was invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          description: No customer exists with that identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+components:
+  schemas:
+    Customer:
+      type: object
+      required: [customerId, email, status]
+      properties:
+        customerId:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+        registeredAt:
+          type: string
+          format: date-time
+    RegisterCustomerRequest:
+      type: object
+      required: [email, password]
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        password:
+          type: string
+          minLength: 8
+    UpdateCustomerRequest:
+      type: object
+      description: Only the fields supplied are changed.
+      minProperties: 1
+      properties:
+        email:
+          type: string
+          format: email
+        name:
+          type: string
+          minLength: 1
+        status:
+          type: string
+          enum: [ACTIVE, SUSPENDED, CLOSED]
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+        message:
+          type: string

package/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/index.mdx

@@ -0,0 +1,32 @@
+---
+id: get-customer
+name: Get Customer
+version: 1.0.0
+summary: |
+  Query to fetch a single customer by their identifier.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: GET
+  path: /customers/{customerId}
+  statusCodes: ['200', '404']
+sidebar:
+  badge: 'GET'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`GetCustomer` is handled by the [[service|customer-api]]. It returns the current state of a single customer, read directly from the [[container|customer-database]].
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Customer/systems/customer-management-system/services/CustomerAPI/queries/GetCustomer/schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "GetCustomer",
+  "description": "Query to fetch a single customer by their identifier, and the customer returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "Parameters used to look up the customer",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "description": "Unique identifier of the customer to fetch",
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "required": ["customerId"]
+    },
+    "response": {
+      "description": "The customer returned by the query",
+      "type": "object",
+      "properties": {
+        "customerId": {
+          "type": "string",
+          "format": "uuid"
+        },
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "name": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["ACTIVE", "SUSPENDED", "CLOSED"]
+        },
+        "registeredAt": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "required": ["customerId", "email", "status"]
+    }
+  },
+  "required": ["request", "response"]
+}

package/templates/default/domains/Customer/systems/identity-provider/containers/user-directory/index.mdx

@@ -0,0 +1,36 @@
+---
+id: user-directory
+name: User Directory
+version: 1.0.0
+summary: The directory of customer credentials and identities — the source of truth for authentication.
+container_type: database
+technology: postgres@16
+authoritative: true
+access_mode: readWrite
+purpose: System of record for credentials and login identities
+classification: regulated
+retention: indefinite
+residency: eu-west-1
+styles:
+  icon: /icons/database/postgresql.svg
+---
+
+<NodeGraph />
+
+### What is this?
+
+The **User Directory** is the authoritative store for customer credentials and login identities. The [[service|oauth-api]] reads from it to verify sign-in attempts. It holds **only** authentication data — customer profile data lives separately in the [[system|customer-management-system]]'s [[container|customer-database]].
+
+### What does it store?
+
+- **Identities** — one record per customer: the login email and a securely hashed credential.
+- **Login metadata** — last login time, multi-factor settings, lockout state.
+
+### Why is it separate from the customer profile?
+
+Keeping credentials in a dedicated, **regulated**-classification store isolates the most sensitive data from general profile data. Authentication is owned by the Identity Provider; the Customer Management System never sees raw credentials.
+
+### Security
+
+- Credentials are stored only as salted, hashed values — never in plaintext.
+- Access is tightly restricted to the [[service|oauth-api]] under least-privilege roles.

package/templates/default/domains/Customer/systems/identity-provider/index.mdx

@@ -0,0 +1,54 @@
+---
+id: identity-provider
+name: Identity Provider
+version: 1.0.0
+summary: |
+  The identity system that authenticates customers. It is the source of truth for credentials and login, verifies sign-in attempts, and emits an event when a customer successfully authenticates.
+scope: external
+owners:
+  - customer-platform
+services:
+  - id: oauth-api
+containers:
+  - id: user-directory
+relationships:
+  - id: customer-management-system
+    label: provides authentication for
+actors:
+  - id: customer
+    name: Customer
+    label: signs in
+    direction: inbound
+badges:
+  - content: Identity
+    backgroundColor: purple
+    textColor: purple
+    icon: LockClosedIcon
+---
+
+## Overview
+
+The **Identity Provider** authenticates customers for Acme Inc. It exposes an OAuth-style API, verifies credentials against the [[container|user-directory]], and emits a [[event|customer-authenticated]] event on a successful sign-in so other systems can react. It provides authentication for the [[system|customer-management-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\|oauth-api]]        | Service    | OAuth-style authentication API. Handles authentication requests and publishes authentication events. |
+| [[container\|user-directory]] | Data store | The directory of customer credentials and identities.                                                |
+
+## Messages this system publishes
+
+- [[event|customer-authenticated]] — a customer has successfully authenticated.

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/index.mdx

@@ -0,0 +1,32 @@
+---
+id: authenticate-customer
+name: Authenticate Customer
+version: 1.0.0
+summary: |
+  Command to authenticate a customer with their credentials.
+owners:
+  - customer-platform
+schemaPath: schema.json
+operation:
+  method: POST
+  path: /oauth/token
+  statusCodes: ['200', '400', '401']
+sidebar:
+  badge: 'POST'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`AuthenticateCustomer` is handled by the [[service|oauth-api]]. It verifies the supplied credentials against the [[container|user-directory]] and, on success, returns an access token and publishes a [[event|customer-authenticated]] event.
+
+## Architecture diagram
+
+<NodeGraph />
+
+## Schema
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+<Footer />

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/commands/AuthenticateCustomer/schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AuthenticateCustomer",
+  "description": "Command to authenticate a customer with their credentials, and the token returned",
+  "type": "object",
+  "properties": {
+    "request": {
+      "description": "The credentials to authenticate",
+      "type": "object",
+      "properties": {
+        "email": {
+          "type": "string",
+          "format": "email"
+        },
+        "password": {
+          "type": "string"
+        }
+      },
+      "required": ["email", "password"]
+    },
+    "response": {
+      "description": "The access token issued on a successful sign-in",
+      "type": "object",
+      "properties": {
+        "accessToken": {
+          "type": "string"
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["Bearer"]
+        },
+        "expiresIn": {
+          "description": "Token lifetime in seconds",
+          "type": "integer"
+        }
+      },
+      "required": ["accessToken", "tokenType", "expiresIn"]
+    }
+  },
+  "required": ["request", "response"]
+}

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/index.mdx

@@ -0,0 +1,29 @@
+---
+id: customer-authenticated
+name: Customer Authenticated
+version: 1.0.0
+summary: |
+  Published when a customer has successfully authenticated.
+owners:
+  - customer-platform
+badges:
+  - content: 'Broker:Kafka'
+    backgroundColor: blue
+    textColor: blue
+    icon: BoltIcon
+schemaPath: schema.json
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+`CustomerAuthenticated` is published by the [[service|oauth-api]] whenever a customer successfully signs in. Other systems consume this event for auditing, session tracking, and security monitoring.
+
+<SchemaViewer file="schema.json" title="JSON Schema" maxHeight="500" />
+
+## Architecture diagram
+
+<NodeGraph />
+
+<Footer />

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/events/CustomerAuthenticated/schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CustomerAuthenticated",
+  "description": "Emitted when a customer successfully authenticates",
+  "type": "object",
+  "properties": {
+    "eventId": {
+      "description": "Unique identifier for this event",
+      "type": "string",
+      "format": "uuid"
+    },
+    "occurredAt": {
+      "description": "Time the customer authenticated",
+      "type": "string",
+      "format": "date-time"
+    },
+    "customerId": {
+      "description": "Unique identifier of the customer that authenticated",
+      "type": "string",
+      "format": "uuid"
+    },
+    "method": {
+      "description": "How the customer authenticated",
+      "type": "string",
+      "enum": ["PASSWORD", "SSO", "MFA"]
+    },
+    "ipAddress": {
+      "description": "IP address the sign-in came from",
+      "type": "string"
+    }
+  },
+  "required": ["eventId", "occurredAt", "customerId", "method"]
+}

package/templates/default/domains/Customer/systems/identity-provider/services/OAuthAPI/index.mdx

@@ -0,0 +1,59 @@
+---
+id: oauth-api
+version: 1.0.0
+name: OAuth API
+summary: |
+  OAuth-style authentication API for the Identity Provider. Verifies customer credentials and publishes an event when a customer successfully authenticates.
+styles:
+  icon: /icons/languages/nodejs.svg
+owners:
+  - customer-platform
+receives:
+  - id: authenticate-customer
+    version: 1.0.0
+sends:
+  - id: customer-authenticated
+    version: 1.0.0
+readsFrom:
+  - id: user-directory
+repository:
+  language: TypeScript
+  url: 'https://github.com/acme/oauth-api'
+---
+
+import Footer from '@catalog/components/footer.astro';
+
+## Overview
+
+The **OAuth API** is the authentication entry point for Acme Inc. It verifies credentials against the [[container|user-directory]] and, on a successful sign-in, publishes a [[event|customer-authenticated]] event so other systems can react.
+
+<Tiles>
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Sends ${frontmatter.sends.length} message`}
+    description="Authentication events published on successful sign-in"
+  />
+  <Tile
+    icon="BoltIcon"
+    href={`/visualiser/services/${frontmatter.id}/${frontmatter.version}`}
+    title={`Receives ${frontmatter.receives.length} message`}
+    description="Authentication requests handled by this service"
+  />
+</Tiles>
+
+### Responsibilities
+
+| Area             | Description                                                                         |
+| ---------------- | ----------------------------------------------------------------------------------- |
+| Authentication   | Handles [[command\|authenticate-customer]] and verifies credentials.                |
+| Event publishing | Emits [[event\|customer-authenticated]] on a successful sign-in.                    |
+| Credentials      | Reads from the [[container\|user-directory]] — the source of truth for credentials. |
+
+## Architecture diagram
+
+<NodeGraph />
+
+<MessageTable format="all" limit={4} />
+
+<Footer />

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

@@ -0,0 +1,48 @@
+---
+dictionary:
+  - id: Customer
+    name: Customer
+    summary: 'A person with an account at Acme Inc, identified by a unique customer id and email.'
+    description: |
+      The customer is the central concept of the Customer domain. Their profile is owned by the
+      Customer Management System, which is the source of truth for who a customer is. A customer has:
+
+      - A unique customer id and a unique email
+      - A display name
+      - An account status (ACTIVE, SUSPENDED or CLOSED)
+
+      A customer's profile data is kept deliberately separate from their credentials, which live in
+      the Identity Provider.
+    icon: User
+  - id: Identity
+    name: Identity
+    summary: 'The credentials and login information used to prove a customer is who they say they are.'
+    description: |
+      An identity is distinct from a customer profile. It lives in the Identity Provider's user
+      directory and holds the login email and a securely hashed credential. Keeping identity separate
+      from profile data isolates the most sensitive information.
+    icon: Fingerprint
+  - id: Authentication
+    name: Authentication
+    summary: 'Verifying that a sign-in attempt belongs to a real customer.'
+    description: |
+      Authentication is owned by the Identity Provider. It verifies credentials against the user
+      directory and, on success, issues an access token and publishes a CustomerAuthenticated event.
+    icon: LockKeyhole
+  - id: Credential
+    name: Credential
+    summary: 'A secret (such as a password) a customer uses to authenticate. Never stored in plain text.'
+    icon: KeyRound
+  - id: Account Status
+    name: Account Status
+    summary: 'Where a customer account sits: ACTIVE, SUSPENDED or CLOSED.'
+    description: |
+      - ACTIVE — the account is in good standing and can be used.
+      - SUSPENDED — temporarily blocked (e.g. for review).
+      - CLOSED — permanently deactivated.
+    icon: Workflow
+  - id: User Directory
+    name: User Directory
+    summary: 'The authoritative store of customer credentials and login identities.'
+    icon: Users
+---

package/templates/default/domains/Fulfilment/entities/inventory-reservation/index.mdx

@@ -0,0 +1,39 @@
+---
+id: inventory-reservation
+name: Inventory Reservation
+version: 1.0.0
+identifier: reservationId
+aggregateRoot: true
+summary: Stock held for a checkout or order before fulfilment.
+owners:
+  - fulfilment-platform
+properties:
+  - name: reservationId
+    type: UUID
+    required: true
+    description: Unique reservation identifier.
+  - name: orderId
+    type: UUID
+    required: false
+    description: Order associated with the reservation once created.
+    references: order
+    relationType: reservedFor
+    referencesIdentifier: orderId
+  - name: productId
+    type: UUID
+    required: true
+    description: Product being reserved.
+    references: product
+    relationType: reserves
+    referencesIdentifier: productId
+  - name: expiresAt
+    type: datetime
+    required: true
+    description: Time the reservation expires if not committed.
+---
+
+## Overview
+
+Inventory Reservation is created during checkout by [[command|reserve-inventory]] and released if the saga fails.
+
+<EntityPropertiesTable />

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

@@ -0,0 +1,36 @@
+---
+id: shipment
+name: Shipment
+version: 1.0.0
+identifier: shipmentId
+aggregateRoot: true
+summary: A carrier delivery for a packed customer order.
+owners:
+  - fulfilment-platform
+properties:
+  - name: shipmentId
+    type: UUID
+    required: true
+    description: Unique shipment identifier.
+  - name: orderId
+    type: UUID
+    required: true
+    description: Order being shipped.
+    references: order
+    relationType: ships
+    referencesIdentifier: orderId
+  - name: carrierReference
+    type: string
+    required: false
+    description: External carrier tracking reference.
+  - name: status
+    type: string
+    required: true
+    description: Shipment delivery status.
+---
+
+## Overview
+
+Shipment is created by the Shipping System and updated from carrier events such as [[event|shipment-created]] and [[event|shipment-delivered]].
+
+<EntityPropertiesTable />