POS - Backend Documentation

1. Documentation Evidence

2. Backend Scope and Boundaries

Owns

• The counter draft: opening a sale, attaching/creating the customer, lines, fulfilment.
• Completion — the one transaction that reserves stock, materialises the checkout pipeline, creates the order and (for pickup) hands over.
• Walk-in account provisioning (no password) and the set-password invitation.
• The pos_sale audit timeline.
• The hourly abandoned-draft sweep.
• The channel label on orders and checkout sessions (defaults online).
• The pos_cash / pos_card / pos_qr payment methods and their counter gateway.

Does Not Own

• Inventory movement (delegated to InventoryReservationService).
• Order creation and lifecycle (delegated to OrderCreationService; the Order module owns every state after confirmed).
• Payment gateway logic (a payment_attempt row is written directly, but the Payment module owns the table and its admin surface).
• Refunds and returns (Order module).
• Barcode search (does not exist — product has sku, no barcode column).
• Receipt/invitation sending (delegated to the Notifications queue).

Source of Truth

3. Module Composition

4. File and Directory Map

apps/api/src/modules/pos/
  pos.module.ts
  pos-shared.module.ts
  pos-worker.module.ts
  admin/
    pos-admin-aggregate.module.ts
    sale/
      pos-sale-admin.controller.ts
      pos-sale-admin.module.ts
      pos-sale-admin.service.ts
      dto/            # request, response, list-query
    lookup/
      pos-lookup-admin.controller.ts
      pos-lookup-admin.module.ts
      dto/pos-lookup.dto.ts
  shared/
    pos.constants.ts
    pos-customer.service.ts
    pos-lookup.service.ts
    pos-mail-queue.service.ts
    pos-sale-access.service.ts
    pos-sale-completion.service.ts
    pos-sale-draft.service.ts
    pos-sale-event.service.ts
    pos-sale-line.service.ts
    pos-sale-number.service.ts
    pos-sale-query.service.ts
    pos-totals.util.ts
  workers/
    pos-draft-sweep.processor.ts
    pos-email.processor.ts
    pos-maintenance.scheduler.ts
    pos-queue.processor.ts
  emails/
    pos-receipt.email.ts
    pos-walk-in-invite.email.ts

5. Data Model

5.1 Schema Source

packages/db/src/schema/pos/
  index.ts
  enums.ts
  pos-sale.ts
  pos-sale-item.ts
  pos-sale-event.ts

Also modified: sales_channel enum in packages/db/src/schema/checkout/enums.ts, payment_method enum gains pos_cash/pos_card/pos_qr, order.channel and checkout_session.channel columns (both default online).

5.2 Tables and Collections

pos_sale

Key constraints:

• uq_pos_sale_{cart,checkout_session,payment_attempt,order}_id — partial on NOT NULL, so a replayed completion collides instead of double-charging.
• chk_pos_sale_status_completion — one exhaustive disjunction: a completed sale must hold every downstream key; picked_up only with pickup, ordered only with delivery; cancelled has no order.
• chk_pos_sale_fulfilment_address — pickup ⇒ no address and shipping 0; delivery ⇒ address present.
• chk_pos_sale_payment_reference_method — reference NULL or method is pos_card/pos_qr (compared ::text because a new enum value cannot be used in the transaction that adds it).
• chk_pos_sale_grand_total_matches — grand_total = subtotal − discount + shipping, written as an equality.
• chk_pos_sale_completed_has_contents — a completed sale has lines; drafts may be empty.
• chk_pos_sale_currency_normalized, chk_pos_sale_number_not_blank, chk_pos_sale_version_positive, chk_pos_sale_money_non_negative, chk_pos_sale_discount_within_subtotal, chk_pos_sale_counts_non_negative.

pos_sale_item

• uq_pos_sale_item_pos_sale_id_product_id — one line per product; the upsert is ON CONFLICT DO UPDATE.
• chk_pos_sale_item_line_total_matches (line_total = unit_price × quantity), chk_pos_sale_item_net_amount_matches (net_amount = line_total − discount), chk_pos_sale_item_discount_within_line, chk_pos_sale_item_price_not_above_mrp, chk_pos_sale_item_money_non_negative, chk_pos_sale_item_product_name_not_blank.

pos_sale_event

• chk_pos_sale_event_transition_pair, chk_pos_sale_event_transition_moves, chk_pos_sale_event_cancel_reason (the IS NOT NULL arm is load-bearing — the original constraint passed on NULL reason, fixed by migration 0015), chk_pos_sale_event_reason_not_blank (~ '[^[:space:]]', not btrim).

5.3 Relationship Diagram

6. Services and Responsibilities

6.1 PosSaleAccessService

FOR UPDATE rather than optimistic version: the caller is about to make several dependent writes, and a version mismatch at the end would discard them all.

6.2 PosSaleEventService

One method: record. Written in the SAME transaction as the change (16-observability-rules). No update, no amend, no soft delete — a correction is a new row.

6.3 PosSaleNumberService

issue → POS-2026-000042 from pos_sale_number_seq (cache: 1), year from timezone('Asia/Kathmandu', now()) in the DB. Its own sequence so till numbers and order numbers never interleave. Gaps are expected and correct — a rolled-back sale consumed its number.

6.4 PosCustomerService

The email check exists only to name the remedy; customers_email_unique enforces. It matches the index exactly — no deleted_at filter, because the unique index is not partial.

6.5 PosLookupService

ILIKE %term% on name/email/phone (customers) and name/SKU (products), min 2 characters, escapeLikePattern + normalizeSearchTerm, PaginationUtil offset. Customers restricted to status = 'active' and not deleted; products to published, not deleted. Deliberately not trigram: an operator wants the exact row, not the closest miss.

6.6 PosSaleDraftService

6.7 PosSaleLineService

• upsertLine: validates quantity (1–99), locks, loads sellable product (published, not deleted, price ≤ MRP), computes amounts, INSERT ... ON CONFLICT DO UPDATE, event item_added/item_quantity_changed, recomputes totals.
• removeLine: locks, hard deletes by (pos_sale_id, product_public_id), event item_removed, recomputes totals. 404 POS_LINE_NOT_FOUND if absent.

6.8 PosSaleCompletionService

complete — one transaction:

1. lockDraft (first lock, the start of the global order).
2. applyPaymentReference — trims, refuses beside pos_cash.
3. assertCompletable — lines, customer, delivery address.
4. assertPricesUnchanged — current sellingPrice vs frozen unitPrice; refuse loudly.
5. reserveAll — ascending product id; insufficient stock translated to POS_INSUFFICIENT_STOCK (narrowed on the code, never the class); nothing queried after a failed statement (25P02).
6. resolveShipping + materialize — cart born converted, session born completed (channel: "pos"), frozen checkout_session_items, payment_attempt born succeeded with gateway_transaction_id = POS-{saleNumber} and a real random callback token hash.
7. reservations.finalize per line — holds become deductions.
8. orders.createFromCheckout(..., { executor: tx, suppressOpeningEmail: pickup }) — the order inside the sale's transaction.
9. handover.handOver for pickup — drives the order to delivered.
10. finalise — status picked_up/ordered, all keys, version + 1, guarded WHERE status = 'draft' (replay → POS_SALE_ALREADY_COMPLETED).
11. mail.queueReceipt — outbox row in the same transaction.
12. Events payment_recorded + completed.

After commit: cache.triggerForWrite({ domain: "inventory", reason: "pos_sale_completed" }) — never inside the transaction (a network call must not hold the locks).

6.9 PosCheckoutMaterializerService

Writes the rows the Order module needs: cart (born converted to dodge uq_cart_customer_id_live), session (born completed to dodge uq_checkout_session_customer_live; channel: "pos"; payment_started_at/completed_at honest — the operator did take the money), lines frozen 1:1, and a settled payment_attempt whose shape, terminal status and audit trail match an online one. chk_checkout_session_status_timestamps still applies in full.

6.10 PosSaleQueryService

• findAll: offset pagination, filters (status, fulfilment, payment method, customer, administrator, from/to), page + total in ONE transaction, created_at DESC, id DESC. 09-pagination-rules: offset is fine here, cap at 10k/100k rows noted (~3 years at 100 sales/day).
• findOne: sale + lines + customer/admin names + order refs; 404 POS_SALE_NOT_FOUND.
• findTimeline: events oldest first, actor name left-joined.

6.11 PosMailQueueService

Both mails enqueued through the outbox in the sale's transaction: queueReceipt (pos.sale_completed, dedupe on the sale id — a sale completes exactly once) and queueWalkInInvite (pos.walk_in_created, dedupe on the customer id). No token in the payload.

The outbox dedupes the enqueue; the HANDLER needed keying too. Both handlers are at-least-once, and their own queue.add into the notifications queue carried no jobId — so a worker SIGKILLed after adding the email but before BullMQ acknowledged completion re-ran and queued a second one. Both now pass a deterministic id (pos-receipt-<salePublicId>, pos-walkin-invite-<customerId>), hyphen-separated because BullMQ rejects a custom id containing :.

6.11a What a receipt line says

The line query reads variant_name and net_amount, not just product_name and line_total.

variant_name is frozen onto pos_sale_item at the sale (migration 0030) so a receipt can say which configuration left the shop. Without it a sale holding the 256GB and the 512GB of one phone printed the same product name on both lines at two different prices, and a support query about "the wrong one" was unanswerable from the receipt. It is read from the frozen column rather than joined from the live variant, because the variant may since have been renamed or withdrawn and the receipt must say what was sold.

net_amount equals line_total today — no path sets a per-line discount — so this is not a visible change. It is correct by construction if one is ever added, where line_total would print the pre-discount line beside a post-discount total.

The meta string is built by buildLineMeta in common/email/email-components.ts, shared with the order-confirmation email. Both surfaces had made the same omission independently, which is the case for one function rather than a third copy — and the shape it produces ("256GB · Qty 1") is the one EmailLineItem's own doc comment had specified all along.

6.12 PosTotalsUtil

Pure functions: computePosSaleTotals (Σ lineTotal, discount, shipping; grandTotal = subtotal − discount + shipping) and computePosLineAmounts (lineTotal = unitPrice × quantity). Integer arithmetic only — no division, no rounding. The client never supplies a total.

7. Runtime Flows

7.1 Completion — the one transaction

7.2 The walk-in creation + invitation

The token is minted by the worker at send time — a raw non-expiring credential must never sit in outbox_events.payload, whose dead rows are never auto-purged.

7.3 The abandoned-draft sweep

Hourly cron (pos-draft-abandon-sweep, Asia/Kathmandu) enqueues pos.sweep_abandoned_drafts directly — the documented outbox exemption for a cron with no accompanying write. The handler claims up to 100 drafts (FOR UPDATE SKIP LOCKED, updated_at <= now() − 24h, oldest first) and cancels each in its OWN transaction with a guarded WHERE status = 'draft' update — an operator resuming the sale beats the sweep. Event reason: POS_DRAFT_ABANDONED_REASON.

8. Caching

POS has no cache keys of its own. Its one cache interaction is clearing the inventory domain after completion (stock moved), and it is deliberately product_review-style: the write-side triggerForWrite runs AFTER commit, fire-and-forget by contract — a committed sale must never 5xx because a cache did not clear.

9. BullMQ, Schedulers, and Async Work

PosQueueProcessor is the ONE @Processor on the queue (concurrency: 3), dispatching via an exhaustive Record<PosJob, handler> — a second decorated class would race and silently drop jobs (it happened on QueueName.INVENTORY). HttpException with an errorCode is a deterministic failure returned as { success: false, retryable: false, errorCode }; anything else is rethrown for retry.

Receipt and invite handlers render the email, enqueue NotificationJob.SEND_EMAIL onto QueueName.NOTIFICATIONS, and may return outcome: "skip" (customer deleted themselves, no email on file) — expected, no remedy, never thrown.

That downstream enqueue carries its own deterministic jobId — pos-receipt-<salePublicId> and pos-walkin-invite-<customerId>. The outbox dedupes the POS job; nothing deduped the notification job it produced, so a handler that died between the add and BullMQ's completion ack re-ran and queued a second email. Hyphens, not colons: BullMQ builds its keys as bull:<queue>:<jobId> and rejects a custom id containing : — the failure mode that once stopped the newsletter sweep from ever running (see pnpm rules:job-ids, which now catches it statically).

9.1 The cron entry point catches its own enqueue

PosMaintenanceScheduler wraps posQueue.add in a try/catch that logs and returns.

This is the one place in the module where swallowing is the correct behaviour and the reason is specific to @Cron: an exception escaping a scheduled handler propagates into the scheduler itself, and the job stops firing. The sweep would then not merely miss the tick that failed — it would never run again, with abandoned drafts holding their stock reservations indefinitely and no error after the first one.

10. Realtime and Events

No WebSocket/realtime surface exists in this module.

11. Security, Auth, and Abuse Controls

• Guards: JwtAuthGuard + RoleGuard on both controllers; IpThrottlerGuard per route.
• Permissions: Pos_CREATE / Pos_READ / Pos_UPDATE / Pos_DELETE, from the Pos permission module — spell it Pos, never POS. Pos_READ also exposes customer lookup, so it is grantable separately from Users_READ.
• Identity: @CurrentUser() user.id is the operator; every mutation records them on the event. The sweep records actor_admin_id: null.
• Rate limits: ADMIN_POS_WRITE 60/min per user (every draft mutation — 10/min ADMIN_WRITE would throttle a 15-item basket mid-sale), ADMIN_POS_COMPLETE 30/min per user, both keyed on the user because every till in a shop shares one IP. Lookup and reads use PUBLIC_SEARCH / ADMIN_READ.
• PII: customer lookup is bounded — 2-char minimum, paginated, never an unbounded list; returns no addresses or history; never the invite token.
• Ownership-scoped reads: a saved address is checked WHERE customer_id = sale.customer_id in the query — another customer's address returns 404, never 403.
• IDOR/leak hygiene: ParseUUIDPipe on every id (its absence caused 500s in Reviews); responses expose only public_ids, never integer PKs; a malformed id is a clean 400.
• Fail-closed: the transaction aborts on any guard; finalise is guarded on status = 'draft'; a completed sale cannot be re-priced or re-charged.
• Audit: every mutation writes pos_sale_event in the same transaction; the event table is append-only with no updated_at.

13. Error Handling

POS_PRODUCT_PRICE_CHANGED and POS_INSUFFICIENT_STOCK mean nothing was charged and nothing was reserved — the whole completion rolled back, the sale is still a live draft.

14. Observability

15. Testing and Validation

Validation: pnpm check-types · pnpm check (Biome) · pnpm build · pnpm test (serial, maxWorkers: 1) · pnpm rules — all passed in the feature's verification run.

16. Mandatory Backend Deep-Dive Pack

16.1 Submodule Coverage Matrix

16.2 UML and Architecture Diagram Pack

• Component diagram: §3 composition graph.
• ER diagram: §5.3.
• Sequence diagrams: §7.1 completion, §7.2 walk-in invite.
• Activity diagram: §7.3 sweep + feature §6.1 till flow.
• State diagram: feature §7 sale lifecycle.
• Deployment/runtime diagram: §9 queue topology.

16.3 Code Flow Narrative

The completion method (PosSaleCompletionService.complete) is the module's critical path and its full 15-step narrative is in §7.1. Walk-in creation in §7.2. The remaining mutation methods share one shape: db.transaction → lockDraft → (validate/load) → write → event → recomputeTotals → commit, with applyToDraft guarding every UPDATE on status = 'draft'.

16.4 Data Layer Deep Dive

Field-level detail for all three tables is in §5.2. Index rationale:

16.5 Business Logic and Invariant Catalog

16.6 Tradeoffs, Alternatives, and ADR Notes

16.7 Operational Runbook

16.8 Backend Risk Register

17. Zero-Omission Backend Checklist

• Every file in the module directory is represented or explicitly marked non-runtime (§4, §16.1).
• Every controller, service, provider, processor, scheduler, helper, mapper, DTO, enum, and schema is documented.
• Every method with business behavior has a code-flow narrative (§6, §7, §16.3).
• Every table/cache object/job payload has field-level detail (§5.2, §9).
• Every index, constraint, relation, and delete behavior has rationale (§5.2, §16.4).
• Every lifecycle/status transition has a state diagram and transition table (feature §7).
• Every read/write/action/job flow has sequence and activity diagrams (§7, §9).
• Every business invariant is cataloged (§16.5).
• Every cache key, invalidation path, queue job, realtime event, and external call is documented (§8, §9, §10).
• Every architectural tradeoff is documented with alternatives and revisit triggers (§16.6).
• Every operational failure mode has a runbook entry (§16.7).

18. Backend Completion Checklist

• Module boundaries are documented (§2).
• Every controller, service, DTO, schema file, job, cache key, and event is covered (§3–§11).
• Every database table has a field table and relationship diagram (§5).
• Every runtime flow has a diagram and branch notes (§7).
• API and features/flows docs are linked (See Also).
• No claim is made without a source file or documented source reference.

See Also

• API doc: /docs/developer/pos/api
• Features and flows doc: /docs/developer/pos/feature
• TDD: not yet published