@izumisy-tailor/omakase-modules 0.1.0 → 0.2.0

package/docs/examples/data-models/scenarios/order-payment-status-scenario.md

@@ -0,0 +1,92 @@
+# Order Payment Status Scenario
+
+## Overview
+This document captures a reference flow where the order module owns the canonical order status while collaborating with optional billing, authorization, and cash receipt modules. The order module remains usable as a standalone component—for example, back-office staff can record invoice or payment outcomes manually—while downstream modules add automation by reacting to order events and pushing their results back through status history entries. The shared contract that keeps order independent is defined in [Order Module Core Contract](../order-module-core-contract.md).
+
+## Module Dependencies
+
+| Module (package path) | Declared dependencies | Purpose |
+| --- | --- | --- |
+| Order (`packages/order-module`) | — | Publishes the `order.orderIntent` contract, stores canonical orders, and exposes status history consumed by downstream financial modules. |
+| Payment authorization (`packages/payment-authorization-module`) | Order | Manages authorization holds/captures against external PSPs and appends payment statuses to `orderStatusHistory`. |
+| Billing (`packages/billing-module`) | Order, Payment authorization | Generates invoices (manually or automatically), links them to authorizations, and writes billing milestones into `orderStatusHistory`. |
+| Cash receipt (`packages/cash-receipt-module`) | Order, Billing | Records cash inflows, allocates them to invoices, and publishes settlement statuses into `orderStatusHistory`. |
+
+## TailorDB Tables and Views
+### Payment authorization module
+- `authorization.request`: Outbound authorization attempts for a given order.
+- `authorization.result`: Holds/voids/captures returned from the PSP.
+- Appends `payment:*` entries (e.g., `payment:authorized`, `payment:capture_failed`) to `orderStatusHistory` via the order dependency.
+
+### Billing module
+- `billing.invoice`: Invoices generated for orders.
+- `billing.invoiceStatus`: Derived view summarizing invoice state (issued, posted, settled).
+- Appends `billing:*` milestones (e.g., `billing:invoice_issued`, `billing:settled`) to `orderStatusHistory` and maintains projections for finance dashboards.
+
+### Cash receipt module
+- `cash.receipt`: Records individual cash inflows.
+- `cash.receiptAllocation`: Maps receipts to invoices.
+- Appends `cash:*` history entries (`cash:payment_applied`, `cash:refund_requested`) to provide audit traces within `orderStatusHistory`.
+
+## Order Status
+
+Baseline `order:*` statuses are documented in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). Financial automation contributes the following additional entries:
+
+| Label | Writer | Trigger timing | Notes |
+| --- | --- | --- | --- |
+| `payment:authorization_pending` | Payment authorization | Immediately after `paymentAuthorizationIntake` enqueues an authorization attempt. | Communicates that an authorization request is in flight. |
+| `payment:authorized` | Payment authorization | When the PSP returns a successful authorization or capture. | Used to gate invoice issuance or fulfilment release. |
+| `payment:capture_failed` | Payment authorization | Upon PSP decline or technical failure. | Prompts support teams to investigate or retry. |
+| `billing:invoice_requested` | Billing | When `billingOrderIntake` decides to create an invoice. | Marks the start of the billing workflow even before the invoice record exists. |
+| `billing:invoice_issued` | Billing | After an invoice is generated. | Downstream consumers can inform customers or trigger collections. |
+| `billing:settled` | Billing | Once the invoice is fully settled in billing systems. | Often paired with cash entries for complete reconciliation. |
+| `cash:payment_applied` | Cash receipt | When cash is allocated to the invoice covering the order. | Confirms funds have been received and matched. |
+| `cash:refund_requested` | Cash receipt | If a refund or reversal is initiated. | Allows order timelines to reflect outstanding customer adjustments. |
+
+## Executor Triggers
+
+| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
+| --- | --- | --- | --- | --- |
+| `order.order` (order) | Order (owner), back-office operators | Record creation or update (CDC) | `billingOrderIntake` (billing) | React to new or updated orders, create invoices when automation is enabled, and append `billing:invoice_requested` statuses. |
+| `order.order` (order) | Order (owner), back-office operators | Record creation or update (CDC) | `paymentAuthorizationIntake` (payment authorization) | Initiate or refresh authorization attempts based on order state or manual triggers; append `payment:authorization_pending` status. |
+| `authorization.result` (payment authorization) | Payment authorization (owner) | Record creation or update (CDC) | `authorizationStatusWriter` (payment authorization) | Append authorization outcomes to `orderStatusHistory` (`payment:authorized`, `payment:capture_failed`) and refresh module projections. |
+| `billing.invoice` (billing) | Billing (owner), operators | Record creation or update (CDC) | `billingStatusWriter` (billing) | Append invoice lifecycle entries (`billing:invoice_issued`, `billing:invoice_posted`) to `orderStatusHistory`. |
+| `billing.invoiceStatus` (billing) | Billing (derived) | View refresh | `billingSettlementWriter` (billing) | Append settlement milestones (`billing:settled`) and update finance dashboards. |
+| `cash.receiptAllocation` (cash receipt) | Cash receipt (owner) | Record creation or update (CDC) | `cashReceiptOrderWriter` (cash receipt) | Append `cash:payment_applied` entries and emit reconciliation tasks when allocations differ from expectations. |
+
+## Flow
+1. A new order intent is submitted (automated integration or operator input). The order module validates it, persists `order.order`, and emits a CDC event.
+2. The billing and payment authorization modules listen to that CDC stream. If enabled, their executors (`billingOrderIntake`, `paymentAuthorizationIntake`) create invoices or authorization requests and append pending statuses (`billing:invoice_requested`, `payment:authorization_pending`). Otherwise they ignore the event, allowing manual workflows.
+3. Authorization results are written to `authorization.result`. The `authorizationStatusWriter` executor appends outcomes such as `payment:authorized` or `payment:capture_failed` to `orderStatusHistory`, enabling order consumers to track financial progress without exposing PSP details.
+4. Billing lifecycle changes (automation or manual invoice entry) update `billing.invoice` / `billing.invoiceStatus`. Billing executors append milestones (`billing:invoice_issued`, `billing:settled`) to `orderStatusHistory` and refresh their projections.
+5. Cash receipts allocate payments to invoices via `cash.receiptAllocation`. The cash receipt executor appends settlement statuses (`cash:payment_applied`) so customer service teams can view payment confirmations from the order timeline.
+6. Operators can always append manual entries to `orderStatusHistory` (e.g., `manual:write_off`) to reflect adjustments; downstream modules treat those entries as authoritative signals and reconcile their own records accordingly.
+
+```mermaid
+sequenceDiagram
+	actor Operator
+	participant Order
+	participant Billing
+	participant Auth as PaymentAuth
+	participant Cash
+
+	Operator->>Order: submit orderIntent (manual or automated)
+	Order->>Order: orderIntentIngestor creates order.order
+	Order-->>Billing: order.order CDC event
+	Billing->>Billing: billingOrderIntake decides on automation
+	Billing->>Order: append billing:* status history entries
+	Order-->>Auth: order.order CDC event
+	Auth->>Auth: paymentAuthorizationIntake initiates auth request
+	Auth->>Order: append payment:* status history entries
+	Billing->>Billing: invoice lifecycle progresses
+	Billing->>Order: append billing:settled when complete
+	Cash-->>Billing: cash.receiptAllocation links receipt to invoice
+	Cash->>Order: append cash:payment_applied status
+```
+
+## Design Considerations
+- Keep configuration dependencies directional: downstream financial modules depend on order, not the other way around, following the guidance in `../order-module-core-contract.md`.
+- Downstream modules append to `orderStatusHistory` using namespace-qualified status codes instead of mutating `order.order` fields, preserving the clean core.
+- CDC-driven automation should be idempotent and tolerant of manual changes, reconciling rather than overwriting operator inputs.
+- Maintain documented vocabularies for `payment:*`, `billing:*`, and `cash:*` statuses so shared dashboards interpret them consistently.
+- Leverage projections (e.g., `order.financialStatusProjection`) for read-heavy contexts while keeping `orderStatusHistory` as the authoritative audit trail.

package/docs/examples/data-models/scenarios/procurement-order-scenario.md

@@ -0,0 +1,95 @@
+# Procurement Order Scenario
+
+## Overview
+This document illustrates how an order module cooperates with a procurement module when customer demand is fulfilled through supplier purchase orders rather than internal stock. The order module remains a clean, customer-facing source of truth, while procurement owns supplier relationships, purchase orders, and inbound logistics. The goal is to let organizations operate mixed models (stocked items vs. drop-ship) without embedding procurement concerns into the core order schema. The shared order contract that keeps the core independent is described in [Order Module Core Contract](../order-module-core-contract.md).
+
+## Module Dependencies
+
+| Module (package path) | Declared dependencies | Purpose |
+| --- | --- | --- |
+| Order (`packages/order-module`) | — | Publishes the `order.orderIntent` contract, stores canonical orders, and exposes status history for downstream modules. |
+| Procurement (`packages/procurement-module`) | Order, Commerce core | Generates and tracks supplier purchase orders, manages inbound shipments, and appends procurement milestones to `orderStatusHistory`. |
+| Commerce core (`packages/commerce-core-module`) | — | Provides product master data, supplier catalogs, and lead-time metadata consumed by procurement. |
+| Inventory (`packages/inventory-module`) | Procurement, Commerce core | Optionally tracks goods received into stock or cross-docking locations. |
+| Billing (`packages/billing-module`) | Order | Handles customer invoicing; may wait for procurement confirmation before finalizing revenue. |
+
+## TailorDB Tables and Views
+### Procurement module
+- `procurement.purchaseOrder`: Supplier-facing purchase orders referencing `orderId` and line allocations.
+- `procurement.supplier`: Master data for suppliers, including lead times, payment terms, and partner IDs.
+- `procurement.inboundShipment`: Tracks ASN (advance shipping notice), shipment status, and expected arrival.
+- `procurement.exceptions`: Captures issues such as supplier delays, quantity shortages, or quality holds.
+- `procurement.orderStatus`: Projection of procurement milestones per order (PO issued, supplier confirmed, shipment dispatched, received).
+- Appends `procurement:*` entries to `orderStatusHistory` for shared visibility while keeping detailed supplier data inside procurement-owned tables.
+
+### Inventory module (optional)
+- Uses core inventory tables (`inventory.stock`, `inventory.stockLedger`, etc.) as defined in `../core/inventory-module.md` to reflect inbound receipts and stock updates; not redefined here.
+- `inventory.receipt`: Scenario-specific record for booking inbound shipments into stock or cross-dock locations.
+
+## Order Status
+
+Baseline `order:*` statuses are defined in [Order Module Core Contract](../order-module-core-contract.md#order-status-vocabulary). Procurement adds the following milestones:
+
+| Label | Writer | Trigger timing | Notes |
+| --- | --- | --- | --- |
+| `procurement:po_issued` | Procurement module | Immediately after `procurementOrderIntake` creates a purchase order. | Indicates supplier engagement has started. |
+| `procurement:po_confirmed` | Procurement module | When the supplier confirms the purchase order. | Confirms expected ship dates and quantities. |
+| `procurement:asn_received` | Procurement module | Upon receiving an ASN or shipment notice. | Signals inbound logistics to prepare for receipt. |
+| `procurement:received` | Procurement module / Inventory module | When goods are fully received and reconciled. | Allows billing or fulfilment to proceed confidently. |
+| `procurement:short_shipment` | Procurement module | If received quantity is less than ordered. | Highlights the need for back-order or customer communication. |
+| `procurement:blocking_exception` | Procurement module | When an exception (delay, quality hold) blocks fulfilment. | Downstream modules should pause until resolved. |
+
+## Executor Triggers
+
+| Trigger table (module) | Writers (modules) | Activation timing | Target executor (module) | Responsibility |
+| --- | --- | --- | --- | --- |
+| `order.order` (order) | Order (owner), operators | Record creation or update (CDC) | `procurementOrderIntake` (procurement) | Decide whether a purchase order is needed based on product supply policies and current stock; create or update `procurement.purchaseOrder` rows. |
+| `procurement.purchaseOrder` (procurement) | Procurement (owner) | Record creation or update (CDC) | `procurementPOStatusProjector` (procurement) | Update supplier confirmations, expected ship dates, and project milestones into `procurement.orderStatus`. |
+| `procurement.inboundShipment` (procurement) | Procurement (owner), suppliers via EDI | Record creation or update (CDC) | `procurementInboundCoordinator` (inventory) | Trigger inbound logistics tasks, e.g., allocate receiving docks or generate `inventory.receipt` placeholders. |
+| `inventory.receipt` (inventory) | Inventory (owner) | Record creation (CDC) | `procurementReceiptReconciler` (procurement) | Match receipts to purchase orders, update quantities received, and close out procurement exceptions. |
+| `procurement.exceptions` (procurement) | Procurement (owner), operators | Record creation or update (CDC) | `procurementExceptionProjector` (procurement) | Reflect exception state in `procurement.orderStatus` and expose signals (e.g., blocks) for downstream modules. |
+
+## Flow
+1. An order intent is submitted. After validation, the order module persists `order.order` and emits a CDC event that triggers `procurementOrderIntake`.
+2. Procurement evaluates supply policies, available stock, and supplier contracts. If a supplier order is required, it creates `procurement.purchaseOrder` entries linking each order line to a supplier and expected ship date, and appends `procurement:po_issued` to `orderStatusHistory`.
+3. Suppliers confirm the purchase order through EDI/API or operator input. `procurement.purchaseOrder` updates drive `procurementPOStatusProjector`, which writes milestones (confirmed, delayed, partial) into `procurement.orderStatus` and appends corresponding entries (e.g., `procurement:po_confirmed`) to `orderStatusHistory`.
+4. When suppliers send advance shipping notices, `procurement.inboundShipment` records are created. `procurementInboundCoordinator` may allocate receiving resources or pre-create `inventory.receipt` placeholders while recording `procurement:asn_received` in the shared history.
+5. Upon physical receipt, the inventory module records `inventory.receipt`, triggering `procurementReceiptReconciler` to update received quantities, close or escalate procurement exceptions, and append `procurement:received` or `procurement:short_shipment` statuses for order-facing consumers.
+6. Any exceptions (short shipments, quality holds, supplier delays) are logged in `procurement.exceptions`. `procurementExceptionProjector` updates `procurement.orderStatus` and surfaces blocking flags via `orderStatusHistory` so downstream modules can pause fulfilment or billing.
+7. Once procurement confirms completion, order and billing experiences reference `procurement.orderStatus` alongside the shared history to release fulfilment and issue invoices when appropriate.
+
+```mermaid
+sequenceDiagram
+    actor Customer
+    participant Order
+    participant Procurement
+    actor Supplier
+    participant Inventory
+    participant Billing
+
+    Customer->>Order: submit orderIntent
+    Order->>Order: orderIntentIngestor creates order.order
+    Order-->>Procurement: order.order CDC event
+    Procurement->>Procurement: procurementOrderIntake creates purchaseOrder
+    Procurement->>Order: append procurement:po_issued status
+    Procurement->>Supplier: send purchase order
+    Supplier-->>Procurement: confirmation updates purchaseOrder
+    Procurement->>Order: append procurement:po_confirmed status
+    Supplier-->>Procurement: send inboundShipment/ASN
+    Procurement->>Order: append procurement:asn_received status
+    Procurement->>Inventory: procurementInboundCoordinator prepares receipt
+    Inventory->>Inventory: record inventory.receipt
+    Inventory-->>Order: append procurement:received / procurement:short_shipment statuses
+    Procurement->>Procurement: procurementExceptionProjector updates orderStatus view
+    Procurement-->>Order: expose orderStatus for fulfillment/billing decisions
+    Order-->>Billing: release for invoicing once procurement complete
+```
+
+## Design Considerations
+- Keep procurement logic modular so order can operate without it (e.g., stocked items). The intake executor should be configuration-driven (per SKU, channel, or merchant) and must adhere to `../order-module-core-contract.md`.
+- Purchase orders may aggregate multiple customer orders; ensure `procurement.purchaseOrder` links to both supplier PO numbers and individual order line allocations.
+- Exceptions should be first-class records with lifecycle management, enabling reporting and SLA tracking.
+- Append procurement milestones to `orderStatusHistory` with namespace-qualified codes (`procurement:*`) so order-facing teams share a single timeline.
+- Inventory integration is optional: drop-ship flows might bypass inventory entirely, while cross-docking requires temporary receipts.
+- Billing should respect procurement status, especially when revenue recognition depends on supplier confirmation or goods receipt.
+- Expose `procurement.orderStatus` as a read-only interface for order, billing, or customer-facing channels rather than duplicating timelines inside the order schema.

package/docs/tutorials/creating-modules.md

@@ -0,0 +1,256 @@
+# Creating Modules
+
+This guide explains how to create reusable Omakase Modules that can be shared across applications.
+
+## Module Structure
+
+A typical module package has this structure:
+
+```
+my-module/
+  package.json
+  tsconfig.json
+  src/
+    module.ts           # Module definition
+    types.ts            # Configuration types
+    tailordb/
+      index.ts          # TailorDB exports
+      context.ts        # Type definitions for tables
+      my-table.ts       # Table builders
+    resolvers/
+      my-resolver.ts
+    executors/
+      my-executor.ts
+```
+
+## 1. Define the Module
+
+Create the module definition with `defineModule`:
+
+```typescript
+// src/module.ts
+import { defineModule } from "@izumisy-tailor/omakase-modules/builder";
+import type { ModuleConfig } from "./types";
+import type { MyModuleTables } from "./tailordb/context";
+import * as pkg from "../package.json";
+
+export default defineModule<ModuleConfig, MyModuleTables>({
+  packageName: pkg.name,
+});
+```
+
+The `packageName` must match the `name` field in your `package.json`.
+
+## 2. Define Configuration Types
+
+Define what configuration options your module accepts:
+
+```typescript
+// src/types.ts
+import { TailorField } from "@tailor-platform/sdk";
+
+type DataModelConfiguration = {
+  docNumberPrefix?: string;
+  customAttributes?: Record<string, TailorField<any>>;
+};
+
+export type ModuleConfig = {
+  dataModel?: {
+    product?: DataModelConfiguration;
+    category?: DataModelConfiguration;
+  };
+};
+```
+
+## 3. Define Table Types
+
+Create type definitions for your module's tables:
+
+```typescript
+// src/tailordb/context.ts
+import type { TailorDBType } from "@tailor-platform/sdk";
+import type { ModuleConfig } from "../types";
+
+export type MyModuleTables = {
+  product: TailorDBType;
+  category: TailorDBType;
+};
+
+export type ModuleFactoryContext = {
+  config: ModuleConfig;
+};
+```
+
+## 4. Build Tables with Configuration
+
+Use `withModuleConfiguration` to access configuration when building tables:
+
+```typescript
+// src/tailordb/index.ts
+import { withModuleConfiguration } from "@izumisy-tailor/omakase-modules/builder";
+import type { MyModuleTables } from "./context";
+import moduleDef from "../module";
+import { buildProductTable } from "./product";
+import { buildCategoryTable } from "./category";
+
+const tables = await withModuleConfiguration(moduleDef, (context) => {
+  const category = buildCategoryTable(context);
+  const product = buildProductTable(context, { category });
+
+  return { product, category } satisfies MyModuleTables;
+});
+
+export const productTable = tables.product;
+export const categoryTable = tables.category;
+```
+
+```typescript
+// src/tailordb/product.ts
+import { db } from "@tailor-platform/sdk";
+import type { ModuleFactoryContext } from "./context";
+
+export const buildProductTable = (
+  { config }: ModuleFactoryContext,
+  deps: { category: TailorDBType }
+) => {
+  const customAttributes = config.dataModel?.product?.customAttributes || {};
+  const docNumberPrefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+
+  return db.type("Product", {
+    name: db.string(),
+    sku: db.string().unique(),
+    categoryId: db.uuid({ optional: true }).relation({
+      type: "keyOnly",
+      toward: { type: deps.category },
+    }),
+    docNumber: db.docNumber({ prefix: docNumberPrefix }),
+    ...customAttributes,
+    ...db.fields.timestamps(),
+  });
+};
+```
+
+## 5. Declare Dependencies on Other Modules
+
+If your module depends on other modules, use `ModuleDependency`:
+
+```typescript
+// src/types.ts
+import type { ModuleDependency } from "@izumisy-tailor/omakase-modules/builder";
+import type commerceCoreModule from "omakase-module-commerce-core";
+
+export type ModuleConfig = {
+  dataModel?: { /* ... */ };
+  dependencies: {
+    commerce: ModuleDependency<typeof commerceCoreModule>;
+  };
+};
+```
+
+This ensures type-safe dependency injection when users configure your module.
+
+## File Export Requirements
+
+Due to Tailor SDK API requirements, **TailorDB** and **Resolvers/Executors** have different export patterns:
+
+**TailorDB**: Should use a single `index.ts` barrel export. All table definitions should be exported from one file. This is **strongly recommended** because it allows you to use `satisfies` to verify that all required tables are defined for the module:
+
+```typescript
+// src/tailordb/index.ts
+const tables = await withModuleConfiguration(moduleDef, (context) => {
+  const category = buildCategoryTable(context);
+  const product = buildProductTable(context, { category });
+
+  // Type error if any required table is missing
+  return { product, category } satisfies MyModuleTables;
+});
+```
+
+```
+src/tailordb/
+  index.ts          # Exports all tables
+  product.ts        # Table builder (not directly exported)
+  category.ts       # Table builder (not directly exported)
+```
+
+**Resolvers/Executors**: Must be exported as **separate files**. Each resolver or executor must be in its own file and cannot be barrel-exported from an `index.ts`:
+
+```
+src/resolvers/
+  getProduct.ts     # Each resolver in its own file
+  listProducts.ts
+src/executors/
+  onProductCreated.ts   # Each executor in its own file
+  onOrderPlaced.ts
+```
+
+This is because the Tailor SDK processes resolver and executor files individually, expecting each file to contain a single definition with a default export.
+
+## 6. Configure Package Exports
+
+Set up your `package.json` to export the built files.
+
+> **Important**: The export paths `./backend/tailordb`, `./backend/resolvers/*`, and `./backend/executors/*` are **required** and must not be changed. The module system expects these exact paths to locate module files.
+
+```json
+{
+  "name": "my-module",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./dist/module.mjs",
+      "types": "./dist/module.d.mts"
+    },
+    "./backend/tailordb": {
+      "default": "./dist/tailordb/index.mjs",
+      "types": "./dist/tailordb/index.d.mts"
+    },
+    "./backend/resolvers/*": {
+      "default": "./dist/resolvers/*.mjs",
+      "types": "./dist/resolvers/*.d.mts"
+    },
+    "./backend/executors/*": {
+      "default": "./dist/executors/*.mjs",
+      "types": "./dist/executors/*.d.mts"
+    }
+  }
+}
+```
+
+Note that TailorDB uses an `index.mjs` barrel export, while resolvers and executors use wildcard patterns to export individual files.
+
+## Best Practices
+
+### Use Factory Functions for Tables
+
+Always use factory functions (like `buildProductTable`) instead of directly exporting table definitions. This allows configuration to be injected.
+
+### Type Your Tables
+
+Use `satisfies` to ensure your returned tables match the expected type:
+
+```typescript
+return { product, category } satisfies MyModuleTables;
+```
+
+### Provide Sensible Defaults
+
+Always provide default values for optional configuration:
+
+```typescript
+const prefix = config.dataModel?.product?.docNumberPrefix ?? "PROD";
+```
+
+### Export Table References
+
+Export individual table references for use in other modules:
+
+```typescript
+export const productTable = tables.product;
+```
+
+This allows other modules to reference your tables in relations and executors.
+
+## Next Steps
+
+- See [Using Modules](./using-modules.md) for how applications consume your module

package/docs/tutorials/using-modules.md

@@ -0,0 +1,174 @@
+# Using Modules in Your Application
+
+This guide explains how to use pre-built Omakase Modules in your Tailor Platform application.
+
+## Prerequisites
+
+- A Tailor Platform application
+- Modules installed as dependencies (e.g., `omakase-module-commerce-core`)
+
+## 1. Configure Modules
+
+Use `loadModules` to configure the modules your application needs:
+
+```typescript
+// modules.ts
+import { loadModules } from "@izumisy-tailor/omakase-modules";
+import { db } from "@tailor-platform/sdk";
+import ecommerceCoreModule from "omakase-module-commerce-core";
+
+export default loadModules((loader) => {
+  loader.add(
+    ecommerceCoreModule.configure({
+      config: {
+        dataModel: {
+          product: {
+            docNumberPrefix: "MY-PROD",
+            customAttributes: {
+              customStatus: db.enum(["new", "used", "refurbished"]),
+            },
+          },
+        },
+      },
+    })
+  );
+
+  return loader;
+});
+```
+
+Each module exposes a `configure()` method that accepts a type-safe configuration object. The available options are defined by the module author.
+
+## 2. Set Up tsconfig.json
+
+Configure path aliases in `tsconfig.json` to enable module configuration loading:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@izumisy-tailor/omakase-modules/config/loader": ["./modules.ts"]
+    }
+  }
+}
+```
+
+This tells the module system where to find your configuration file.
+
+## 3. Reference Modules in tailor.config.ts
+
+Use `getModulesReference` to include module files in your Tailor configuration:
+
+```typescript
+// tailor.config.ts
+import { defineConfig } from "@tailor-platform/sdk";
+import { getModulesReference } from "@izumisy-tailor/omakase-modules/config/sdk";
+import modules from "./modules";
+
+const moduleReference = getModulesReference(modules);
+
+export default defineConfig({
+  name: "my-app",
+  db: {
+    main: {
+      files: ["./src/tailordb/*.ts", ...moduleReference.tailordb],
+    },
+  },
+  resolver: {
+    "main-pipeline": {
+      files: ["./src/resolvers/*.ts", ...moduleReference.resolver],
+    },
+  },
+  executor: {
+    files: ["./src/executors/**/*.ts", ...moduleReference.executor],
+  },
+});
+```
+
+## 4. Handle Module Dependencies
+
+When modules depend on other modules, you need to wire them together:
+
+```typescript
+// modules.ts
+import { loadModules } from "@izumisy-tailor/omakase-modules";
+import ecommerceCoreModule from "omakase-module-commerce-core";
+import orderModule from "omakase-module-order";
+import inventoryModule from "omakase-module-inventory";
+
+export default loadModules((loader) => {
+  // Add the base module first
+  const $commerce = loader.add(
+    ecommerceCoreModule.configure({
+      config: { /* ... */ },
+    })
+  );
+
+  // Pass the commerce module as a dependency
+  const $order = loader.add(
+    orderModule.configure({
+      config: {
+        dependencies: {
+          commerce: $commerce,
+        },
+      },
+    })
+  );
+
+  // Inventory depends on both commerce and order
+  loader.add(
+    inventoryModule.configure({
+      config: {
+        dbNamespace: "main",
+        dependencies: {
+          commerce: $commerce,
+          order: $order,
+        },
+      },
+    })
+  );
+
+  return loader;
+});
+```
+
+The `loader.add()` method returns the configured module, which can then be passed as a dependency to other modules.
+
+## Common Configuration Options
+
+Most modules support these common configuration patterns:
+
+### Custom Attributes
+
+Add custom fields to module tables:
+
+```typescript
+config: {
+  dataModel: {
+    product: {
+      customAttributes: {
+        myCustomField: db.string(),
+        priority: db.int(),
+      },
+    },
+  },
+}
+```
+
+### Document Number Prefixes
+
+Customize document number prefixes:
+
+```typescript
+config: {
+  dataModel: {
+    order: {
+      docNumberPrefix: "ORD-2024",
+    },
+  },
+}
+```
+
+## Next Steps
+
+- See [Creating Modules](./creating-modules.md) if you want to build your own reusable modules

package/package.json

@@ -1,35 +1,27 @@
 {
   "name": "@izumisy-tailor/omakase-modules",
   "private": false,
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Modularization mechanism for Tailor Platform application powered by Tailor SDK",
   "type": "module",
   "files": [
-    "dist"
+    "src",
+    "docs"
   ],
   "exports": {
     ".": {
-      "default": "./dist/config/index.mjs",
-      "types": "./dist/config/index.d.mts"
+      "default": "./src/config/index.ts"
     },
     "./config/sdk": {
-      "default": "./dist/config/sdk/index.mjs",
-      "types": "./dist/config/sdk/index.d.mts"
+      "default": "./src/config/sdk/index.ts"
     },
     "./builder": {
-      "default": "./dist/builder/index.mjs",
-      "types": "./dist/builder/index.d.mts"
+      "default": "./src/builder/index.ts"
     },
     "./config/loader": {
-      "default": "./dist/stub-loader/index.mjs",
-      "types": "./dist/stub-loader/index.d.mts"
+      "default": "./src/stub-loader/index.ts"
     }
   },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "type-check": "tsc"
-  },
   "keywords": [
     "tailor-platform",
     "tailor-sdk",
@@ -38,13 +30,15 @@
   ],
   "author": "Tailor Inc.",
   "license": "MIT",
-  "packageManager": "pnpm@10.22.0",
   "devDependencies": {
     "@types/node": "^25.0.3",
     "tsdown": "^0.18.0",
     "typescript": "^5"
   },
   "peerDependencies": {
-    "@tailor-platform/sdk": "^0.17.0"
+    "@tailor-platform/sdk": "^0.20.0"
+  },
+  "scripts": {
+    "type-check": "tsc"
   }
-}
+}