Digital Key Module - Backend Documentation

1. Scope and Boundaries

The digital key backend owns the product_digital_keys table and the admin flows that manage the key pool lifecycle. Each digital product references a pool of keys that are assigned to orders at delivery time. There is no customer or mobile digital-key module in the current repo.

2. Module Composition

Key Pool Management (Catalog)

• Aggregate admin composition: apps/api/src/modules/catalog/catalog-admin.module.ts
• Leaf module: apps/api/src/modules/catalog/admin/digital-key/digital-key-admin.module.ts
• Controller: apps/api/src/modules/catalog/admin/digital-key/digital-key-admin.controller.ts
• Service: apps/api/src/modules/catalog/admin/digital-key/digital-key-admin.service.ts

Digital Delivery (Order)

• Digital delivery endpoint: apps/api/src/modules/order/admin/order-admin.controller.ts
• Digital delivery service method: apps/api/src/modules/order/admin/order-admin.service.ts

3. Data Model

• Table: product_digital_keys
• Schema file: packages/db/src/schema/product/product-digital-key.ts
• Product FK: packages/db/src/schema/product/product.ts via product_digital_keys.product_id

Primary columns:

• id - serial primary key
• product_id - FK to products.id
• key_value - the actual license / product key string
• status - enum: available | assigned | expired (default: available)
• assigned_at - timestamp when key was assigned to an order
• order_item_id - FK to order_items.id when assigned
• created_at
• updated_at

Unique constraint: (product_id, key_value) — no duplicate keys per product.

4. Runtime Rules

• Keys are created in available status only.
• A key can only be assigned once — onConflictDoNothing on insert prevents duplicates.
• Assignment transfers key from available → assigned and links it to the order item.
• Deleting a key is only allowed when status is available.
• Digital delivery is a synchronous admin action: keys are assigned and emailed in the same request.

5. Admin API — Key Pool Management

All endpoints under admin/catalog/products/:productId/keys:

6. Admin API — Digital Order Delivery

All endpoints under admin/orders:

7. Delivery Flow

1. Admin triggers POST /api/admin/orders/:id/send-digital-delivery.
2. System checks the order is paid and order_type is digital.
3. For each digital order item, an available key from the product's pool is claimed and assigned.
4. Keys are linked to their respective order_item records.
5. An email with the assigned keys is sent to the customer.
6. Fulfillment status transitions to key_sent.
7. A DIGITAL_KEY_DELIVERY notification event is emitted.

8. Error Contracts

• DIGITAL_KEY_NOT_FOUND — No available key in the pool for a digital product
• DIGITAL_KEY_IN_USE — Attempt to delete a key that is already assigned
• ORDER_NOT_DIGITAL — Digital delivery attempted on a non-digital order

9. File Map

See Also

• Catalog Product - Backend Documentation
• Order Fulfillment Lifecycle