dsh-knowhub 0.9.0 → 0.10.0

package/skills/archify/examples/orders.erd.json

@@ -0,0 +1,337 @@
+{
+  "schema_version": 1,
+  "diagram_type": "erd",
+  "meta": {
+    "title": "Order management schema",
+    "locale": "en",
+    "output": "examples/erd-orders-rendered.html",
+    "quality_profile": "showcase",
+    "views": [
+      {
+        "id": "identity",
+        "label": "Reference rows",
+        "focus": [
+          "customer",
+          "product"
+        ],
+        "note": "The rows everything else points at, with their unique keys."
+      },
+      {
+        "id": "checkout",
+        "label": "Checkout core",
+        "focus": [
+          "order",
+          "order_item",
+          "customer"
+        ],
+        "note": "order is the hub: order_item and payment both point back at it."
+      },
+      {
+        "id": "followups",
+        "label": "Payment and stock",
+        "focus": [
+          "payment",
+          "order",
+          "inventory",
+          "product"
+        ],
+        "note": "One optional dashed link and one mandatory stock link."
+      }
+    ]
+  },
+  "layout": {
+    "mode": "grid",
+    "gapY": 38,
+    "gapX": 72
+  },
+  "entities": [
+    {
+      "id": "customer",
+      "label": "customer",
+      "tag": "accounts",
+      "row": 0,
+      "col": 0,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "email",
+          "type": "varchar(255)",
+          "key": "uk"
+        },
+        {
+          "name": "display_name",
+          "type": "varchar(120)"
+        },
+        {
+          "name": "created_at",
+          "type": "timestamptz"
+        }
+      ]
+    },
+    {
+      "id": "order",
+      "label": "order",
+      "tag": "checkout",
+      "row": 0,
+      "col": 1,
+      "width": 260,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "customer_id",
+          "type": "bigint",
+          "key": "fk",
+          "references": "customer.id"
+        },
+        {
+          "name": "status",
+          "type": "varchar(32)"
+        },
+        {
+          "name": "total_amount",
+          "type": "numeric(12,2)"
+        },
+        {
+          "name": "currency",
+          "type": "char(3)"
+        },
+        {
+          "name": "placed_at",
+          "type": "timestamptz"
+        },
+        {
+          "name": "updated_at",
+          "type": "timestamptz"
+        }
+      ]
+    },
+    {
+      "id": "order_item",
+      "label": "order_item",
+      "tag": "line items",
+      "row": 1,
+      "col": 2,
+      "width": 254,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "order_id",
+          "type": "bigint",
+          "key": "fk",
+          "references": "order.id"
+        },
+        {
+          "name": "product_id",
+          "type": "bigint",
+          "key": "fk",
+          "references": "product.id"
+        },
+        {
+          "name": "quantity",
+          "type": "int"
+        },
+        {
+          "name": "unit_price",
+          "type": "numeric(12,2)"
+        },
+        {
+          "name": "discount_amount",
+          "type": "numeric(12,2)"
+        }
+      ]
+    },
+    {
+      "id": "product",
+      "label": "product",
+      "tag": "catalog",
+      "row": 1,
+      "col": 1,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "sku",
+          "type": "varchar(64)",
+          "key": "uk"
+        },
+        {
+          "name": "name",
+          "type": "varchar(160)"
+        },
+        {
+          "name": "price",
+          "type": "numeric(12,2)"
+        },
+        {
+          "name": "cost_amount",
+          "type": "numeric(12,2)"
+        },
+        {
+          "name": "active",
+          "type": "boolean"
+        },
+        {
+          "name": "created_at",
+          "type": "timestamptz"
+        }
+      ]
+    },
+    {
+      "id": "inventory",
+      "label": "inventory",
+      "tag": "catalog",
+      "row": 1,
+      "col": 0,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "product_id",
+          "type": "bigint",
+          "key": "fk",
+          "references": "product.id"
+        },
+        {
+          "name": "warehouse_code",
+          "type": "varchar(16)"
+        },
+        {
+          "name": "quantity",
+          "type": "int"
+        },
+        {
+          "name": "reserved_quantity",
+          "type": "int"
+        },
+        {
+          "name": "updated_at",
+          "type": "timestamptz"
+        }
+      ],
+      "width": 236
+    },
+    {
+      "id": "payment",
+      "label": "payment",
+      "tag": "checkout",
+      "row": 0,
+      "col": 2,
+      "attributes": [
+        {
+          "name": "id",
+          "type": "bigint",
+          "key": "pk"
+        },
+        {
+          "name": "order_id",
+          "type": "bigint",
+          "key": "fk",
+          "references": "order.id"
+        },
+        {
+          "name": "method",
+          "type": "varchar(32)"
+        },
+        {
+          "name": "amount",
+          "type": "numeric(12,2)"
+        },
+        {
+          "name": "paid_at",
+          "type": "timestamptz"
+        },
+        {
+          "name": "external_ref",
+          "type": "varchar(64)"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "id": "order_customer",
+      "from": "order",
+      "to": "customer",
+      "label": "placed by",
+      "fromCardinality": "many",
+      "toCardinality": "one"
+    },
+    {
+      "id": "payment_order",
+      "from": "payment",
+      "to": "order",
+      "fromCardinality": "many",
+      "fromOptional": true,
+      "toCardinality": "one",
+      "identifying": false
+    },
+    {
+      "id": "order_item_order",
+      "from": "order_item",
+      "to": "order",
+      "fromCardinality": "many",
+      "toCardinality": "one"
+    },
+    {
+      "id": "order_item_product",
+      "from": "order_item",
+      "to": "product",
+      "fromCardinality": "many",
+      "toCardinality": "one"
+    },
+    {
+      "id": "inventory_product",
+      "from": "inventory",
+      "to": "product",
+      "fromCardinality": "many",
+      "toCardinality": "one"
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Keys",
+      "items": [
+        "Every child carries the parent id as a bigint foreign key.",
+        "order is the hub: order_item and payment each hold an order_id.",
+        "email and sku are unique, so they carry a secondary key marker."
+      ]
+    },
+    {
+      "dot": "amber",
+      "title": "Optionality",
+      "items": [
+        "An order may exist before any payment attempt, so the payment side is zero or many.",
+        "The payment relationship is non-identifying: it is drawn dashed.",
+        "customer, product, and order_item links are all mandatory."
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "How the bands read",
+      "items": [
+        "The checkout band is the order and the payment that settles it.",
+        "The catalog band is what orders point at: one product, one stock record.",
+        "accounts and line items stand alone; a single-table domain keeps its tag in the table header."
+      ]
+    }
+  ]
+}

package/skills/archify/examples/payment-incident.timeline.json

@@ -0,0 +1,24 @@
+{
+  "schema_version": 1,
+  "diagram_type": "timeline",
+  "meta": {
+    "title": "Payment failure incident",
+    "subtitle": "Illustrative incident: release, monitoring, and response events on one clock.",
+    "output": "payment-incident-timeline.html",
+    "evidence": "illustrative",
+    "timezone": "Asia/Shanghai",
+    "quality_profile": "showcase"
+  },
+  "lanes": [
+    { "id": "release", "label": "Release" },
+    { "id": "monitoring", "label": "Monitoring" },
+    { "id": "response", "label": "Response" }
+  ],
+  "events": [
+    { "id": "deploy", "at": "2026-10-01T10:00:00+08:00", "title": "Deploy v2.4", "detail": "New version starts serving payment requests.", "lane": "release", "kind": "change" },
+    { "id": "alert", "at": "2026-10-01T10:05:00+08:00", "title": "Payment failure alert", "detail": "Error rate on /pay rises above the paging threshold.", "lane": "monitoring", "kind": "alert" },
+    { "id": "rollback", "at": "2026-10-01T10:10:00+08:00", "title": "Start rollback", "detail": "On-call decides to return to v2.3.", "lane": "response", "kind": "action" },
+    { "id": "recovered", "at": "2026-10-01T10:15:00+08:00", "title": "Metrics recovered", "detail": "Payment success rate back to baseline.", "lane": "monitoring", "kind": "recovery" },
+    { "id": "closed", "at": "2026-10-01T10:20:00+08:00", "title": "Incident closed", "detail": "Stability confirmed; response ends.", "lane": "response", "kind": "action" }
+  ]
+}

package/skills/archify/examples/payment-platform.tree.json

@@ -0,0 +1,22 @@
+{
+  "schema_version": 1,
+  "diagram_type": "tree",
+  "meta": {
+    "title": "Payment platform capabilities",
+    "subtitle": "Illustrative decomposition: each capability belongs to exactly one parent. Links show containment, not calls.",
+    "output": "payment-platform-tree.html",
+    "quality_profile": "showcase"
+  },
+  "nodes": [
+    { "id": "platform", "label": "Payment platform", "sublabel": "Decomposed by capability" },
+    { "id": "orders", "label": "Orders", "parent": "platform", "sublabel": "Order lifecycle" },
+    { "id": "payments", "label": "Payments", "parent": "platform", "sublabel": "Money movement" },
+    { "id": "operations", "label": "Operations", "parent": "platform", "sublabel": "Back-office work" },
+    { "id": "create_order", "label": "Create order", "parent": "orders" },
+    { "id": "cancel_order", "label": "Cancel order", "parent": "orders" },
+    { "id": "card_payment", "label": "Card payment", "parent": "payments" },
+    { "id": "wallet_payment", "label": "Wallet payment", "parent": "payments" },
+    { "id": "refunds", "label": "Refund handling", "parent": "operations" },
+    { "id": "reconciliation", "label": "Transaction reconciliation", "parent": "operations" }
+  ]
+}

package/skills/archify/examples/payment-processors.class.json

@@ -0,0 +1,177 @@
+{
+  "schema_version": 1,
+  "diagram_type": "class",
+  "meta": {
+    "title": "Payment processor hierarchy",
+    "subtitle": "Illustrative module: one processor contract, a retrying base class, and five provider implementations.",
+    "output": "payment-processors-class.html",
+    "quality_profile": "showcase"
+  },
+  "layout": {
+    "mode": "grid"
+  },
+  "types": [
+    {
+      "id": "checkout_orchestrator",
+      "label": "CheckoutOrchestrator",
+      "kind": "class",
+      "sublabel": "Runs one checkout from order to receipt",
+      "row": 0,
+      "col": 0,
+      "attributes": [
+        { "name": "registry", "type": "ProcessorRegistry", "visibility": "private" },
+        { "name": "clock", "type": "Clock", "visibility": "private" }
+      ],
+      "methods": [
+        { "name": "checkout", "parameters": "order: Order, key: IdempotencyKey", "returns": "CheckoutResult", "visibility": "public" },
+        { "name": "cancelPendingAuthorization", "parameters": "orderId: OrderId", "returns": "void", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "processor_registry",
+      "label": "ProcessorRegistry",
+      "kind": "class",
+      "sublabel": "Selects a processor for a payment method",
+      "row": 0,
+      "col": 1,
+      "attributes": [
+        { "name": "processors", "type": "Map<MethodType, PaymentProcessor>", "visibility": "private" }
+      ],
+      "methods": [
+        { "name": "processorFor", "parameters": "method: PaymentMethod", "returns": "PaymentProcessor", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "payment_processor",
+      "label": "PaymentProcessor",
+      "kind": "interface",
+      "sublabel": "Authorize, capture, and refund contract",
+      "row": 0,
+      "col": 2.5,
+      "methods": [
+        { "name": "authorize", "parameters": "request: AuthorizationRequest", "returns": "AuthorizationResult", "visibility": "public", "abstract": true },
+        { "name": "capture", "parameters": "authorization: AuthorizationId, amount: Money", "returns": "CaptureResult", "visibility": "public", "abstract": true },
+        { "name": "refund", "parameters": "capture: CaptureId, amount: Money", "returns": "RefundResult", "visibility": "public", "abstract": true }
+      ]
+    },
+    {
+      "id": "order",
+      "label": "Order",
+      "kind": "class",
+      "sublabel": "Aggregate root for one purchase",
+      "row": 1,
+      "col": 0,
+      "attributes": [
+        { "name": "id", "type": "OrderId", "visibility": "public" },
+        { "name": "total", "type": "Money", "visibility": "public" },
+        { "name": "status", "type": "PaymentStatus", "visibility": "public" }
+      ],
+      "methods": [
+        { "name": "addLine", "parameters": "sku: Sku, quantity: int", "returns": "LineItem", "visibility": "public" },
+        { "name": "markAuthorized", "parameters": "authorization: AuthorizationId", "returns": "void", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "payment_status",
+      "label": "PaymentStatus",
+      "kind": "enum",
+      "sublabel": "Lifecycle of the order's payment",
+      "row": 1,
+      "col": 1,
+      "attributes": [
+        { "name": "PENDING" },
+        { "name": "AUTHORIZED" },
+        { "name": "CAPTURED" },
+        { "name": "REFUNDED" },
+        { "name": "FAILED" }
+      ]
+    },
+    {
+      "id": "retrying_processor",
+      "label": "RetryingProcessorBase",
+      "kind": "abstract",
+      "sublabel": "Shared retry, timeout, and idempotency handling",
+      "row": 1,
+      "col": 2,
+      "attributes": [
+        { "name": "DEFAULT_TIMEOUT", "type": "Duration", "visibility": "public", "static": true },
+        { "name": "retryPolicy", "type": "RetryPolicy", "visibility": "protected" }
+      ],
+      "methods": [
+        { "name": "authorize", "parameters": "request: AuthorizationRequest", "returns": "AuthorizationResult", "visibility": "public" },
+        { "name": "sendToProvider", "parameters": "request: ProviderRequest", "returns": "ProviderResponse", "visibility": "protected", "abstract": true }
+      ]
+    },
+    {
+      "id": "bank_transfer",
+      "label": "BankTransferProcessor",
+      "kind": "class",
+      "sublabel": "Asynchronous transfer without provider retries",
+      "row": 1,
+      "col": 3,
+      "methods": [
+        { "name": "authorize", "parameters": "request: AuthorizationRequest", "returns": "AuthorizationResult", "visibility": "public" },
+        { "name": "awaitSettlement", "parameters": "transfer: TransferId", "returns": "SettlementResult", "visibility": "private" }
+      ]
+    },
+    {
+      "id": "line_item",
+      "label": "LineItem",
+      "kind": "record",
+      "sublabel": "Immutable priced order line",
+      "row": 2,
+      "col": 0,
+      "attributes": [
+        { "name": "sku", "type": "Sku", "visibility": "public" },
+        { "name": "quantity", "type": "int", "visibility": "public" },
+        { "name": "unitPrice", "type": "Money", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "stripe_card",
+      "label": "StripeCardProcessor",
+      "kind": "class",
+      "sublabel": "Card payments through Stripe",
+      "row": 2,
+      "col": 1,
+      "methods": [
+        { "name": "sendToProvider", "parameters": "request: ProviderRequest", "returns": "ProviderResponse", "visibility": "protected" }
+      ]
+    },
+    {
+      "id": "adyen_card",
+      "label": "AdyenCardProcessor",
+      "kind": "class",
+      "sublabel": "Card payments through Adyen",
+      "row": 2,
+      "col": 2,
+      "methods": [
+        { "name": "sendToProvider", "parameters": "request: ProviderRequest", "returns": "ProviderResponse", "visibility": "protected" }
+      ]
+    },
+    {
+      "id": "paypal_wallet",
+      "label": "PayPalWalletProcessor",
+      "kind": "class",
+      "sublabel": "Wallet payments through PayPal",
+      "row": 2,
+      "col": 3,
+      "methods": [
+        { "name": "sendToProvider", "parameters": "request: ProviderRequest", "returns": "ProviderResponse", "visibility": "protected" },
+        { "name": "exchangeBillingAgreementToken", "parameters": "token: String", "returns": "AgreementId", "visibility": "private" }
+      ]
+    }
+  ],
+  "relationships": [
+    { "id": "orchestrator_registry", "from": "checkout_orchestrator", "to": "processor_registry", "kind": "association", "label": "selects via" },
+    { "id": "registry_processors", "from": "processor_registry", "to": "payment_processor", "kind": "aggregation", "label": "holds" },
+    { "id": "orchestrator_order", "from": "checkout_orchestrator", "to": "order", "kind": "dependency", "label": "updates" },
+    { "id": "order_lines", "from": "order", "to": "line_item", "kind": "composition", "label": "owns lines" },
+    { "id": "order_status", "from": "order", "to": "payment_status", "kind": "association" },
+    { "id": "retrying_implements", "from": "retrying_processor", "to": "payment_processor", "kind": "realization" },
+    { "id": "bank_implements", "from": "bank_transfer", "to": "payment_processor", "kind": "realization" },
+    { "id": "stripe_extends", "from": "stripe_card", "to": "retrying_processor", "kind": "inheritance" },
+    { "id": "adyen_extends", "from": "adyen_card", "to": "retrying_processor", "kind": "inheritance" },
+    { "id": "paypal_extends", "from": "paypal_wallet", "to": "retrying_processor", "kind": "inheritance" }
+  ]
+}

package/skills/archify/examples/payments.class.json

@@ -0,0 +1,85 @@
+{
+  "schema_version": 1,
+  "diagram_type": "class",
+  "meta": {
+    "title": "Payment module types",
+    "subtitle": "OrderService depends on the PaymentGateway contract; card and wallet gateways implement it.",
+    "output": "payments-class.html",
+    "quality_profile": "showcase"
+  },
+  "layout": {
+    "mode": "grid"
+  },
+  "types": [
+    {
+      "id": "order_service",
+      "label": "OrderService",
+      "kind": "class",
+      "sublabel": "Creates orders and starts payment",
+      "row": 0,
+      "col": 0,
+      "attributes": [
+        { "name": "gateway", "type": "PaymentGateway", "visibility": "private" }
+      ],
+      "methods": [
+        { "name": "createOrder", "parameters": "cart: Cart", "returns": "Order", "visibility": "public" },
+        { "name": "checkout", "parameters": "order: Order", "returns": "Receipt", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "payment_gateway",
+      "label": "PaymentGateway",
+      "kind": "interface",
+      "sublabel": "Payment contract every channel fulfils",
+      "row": 0,
+      "col": 1.5,
+      "methods": [
+        { "name": "pay", "parameters": "amount: Money", "returns": "Result", "visibility": "public", "abstract": true }
+      ]
+    },
+    {
+      "id": "order",
+      "label": "Order",
+      "kind": "class",
+      "sublabel": "Order identity, amount, and status",
+      "row": 1,
+      "col": 0,
+      "attributes": [
+        { "name": "id", "type": "OrderId", "visibility": "public" },
+        { "name": "amount", "type": "Money", "visibility": "public" },
+        { "name": "status", "type": "OrderStatus", "visibility": "public" }
+      ],
+      "methods": [
+        { "name": "markPaid", "returns": "void", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "card_gateway",
+      "label": "CardGateway",
+      "kind": "class",
+      "sublabel": "Charges a bank card",
+      "row": 1,
+      "col": 1,
+      "methods": [
+        { "name": "pay", "parameters": "amount: Money", "returns": "Result", "visibility": "public" }
+      ]
+    },
+    {
+      "id": "wallet_gateway",
+      "label": "WalletGateway",
+      "kind": "class",
+      "sublabel": "Debits a stored wallet balance",
+      "row": 1,
+      "col": 2,
+      "methods": [
+        { "name": "pay", "parameters": "amount: Money", "returns": "Result", "visibility": "public" }
+      ]
+    }
+  ],
+  "relationships": [
+    { "id": "uses_gateway", "from": "order_service", "to": "payment_gateway", "kind": "dependency", "label": "pays through" },
+    { "id": "creates_order", "from": "order_service", "to": "order", "kind": "dependency", "label": "creates" },
+    { "id": "card_implements", "from": "card_gateway", "to": "payment_gateway", "kind": "realization" },
+    { "id": "wallet_implements", "from": "wallet_gateway", "to": "payment_gateway", "kind": "realization" }
+  ]
+}