Appendix F: BRD-to-Code Module Mapping

Version: 4.0.0 Last Updated: February 25, 2026 BRD Version: 20.0 (19,900+ lines, 7 modules, 113 decisions)

F.1 Purpose & How to Use This Document

This appendix maps every business capability in the Business Requirements Document (BRD v20.0) to a specific code-level service in the POS Platform implementation. It bridges the gap between business requirements (written for stakeholders) and the modular monolith implementation (written for developers).

Who Should Use This

Audience	Use Case
Developers	Find which service to create/modify when implementing a BRD feature
Architects	Verify module boundaries and dependency direction rules
QA Engineers	Trace test coverage back to BRD sections
Product Owners	Understand how business features map to technical components

How to Read the Tables

Each service entry includes:

Service Name: Technology-agnostic logical name (e.g., sale.cart.command.service)
BRD Section(s): Which BRD section(s) this service implements
Capability: What business function this service performs
Pattern: CQRS Command, Query, CRUD, Event Handler, Rule Engine, etc.
Owns Tables: Database tables this service is the authoritative writer for
Publishes/Consumes Events: Domain events for inter-service communication

F.2 Architecture Context

The POS Platform follows an Event-Driven Modular Monolith architecture (selected in Chapter 04) with the following pattern assignments per module:

Module	CQRS	Event Sourcing	Pattern
Module 1: Sales	Full CQRS	Full ES	Separate command/query services
Module 2: Customers	Standard CRUD	None	Repository pattern with caching
Module 3: Catalog	Standard CRUD	None	Read-heavy, Redis cache
Module 4: Inventory	Materialized read model	ES for audit trail	Command/query split for PO, transfers
Module 5: Setup	Standard CRUD	None	Configuration data, direct access
Module 6: Integrations	Standard CRUD	Audit-trail-only ES	Extractable gateway

Design Principles

Maximum Granularity: One service per business capability, not one service per module
Single Responsibility: Each service does ONE thing well
DDD Boundaries: Services own their aggregates; cross-module access via events or public API
No God Services: Break coarse-grained services (e.g., IOrderService) into focused capabilities

Reference: Chapter 04 (Architecture Styles Analysis), Section L.4 for full architecture rationale.

F.3 Module Overview

The BRD defines 6 business modules. The code architecture maps these to 7 code modules plus cross-cutting concerns and an optional RFID module:

#	BRD Module	Code Module	Services	Pattern
1	Sales (1.1-1.20)	`modules/sales/`	37	Full CQRS + ES
2	Customers (2.1-2.8)	`modules/customers/`	7	CRUD
3	Catalog (3.1-3.15)	`modules/catalog/`	20	CRUD + Cache
4	Inventory (4.1-4.19)	`modules/inventory/`	23	Materialized + ES audit
5	Setup (5.1-5.21)	`modules/setup/`	21	CRUD
6	Integrations (6.1-6.13)	`modules/integrations/`	20	CRUD + Audit ES
X	Cross-cutting (Ch 07, 14)	`cross-cutting/`	8	Mixed
R	RFID/Raptag (Ch 10 D13)	`modules/rfid/`	6	CRUD + Command
	TOTAL		142

F.4 Module 1: Sales – Service Breakdown (37 Services, Full CQRS+ES)

BRD Sections: 1.1-1.20

F.4.1 Cart & Checkout Commands

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
1	`sale.cart.command.service`	1.1	Create cart, add/remove line items, attach customer	Command	orders (draft state)	`SaleCreated`, `SaleLineItemAdded`, `SaleLineItemRemoved`	–
2	`sale.cart.query.service`	1.1	Get active cart, list items, calculate running totals	Query	(reads orders, order_items)	–	`SaleLineItemAdded`, `SaleLineItemRemoved`
3	`sale.park.command.service`	1.1, 1.1.1	Park/retrieve/expire held sales, manage TTL, soft-reserve inventory	Command	orders (parked state)	`SaleParked`, `SaleRetrieved`, `SaleExpired`	–
4	`sale.park.query.service`	1.1	List parked sales for terminal/location	Query	(reads orders WHERE status=parked)	–	`SaleParked`, `SaleRetrieved`

F.4.2 Discount & Pricing Commands

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
5	`sale.discount.command.service`	1.2	Apply/remove line discounts, global discounts, enforce calculation order	Command	(writes to order discount fields)	`DiscountApplied`, `DiscountRemoved`	–
6	`sale.promotion.engine.service`	1.2, 1.14	Evaluate automatic promos (Buy X Get Y), validate coupon codes, stack rules	Rule Engine	pricing_rules (read)	`PromotionTriggered`, `CouponRedeemed`	`SaleLineItemAdded`
7	`sale.price-override.command.service`	1.2	Manual price override with manager auth, reason code	Command	(writes to order_items.unit_price)	`PriceOverridden`	–

F.4.3 Payment & Settlement Commands

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
8	`sale.payment.command.service`	1.3	Process split tenders, validate payment covers total, calculate change	Command	payment_attempts	`PaymentReceived`, `PaymentFailed`	–
9	`sale.payment.card.service`	1.18	SAQ-A semi-integrated card flow: initiate terminal, receive token + auth	Integration	payment_attempts (card entries)	`CardPaymentAuthorized`, `CardPaymentDeclined`	–
10	`sale.payment.cash.service`	1.3	Cash tendering, change calculation, drawer interaction	Stateful	(writes to cash_movements)	`CashPaymentReceived`	–
11	`sale.payment.giftcard.service`	1.3, 1.5	Check GC balance, apply partial/full, deduct	Command	gift_card_transactions	`GiftCardRedeemed`	–
12	`sale.payment.storecredit.service`	1.3	Check credit balance, apply on-account, validate credit limit	Command	(reads/writes customer store_credit)	`StoreCreditApplied`	–
13	`sale.payment.affirm.service`	1.3	Third-party financing flow: create session, handle webhook	Integration	payment_attempts (affirm entries)	`AffirmLoanApproved`	–
14	`sale.finalize.command.service`	1.3	Finalize order: write record, deduct inventory, award loyalty, record commission	Command (Orchestrator)	orders (completed state)	`SaleCompleted`	`PaymentReceived`

F.4.4 Post-Sale Commands

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
15	`sale.void.command.service`	1.4, 1.4.1	Void same-day order: reverse inventory, loyalty, commission; check eligibility	Command	orders (voided state)	`SaleVoided`	–
16	`sale.return.command.service`	1.4	Process return: validate receipt, apply policy, issue refund	Command	returns, return_items	`ReturnInitiated`, `ReturnCompleted`	–
17	`sale.exchange.command.service`	1.4	Dedicated exchange: items OUT + items IN, calculate difference	Command	returns (exchange type), orders	`ExchangeProcessed`	–
18	`sale.return-policy.engine.service`	1.9	Evaluate return eligibility: time window, receipt validation, manager override	Rule Engine	(reads tenant_settings, return policy config)	`ReturnPolicyEvaluated`	–

F.4.5 Gift Card Commands

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
19	`sale.giftcard.command.service`	1.5	Sell/activate gift cards, reload, deactivate, check compliance	Command	gift_cards, gift_card_transactions	`GiftCardIssued`, `GiftCardActivated`, `GiftCardReloaded`	–
20	`sale.giftcard.query.service`	1.5	Balance lookup, transaction history, expiration check	Query	(reads gift_cards, gift_card_transactions)	–	`GiftCardRedeemed`, `GiftCardIssued`

F.4.6 Special Order & Layaway

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
21	`sale.specialorder.command.service`	1.6	Create/manage special orders and back orders	Command	orders (special_order type)	`SpecialOrderCreated`, `SpecialOrderFulfilled`	`InventoryReceived`
22	`sale.layaway.command.service`	1.3.2	Create layaway, accept deposits, release inventory on final payment	Stateful	orders (layaway state)	`LayawayCreated`, `LayawayPaymentReceived`, `LayawayCompleted`, `LayawayCancelled`	–
23	`sale.hold-for-pickup.command.service`	1.11	Hold/stage/expire pickup orders including BOPIS	Stateful	orders (hold states)	`HoldCreated`, `HoldStaged`, `HoldPickedUp`, `HoldExpired`	–

F.4.7 Cash Drawer Operations

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
24	`sale.cashdrawer.command.service`	1.12	Open/close drawer, paid in/out, cash drops, no-sale	Command	cash_drawers, cash_movements, cash_drops	`DrawerOpened`, `DrawerClosed`, `DrawerCashDrop`, `DrawerPaidIn`, `DrawerPaidOut`	`CashPaymentReceived`
25	`sale.cashdrawer.count.service`	1.12	Denomination-level cash counts (opening, closing, mid-shift, audit)	Command	cash_counts	`CashCounted`	–
26	`sale.cashdrawer.pickup.service`	1.12	Armored car pickup tracking, bank deposit reconciliation	Command	cash_pickups	`CashPickupCompleted`	–
27	`sale.shift.command.service`	1.12	Clock-in/out to shift, link to drawer, track totals	Stateful	shifts	`ShiftOpened`, `ShiftClosed`	`DrawerOpened`, `DrawerClosed`, `SaleCompleted`

F.4.8 Tax Engine

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
28	`sale.tax.calculation.service`	1.17	Calculate compound 3-level tax (State/County/City), handle exemptions	Calculation	(reads taxes, location_tax)	`TaxCalculated`	–

F.4.9 Commission & Loyalty

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
29	`sale.commission.command.service`	1.8	Calculate and record commissions per sale, proportional reversal on return	Command	(commission fields on orders)	`CommissionRecorded`, `CommissionReversed`	`SaleCompleted`, `ReturnCompleted`, `SaleVoided`
30	`sale.loyalty.command.service`	1.15	Award/redeem loyalty points, tier calculation, bonus rules	Command	loyalty_transactions, loyalty_accounts	`LoyaltyPointsEarned`, `LoyaltyPointsRedeemed`, `LoyaltyTierChanged`	`SaleCompleted`

F.4.10 Queries & Read Models

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
31	`sale.history.query.service`	1.4	Sales history with filters (date, user, status, location)	Query	(reads orders, order_items)	–	`SaleCompleted`, `SaleVoided`, `ReturnCompleted`
32	`sale.receipt.query.service`	1.4	Generate/reprint receipt data, email receipt	Query	(reads orders, order_items, payments)	`ReceiptEmailed`	–
33	`sale.receipt.validate.service`	1.4	Validate receipt barcode authenticity, match to order	Query	(reads orders)	–	–
34	`sale.daily-summary.projection.service`	1.1.2, 1.3.4	Materialized daily sales summary, hourly heatmap	Event Handler	(writes read model views)	–	`SaleCompleted`, `SaleVoided`, `ReturnCompleted`
35	`sale.price-check.query.service`	1.13	Price check mode: lookup product price without sale context	Query	(reads products, pricing_rules)	–	–

F.4.11 Offline & Serial Tracking

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
36	`sale.offline.sync.service`	1.16	Queue offline transactions, sync on reconnect, conflict resolution	Stateful	sync_queue (sale entries)	`OfflineSaleSynced`, `SyncConflictDetected`	–
37	`sale.serial-tracking.command.service`	1.10	Associate serial numbers with sale line items, validate uniqueness	Command	(serial_number field on order_items)	`SerialNumberSold`	–

F.5 Module 2: Customers – Service Breakdown (7 Services, CRUD)

BRD Sections: 2.1-2.8

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
38	`customer.profile.crud.service`	2.1	Create/update/delete customer profiles, manage PII	CRUD	customers	`CustomerCreated`, `CustomerUpdated`, `CustomerDeleted`	–
39	`customer.search.query.service`	2.1	Search customers by name, email, phone, loyalty number	Query	(reads customers)	–	`CustomerCreated`, `CustomerUpdated`
40	`customer.group.crud.service`	2.2	Manage customer groups/tiers (VIP, Wholesale, etc.), auto-tier rules	CRUD	(customer group/tier fields)	`CustomerGroupAssigned`, `CustomerTierChanged`	`SaleCompleted`
41	`customer.notes.crud.service`	2.3	Customer notes, preferences, internal flags	CRUD	(notes fields on customers)	–	–
42	`customer.communication.crud.service`	2.4	Marketing consent, preferred channels, opt-in/out	CRUD	(communication preference fields)	`CommunicationPreferenceChanged`	–
43	`customer.merge.command.service`	2.5	Merge duplicate customer records, reassign history	Command	customers (merge target)	`CustomersMerged`	–
44	`customer.privacy.command.service`	2.5, 2.6	GDPR anonymization, data export, deletion request	Command	customers (anonymized_at)	`CustomerAnonymized`, `CustomerDataExported`	–

F.6 Module 3: Catalog – Service Breakdown (20 Services, CRUD+Cache)

BRD Sections: 3.1-3.15

F.6.1 Product Management

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
45	`catalog.product.crud.service`	3.1	Create/update/delete products, manage attributes, soft delete	CRUD	products	`ProductCreated`, `ProductUpdated`, `ProductDeleted`	–
46	`catalog.variant.crud.service`	3.1	Create/update/delete variants (size/color), matrix management	CRUD	variants	`VariantCreated`, `VariantUpdated`, `VariantDeleted`	–
47	`catalog.product.query.service`	3.1	Get product by ID/SKU/barcode, list with pagination/filters	Query	(reads products, variants)	–	`ProductCreated`, `ProductUpdated`
48	`catalog.bulk-import.command.service`	3.1	Bulk CSV/Excel import of products and variants	Command	products, variants	`BulkImportCompleted`	–
49	`catalog.product.lifecycle.service`	3.2	Manage product lifecycle: draft, active, discontinued, archived	Stateful	products (lifecycle states)	`ProductActivated`, `ProductDiscontinued`, `ProductArchived`	–

F.6.2 Categorization & Tagging

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
50	`catalog.category.crud.service`	3.5	Manage hierarchical categories, sort order	CRUD	categories	`CategoryCreated`, `CategoryUpdated`	–
51	`catalog.collection.crud.service`	3.5	Marketing/seasonal collections with date ranges	CRUD	collections, product_collection	`CollectionCreated`, `CollectionUpdated`	–
52	`catalog.tag.crud.service`	3.5	Freeform product tags	CRUD	tags, product_tag	–	–
53	`catalog.brand.crud.service`	3.1	Brand reference data management	CRUD	brands	–	–

F.6.3 Pricing

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
54	`catalog.pricing.crud.service`	3.3	Manage pricing rules, price books, tier pricing	CRUD	pricing_rules	`PricingRuleCreated`, `PricingRuleUpdated`	–
55	`catalog.pricing.calculation.service`	3.3	Calculate effective price (hierarchy: price book > tier > promo > base)	Calculation	(reads pricing_rules, products)	–	–
56	`catalog.markdown.command.service`	3.3	Schedule markdowns, automatic clearance pricing	Command	pricing_rules (markdown type)	`MarkdownApplied`, `MarkdownExpired`	–

F.6.4 Barcode & Label

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
57	`catalog.barcode.service`	3.4	Generate/validate/lookup UPC/EAN barcodes	CRUD	(barcode fields on products/variants)	–	–
58	`catalog.label.print.service`	3.10	Generate label/price tag print jobs, template selection	Command	(label print queue)	`LabelPrintJobCreated`	–

F.6.5 Search, Media & Vendor

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
59	`catalog.search.service`	3.9	Full-text product search, faceted filtering, suggestions	Query	(reads products via FTS indexes)	–	`ProductCreated`, `ProductUpdated`
60	`catalog.media.crud.service`	3.11	Product image management, upload, reorder	CRUD	(image fields on products/variants)	–	–
61	`catalog.vendor.crud.service`	3.8	Vendor/supplier management, lead times, min order quantities	CRUD	(vendor reference tables)	`VendorCreated`, `VendorUpdated`	–
62	`catalog.notes.crud.service`	3.12	Product notes and attachments	CRUD	(notes/attachments on products)	–	–
63	`catalog.permissions.service`	3.13	Catalog approval workflows, permission checks	Rule Engine	(reads role_permissions)	`CatalogChangeApproved`, `CatalogChangeRejected`	`ProductUpdated`
64	`catalog.analytics.query.service`	3.14	Product performance analytics, sales velocity, margin analysis	Query	(reads products, order_items, inventory)	–	`SaleCompleted`

F.7 Module 4: Inventory – Service Breakdown (23 Services, Materialized+ES Audit)

BRD Sections: 4.1-4.19

F.7.1 Stock Level Queries

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
65	`inventory.level.query.service`	4.1, 4.2	Get current stock by variant/location, available qty calculation	Query	(reads inventory_levels materialized view)	–	`InventoryAdjusted`, `InventorySold`, `InventoryReceived`
66	`inventory.level.adjustment.service`	4.7	Manual adjustments: count, damage, theft, found, with reason codes	Command	inventory_levels, inventory_transactions	`InventoryAdjusted`	–
67	`inventory.status-model.service`	4.2	Manage inventory statuses: available, reserved, committed, in_transit, damaged	Stateful	inventory_levels (status fields)	`InventoryStatusChanged`	–

F.7.2 Purchase Orders

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
68	`inventory.po.command.service`	4.3	Create/edit/approve/cancel purchase orders	Command	(purchase_orders table)	`PurchaseOrderCreated`, `PurchaseOrderApproved`, `PurchaseOrderCancelled`	–
69	`inventory.po.query.service`	4.3	List/search POs, status tracking, ETA display	Query	(reads purchase_orders)	–	`PurchaseOrderCreated`, `PurchaseOrderApproved`
70	`inventory.receiving.command.service`	4.4	Receive against PO: full/partial, inspection, discrepancy handling	Command	inventory_levels, inventory_transactions	`InventoryReceived`, `ReceivingDiscrepancyLogged`	`PurchaseOrderApproved`

F.7.3 Reorder Management

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
71	`inventory.reorder.engine.service`	4.5	Auto-reorder point monitoring, suggested PO generation	Rule Engine	(reads inventory_levels, reorder configs)	`ReorderPointReached`, `ReorderSuggested`	`InventoryAdjusted`, `InventorySold`

F.7.4 Counting & Auditing

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
72	`inventory.count.command.service`	4.6	Physical inventory counts: full, cycle, spot check	Command	inventory_transactions (count type)	`InventoryCounted`	–
73	`inventory.count.query.service`	4.6	Count session management, variance reports	Query	(reads count sessions/results)	–	`InventoryCounted`

F.7.5 Transfers

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
74	`inventory.transfer.command.service`	4.8	Create/ship/receive inter-store transfers	Command	(transfer tables), inventory_transactions	`InventoryTransferred`, `TransferShipped`, `TransferReceived`	–
75	`inventory.transfer.query.service`	4.8	List transfers, track in-transit, ETA	Query	(reads transfer tables)	–	`TransferShipped`, `TransferReceived`

F.7.6 Vendor Returns & Costing

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
76	`inventory.rma.command.service`	4.9	Vendor RMA: create, ship back, track credit	Command	(RMA tables)	`VendorRMACreated`, `VendorRMAShipped`	–
77	`inventory.costing.calculation.service`	4.11	Landed cost calculation: freight, duty, insurance allocation	Calculation	(cost fields on inventory_transactions)	`LandedCostCalculated`	`InventoryReceived`
78	`inventory.serial-lot.command.service`	4.10	Serial/lot number assignment, tracking, recall support	Command	(serial/lot fields)	`SerialNumberAssigned`, `LotCreated`	–

F.7.7 Movement History & Dashboard

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
79	`inventory.movement.query.service`	4.12	Stock ledger, movement history by variant/location	Query	(reads inventory_transactions)	–	all `Inventory*` events
80	`inventory.dashboard.projection.service`	4.17	Inventory dashboard materialized views: stock value, aging, velocity	Event Handler	(writes dashboard read models)	–	`InventoryAdjusted`, `InventorySold`, `InventoryReceived`

F.7.8 POS Integration & Fulfillment

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
81	`inventory.sale-deduction.event-handler.service`	4.13	Deduct inventory on sale completion, restore on void/return	Event Handler	inventory_levels, inventory_transactions	`InventorySold`, `InventoryRestored`	`SaleCompleted`, `SaleVoided`, `ReturnCompleted`
82	`inventory.reservation.command.service`	4.13	Soft-reserve inventory for pending sales, holds, layaways	Command	inventory_levels (quantity_reserved)	`InventoryReserved`, `InventoryReservationReleased`	`SaleParked`, `HoldCreated`, `LayawayCreated`
83	`inventory.fulfillment.command.service`	4.14	Online order fulfillment: pick, pack, ship from store	Command	(fulfillment fields on orders)	`FulfillmentStarted`, `FulfillmentShipped`	–

F.7.9 Offline & Alerts

#	Service Name	BRD Section(s)	Capability	Pattern	Owns Tables	Publishes Events	Consumes Events
84	`inventory.offline.sync.service`	4.15	Offline inventory operations queue, sync, conflict resolution	Stateful	sync_queue (inventory entries)	`OfflineInventorySynced`	–
85	`inventory.alert.service`	4.16	Low stock alerts, reorder notifications, expiring lot alerts	Event Handler	–	`LowStockAlert`, `ReorderAlert`	`InventoryAdjusted`, `InventorySold`
86	`inventory.rules.engine.service`	4.18	Business rules evaluation from YAML config (negative stock, auto-transfer)	Rule Engine	(reads tenant_settings)	–	–
87	`inventory.report.query.service`	4.17	Inventory reports: valuation, aging, shrinkage, turnover	Query	(reads inventory_levels, inventory_transactions)	–	–

F.8 Module 5: Setup & Configuration – Service Breakdown (21 Services, CRUD)

BRD Sections: 5.1-5.21

F.8.1 System Settings

#	Service Name	BRD Section(s)	Capability	Pattern
88	`setup.settings.crud.service`	5.2	System settings, branding, locale, defaults	CRUD
89	`setup.currency.crud.service`	5.3	Multi-currency configuration, exchange rates	CRUD

F.8.2 Location Management

#	Service Name	BRD Section(s)	Capability	Pattern
90	`setup.location.crud.service`	5.4	Create/update/deactivate locations, assign type, set hours	CRUD

F.8.3 User & Role Management

#	Service Name	BRD Section(s)	Capability	Pattern
91	`setup.user.crud.service`	5.5	User profile management, activation/deactivation	CRUD
92	`setup.role.crud.service`	5.5	Role management, permission assignment matrix	CRUD
93	`setup.timetracking.command.service`	5.6	Clock-in/clock-out, break management	Command

F.8.4 Register & Hardware

#	Service Name	BRD Section(s)	Capability	Pattern
94	`setup.register.crud.service`	5.7	Register management, IP limits (max 2/365 days), retire (OWNER-only)	CRUD
95	`setup.printer.crud.service`	5.8	Printer/peripheral registration, connection management	CRUD
96	`setup.device.crud.service`	5.7	Device registration, hardware fingerprint, status management	CRUD

F.8.5 Tax Configuration

#	Service Name	BRD Section(s)	Capability	Pattern
97	`setup.tax.crud.service`	5.9	Tax rate definitions, location-tax assignments, effective dates	CRUD

F.8.6 Payment & UoM Configuration

#	Service Name	BRD Section(s)	Capability	Pattern
98	`setup.payment-method.crud.service`	5.11	Payment method configuration, processor settings	CRUD
99	`setup.uom.crud.service`	5.10	Units of measure management, conversion rules	CRUD

F.8.7 Custom Fields & Workflows

#	Service Name	BRD Section(s)	Capability	Pattern
100	`setup.customfield.crud.service`	5.12	Custom field definitions, validation rules, entity assignment	CRUD
101	`setup.approval-workflow.crud.service`	5.13	Approval workflow configuration, threshold rules	CRUD

F.8.8 Receipt & Email

#	Service Name	BRD Section(s)	Capability	Pattern
102	`setup.receipt.crud.service`	5.14	Receipt template configuration, header/footer customization	CRUD
103	`setup.email-template.crud.service`	5.15	Email template management, variable substitution	CRUD

F.8.9 Audit & Onboarding

#	Service Name	BRD Section(s)	Capability	Pattern
104	`setup.audit.config.service`	5.18	Audit log configuration, retention policies	CRUD
105	`setup.rules.engine.service`	5.19	Business rules YAML configuration, validation	CRUD
106	`setup.loyalty.config.service`	5.17	Loyalty program configuration: earn rate, tiers, expiry	CRUD
107	`setup.onboarding.wizard.service`	5.20	Tenant onboarding wizard: step tracking, initial data seeding	Stateful
108	`setup.integrations-hub.config.service`	5.16	Integration connections configuration (Setup side of Module 6)	CRUD

F.9 Module 6: Integrations – Service Breakdown (20 Services, CRUD+Audit ES)

BRD Sections: 6.1-6.13

F.9.1 Core Integration Infrastructure

#	Service Name	BRD Section(s)	Capability	Pattern
109	`integration.provider.registry.service`	6.2	Provider registration, IIntegrationProvider management	CRUD
110	`integration.circuit-breaker.service`	6.2	Circuit breaker state machine (CLOSED/OPEN/HALF_OPEN) per provider	Stateful
111	`integration.outbox.relay.service`	6.2	Transactional outbox polling, event publication via LISTEN/NOTIFY	Event Handler
112	`integration.idempotency.service`	6.2	Idempotency key tracking for at-least-once delivery	Stateful
113	`integration.webhook.pipeline.service`	6.2	Inbound webhook receipt, signature validation, routing	Integration
114	`integration.dead-letter.service`	6.2	Failed integration message capture, retry, replay	Event Handler

F.9.2 Shopify Integration

#	Service Name	BRD Section(s)	Capability	Pattern
115	`integration.shopify.product-sync.service`	6.3	Bidirectional product/variant sync via GraphQL, bulk operations	Integration
116	`integration.shopify.inventory-sync.service`	6.3	Inventory level sync with safety buffers, oversell prevention	Integration
117	`integration.shopify.order-sync.service`	6.3	Online order ingestion, BOPIS flow, fulfillment updates	Integration
118	`integration.shopify.webhook-handler.service`	6.3	Shopify webhook processing: orders/create, products/update, etc.	Event Handler

F.9.3 Amazon SP-API Integration

#	Service Name	BRD Section(s)	Capability	Pattern
119	`integration.amazon.catalog-sync.service`	6.4	Amazon catalog/listings management, compliance validation	Integration
120	`integration.amazon.order-sync.service`	6.4	Amazon order polling (2-min interval), FBM fulfillment	Integration
121	`integration.amazon.inventory-sync.service`	6.4	Amazon inventory feed, FBA + FBM channel quantities	Integration

F.9.4 Google Merchant Integration

#	Service Name	BRD Section(s)	Capability	Pattern
122	`integration.google.product-sync.service`	6.5	Google Merchant product data feed, disapproval prevention	Integration
123	`integration.google.inventory-sync.service`	6.5	Local inventory ads feed (2x/day batch)	Integration

F.9.5 Cross-Platform Orchestration

#	Service Name	BRD Section(s)	Capability	Pattern
124	`integration.cross-platform.validation.service`	6.6	Strictest-rule-wins validation across all channels	Rule Engine
125	`integration.cross-platform.inventory-orchestrator.service`	6.7	Safety buffer computation, channel allocation, saga compensation	Stateful (Saga)

F.9.6 Payment, Email & Shipping

#	Service Name	BRD Section(s)	Capability	Pattern
126	`integration.payment-processor.service`	6.8	Payment processor gateway abstraction (Stripe, Square)	Integration
127	`integration.email.service`	6.9	Email sending via provider abstraction (SendGrid, SES)	Integration
128	`integration.shipping.service`	6.10	Carrier rate lookup, label generation, tracking	Integration

F.10 Cross-Cutting Services (8 Services)

These services satisfy architecture requirements from the Blueprint (Ch 07, Ch 14) rather than direct BRD business sections. They provide infrastructure that all modules depend on.

#	Service Name	Blueprint Reference	Capability	Pattern
129	`crosscutting.event-store.service`	Ch 07 L.4A.1	Append events, optimistic concurrency, snapshot management	Stateful
130	`crosscutting.tenant.middleware.service`	Ch 07 L.10A.4	Tenant resolution from JWT, RLS policy enforcement	Stateful
131	`crosscutting.auth.service`	Ch 14	JWT validation, PIN authentication, permission checks	Stateful
132	`crosscutting.audit-log.service`	Ch 07 L.4A	Cross-cutting audit trail: who, what, when, before/after	Event Handler
133	`crosscutting.notification.service`	Ch 07	Push notifications, in-app alerts, SignalR real-time	Event Handler
134	`crosscutting.sync.orchestrator.service`	Ch 07 L.10A.1	Offline sync coordination: device registration, conflict resolution	Stateful
135	`crosscutting.report.engine.service`	Various	Saved report execution, scheduling, export (CSV/PDF)	Query
136	`crosscutting.state-machine.service`	Ch 07 L.4A	Database-driven state machine: validate transitions, log history	Rule Engine

Optional: RFID Module (Raptag, 6 Services)

#	Service Name	Blueprint Reference	Capability	Pattern
137	`rfid.config.crud.service`	Ch 10 D13	RFID tenant configuration (EPC prefix, serial counter)	CRUD
138	`rfid.tag.crud.service`	Ch 10 D13	Tag lifecycle: create, activate, sell, transfer, void	CRUD
139	`rfid.printer.crud.service`	Ch 10 D13	Printer registration, status monitoring	CRUD
140	`rfid.printjob.command.service`	Ch 10 D13	Print job queue management, progress tracking	Command
141	`rfid.scan.command.service`	Ch 10 D13	Scan session management: start, record reads, complete	Command
142	`rfid.inventory-reconciliation.service`	Ch 10 D13	Compare RFID scan results against expected inventory	Calculation

F.11 Module Dependency Matrix

F.11.1 Inter-Module Dependencies

Module 1 (Sales) --> Module 3 (Catalog):
  sale.cart.command.service --> catalog.product.query.service (lookup product/variant)
  sale.promotion.engine.service --> catalog.pricing.calculation.service (resolve price)
  sale.price-check.query.service --> catalog.product.query.service (read product)

Module 1 (Sales) --> Module 4 (Inventory):
  sale.finalize.command.service --> inventory.sale-deduction (via SaleCompleted event)
  sale.park.command.service --> inventory.reservation (soft-reserve on park)
  sale.void.command.service --> inventory.sale-deduction (via SaleVoided, restores)
  sale.return.command.service --> inventory.sale-deduction (via ReturnCompleted, restores)

Module 1 (Sales) --> Module 2 (Customers):
  sale.cart.command.service --> customer.profile.crud.service (attach customer)
  sale.loyalty.command.service --> customer.profile.crud.service (read loyalty)
  sale.payment.storecredit.service --> customer.profile.crud.service (check credit)

Module 1 (Sales) --> Module 5 (Setup):
  sale.tax.calculation.service --> setup.tax.crud.service (read tax rates)
  sale.shift.command.service --> setup.user.crud.service (validate employee)
  sale.cashdrawer.command.service --> setup.register.crud.service (validate register)

Module 1 (Sales) --> Module 6 (Integrations):
  sale.payment.card.service --> integration.payment-processor.service (card auth)
  sale.receipt.query.service --> integration.email.service (email receipt)

Module 3 (Catalog) --> Module 4 (Inventory):
  catalog.product.lifecycle.service --> inventory.level.query.service (check stock)

Module 4 (Inventory) --> Module 3 (Catalog):
  inventory.po.command.service --> catalog.vendor.crud.service (vendor details)
  inventory.reorder.engine.service --> catalog.product.query.service (product details)

Module 4 (Inventory) --> Module 5 (Setup):
  inventory.level.query.service --> setup.location.crud.service (location details)
  inventory.rules.engine.service --> setup.settings.crud.service (business rules)

Module 6 (Integrations) --> Module 3 (Catalog):
  integration.shopify.product-sync --> catalog.product.query.service (read products)
  integration.amazon.catalog-sync --> catalog.product.query.service (read products)
  integration.google.product-sync --> catalog.product.query.service (read products)
  integration.cross-platform.validation --> catalog.product.query.service (validate)

Module 6 (Integrations) --> Module 4 (Inventory):
  integration.shopify.inventory-sync --> inventory.level.query.service (read stock)
  integration.amazon.inventory-sync --> inventory.level.query.service (read stock)
  integration.google.inventory-sync --> inventory.level.query.service (read stock)
  integration.cross-platform.inventory-orchestrator --> inventory.level.query (allocate)

Module 6 (Integrations) --> Module 1 (Sales):
  integration.shopify.order-sync --> sale.finalize.command.service (create order)

Cross-Cutting --> All Modules:
  crosscutting.tenant.middleware.service --> ALL (RLS enforcement)
  crosscutting.auth.service --> ALL (permission checks)
  crosscutting.audit-log.service --> ALL (via event subscription)
  crosscutting.event-store.service --> Module 1, 4, 6 (ES-enabled modules)

F.11.2 Dependency Direction Rules

Rule	Description
Allowed	Module 1 –> Module 2, 3, 4, 5 (sales orchestrates)
Allowed	Module 6 –> Module 3, 4 (integrations read catalog/inventory)
Allowed	Module 4 –> Module 3 (inventory references catalog)
Forbidden	Module 2 –> Module 1 (customers cannot call sales)
Forbidden	Module 3 –> Module 1 (catalog cannot call sales)
Forbidden	Module 5 –> Module 1, 2, 3, 4 (setup is pure configuration)
Event-Only	Module 4 <– Module 1 (inventory reacts to sale events, not direct calls)

F.12 Service-to-BRD Traceability Matrix

Every BRD top-level section (x.y) maps to at least one service. Full bidirectional traceability:

Coverage Statistics

BRD Module	Sections	Services	Coverage
Module 1: Sales (1.1-1.20)	59 subsections	37 services	100%
Module 2: Customers (2.1-2.8)	10 subsections	7 services	100%
Module 3: Catalog (3.1-3.15)	48 subsections	20 services	100%
Module 4: Inventory (4.1-4.19)	55 subsections	23 services	100%
Module 5: Setup (5.1-5.21)	63 subsections	21 services	100%
Module 6: Integrations (6.1-6.13)	28 subsections	20 services	100%
TOTAL	263 subsections	128 services	100%

Criterion	Split (CQRS)	Keep Together (CRUD)
Write and read models differ significantly	Yes	–
Audit trail required (Event Sourcing)	Yes	–
Read-heavy with denormalized views	Yes (materialized projections)	–
Simple entity CRUD with no complex reads	–	Yes
Configuration data	–	Yes

F.13.2 CQRS Event Flow

1. Client sends Command (e.g., CreateSaleCommand)
       |
       v
2. Command Handler validates business rules
       |
       v
3. Aggregate produces Domain Events (e.g., SaleCreated, SaleLineItemAdded)
       |
       v
4. Events appended to Event Store (events table)
       |
       +---> 5a. Projection Handlers update Read Models (materialized views)
       +---> 5b. Audit Log Handler writes to audit_log
       +---> 5c. Outbox Relay publishes to external subscribers
       +---> 5d. Integration Handler triggers sync (Module 6)
              |
              v
6. Query reads from optimized Read Model (not event store)

F.13.3 Domain Events Summary

Aggregate	Module	Event Count
Sale	1 (Sales)	25
Return	1 (Sales)	5
Gift Card	1 (Sales)	4
Layaway/Hold	1 (Sales)	6
Cash Drawer	1 (Sales)	6
Inventory	4 (Inventory)	12
Customer	2 (Customers)	8
Employee	5 (Setup)	4
Integration	6 (Integrations)	10
TOTAL		80

F.14 Folder Structure Reference (Technology-Agnostic)

src/
+-- modules/
|   +-- sales/
|   |   +-- commands/
|   |   |   +-- cart/
|   |   |   +-- checkout/
|   |   |   +-- payment/
|   |   |   +-- return/
|   |   |   +-- cash-drawer/
|   |   |   +-- gift-card/
|   |   |   +-- layaway/
|   |   |   +-- hold/
|   |   +-- queries/
|   |   +-- events/
|   |   +-- event-handlers/
|   |   +-- domain/
|   |   |   +-- aggregates/
|   |   |   +-- value-objects/
|   |   |   +-- rules/
|   |   +-- repositories/
|   |   +-- dtos/
|   |
|   +-- customers/
|   |   +-- commands/
|   |   +-- queries/
|   |   +-- domain/
|   |   +-- repositories/
|   |
|   +-- catalog/
|   |   +-- commands/
|   |   |   +-- product/
|   |   |   +-- variant/
|   |   |   +-- pricing/
|   |   |   +-- category/
|   |   |   +-- bulk-import/
|   |   +-- queries/
|   |   +-- domain/
|   |   +-- cache/
|   |
|   +-- inventory/
|   |   +-- commands/
|   |   |   +-- adjustment/
|   |   |   +-- purchase-order/
|   |   |   +-- receiving/
|   |   |   +-- transfer/
|   |   |   +-- count/
|   |   |   +-- reservation/
|   |   |   +-- fulfillment/
|   |   +-- queries/
|   |   +-- events/
|   |   +-- event-handlers/
|   |   +-- domain/
|   |
|   +-- setup/
|   |   +-- commands/
|   |   +-- queries/
|   |
|   +-- integrations/
|   |   +-- core/
|   |   |   +-- provider-registry/
|   |   |   +-- circuit-breaker/
|   |   |   +-- outbox-relay/
|   |   |   +-- idempotency/
|   |   |   +-- webhook-pipeline/
|   |   |   +-- dead-letter/
|   |   +-- providers/
|   |   |   +-- shopify/
|   |   |   +-- amazon/
|   |   |   +-- google/
|   |   |   +-- payment/
|   |   |   +-- email/
|   |   |   +-- shipping/
|   |   +-- orchestration/
|   |   +-- anti-corruption-layer/
|   |
|   +-- rfid/
|       +-- commands/
|       +-- queries/
|       +-- domain/
|
+-- cross-cutting/
|   +-- event-store/
|   +-- tenant/
|   +-- auth/
|   +-- audit/
|   +-- sync/
|   +-- notifications/
|   +-- reporting/
|   +-- state-machine/
|
+-- shared/
|   +-- domain/
|   +-- interfaces/
|   +-- infrastructure/
|
+-- api/
    +-- controllers/
    +-- startup/

F.15 Summary Statistics

Metric	Value
BRD Modules	6
Code Modules	7 + cross-cutting + RFID
Total Services	142
Module 1 (Sales)	37 services
Module 2 (Customers)	7 services
Module 3 (Catalog)	20 services
Module 4 (Inventory)	23 services
Module 5 (Setup)	21 services
Module 6 (Integrations)	20 services
Cross-Cutting	8 services
RFID (Optional)	6 services
Domain Events	80
State Machines	19
BRD Decisions Mapped	107/107 (100%)
BRD Coverage	100% (all sections mapped)
Orphaned Capabilities	0

Service Pattern Distribution

Pattern	Count	%
CRUD	35	24.6%
Command	28	19.7%
Query	14	9.9%
Integration	13	9.2%
Stateful	12	8.5%
Event Handler	10	7.0%
Rule Engine	7	4.9%
Calculation	5	3.5%
Other (Orchestrator, Saga)	18	12.7%
TOTAL	142	100%

Migration from Current Service Layer

The current Chapter 11 defines 5 coarse-grained services. This mapping decomposes them:

Current Service (Ch 14)	Decomposed Into	Count
`IOrderService`	`sale.cart.`, `sale.park.`, `sale.discount.`, `sale.payment.`, `sale.finalize.`, `sale.void.`, `sale.return.`, `sale.exchange.`, `sale.layaway.`, `sale.hold-for-pickup.`, `sale.giftcard.`, `sale.receipt.`, `sale.history.*`	23
`IInventoryService`	`inventory.level.`, `inventory.po.`, `inventory.receiving.`, `inventory.transfer.`, `inventory.count.`, `inventory.rma.`, `inventory.reservation.`, `inventory.fulfillment.`	23
`ICustomerService`	`customer.profile.`, `customer.search.`, `customer.group.`, `customer.merge.`, `customer.privacy.`, `sale.loyalty.`	7
`IItemService`	`catalog.product.`, `catalog.variant.`, `catalog.search.`, `catalog.bulk-import.`	20
`IReportService`	`crosscutting.report.engine.service`, `sale.daily-summary.`, `inventory.dashboard.`, `catalog.analytics.*`	4
(new services)	`setup.`, `integration.`, cross-cutting, RFID	55

RFID Decisions (BRD v20.0, #108-113)

BRD v20.0 added 6 new decisions for the RFID Counting Subsystem:

#	Decision	Summary
108	RFID scope limited to counting only	No lifecycle tracking (sold_at, transferred_at stripped). Tag status limited to: active, void, lost
109	EPC serial generation via PostgreSQL SEQUENCE	Per-tenant SEQUENCE for serial numbers, not column-based last_serial_number
110	Chunked sync with 5,000 events per chunk	UNIQUE(session_id, epc) idempotency, resume via upload-status endpoint
111	RSSI-based multi-operator dedup	When multiple operators scan the same tag, highest RSSI wins for section assignment
112	Auto-save with 30-second SQLite checkpoint	Crash recovery dialog, battery-triggered saves on Raptag mobile app
113	Maximum 10 operators per counting session	Section assignment per operator, session_operators join table

Related services: rfid.tag.crud.service, rfid.session.command.service, rfid.scan.command.service, rfid.sync.command.service, rfid.config.crud.service, rfid.encoding.command.service

Document Information

Attribute	Value
Version	5.0.0
Created	2026-02-24
Updated	2026-02-25
Author	Claude Code
Status	Active
Section	Appendix F
BRD Version	20.0

This appendix is part of the POS Blueprint Book. All content is self-contained.

The POS Platform Blueprint