5f8726ee4e
17 domain design docs covering architecture, accounts, inventory, rentals, lessons, repairs, POS, payments, batch repairs, delivery, billing, accounting, deployment, licensing, installer, and backend tech architecture. Plus implementation roadmap (doc 18) and personnel management (doc 19). Key design decisions documented: - company/location model (multi-tenant + multi-location) - member entity (renamed from student to support multiple adults) - Stripe vs Global Payments billing ownership differences - User/location/terminal licensing model - Valkey 8 instead of Redis
3.0 KiB
Music Store Management Platform
Domain Design: Sales & Point of Sale
1. Overview
The Sales & POS domain handles all in-person and counter transactions — retail sales, deposits, repair payments, rental fees, and account charges. It integrates with Stripe Terminal for card-present payments and Stripe Elements for keyed entry.
2. Transaction Types
Type
Description
sale
Retail sale of product — instruments, accessories, supplies
repair_payment
Payment collected at repair ticket pickup
rental_deposit
Security deposit collected at rental start
account_payment
Payment against outstanding account balance
refund
Return of payment — full or partial
3. Database Schema
3.1 transaction
Column
Type
Notes
id
uuid PK
company_id
uuid FK
Tenant scoping
location_id
uuid FK
Physical location where transaction occurred
transaction_number
varchar
Human-readable ID
account_id
uuid FK
Nullable for anonymous cash sales
transaction_type
enum
sale|repair_payment|rental_deposit|account_payment|refund
status
enum
pending|completed|voided|refunded
subtotal
numeric(10,2)
Before tax and discounts
discount_total
numeric(10,2)
Total discounts applied
tax_total
numeric(10,2)
total
numeric(10,2)
Final amount charged
payment_method
enum
card_present|card_keyed|cash|check|account_charge
stripe_payment_intent_id
varchar
For card transactions
stripe_terminal_reader_id
varchar
Which reader was used
processed_by
uuid FK
Employee who processed
notes
text
created_at
timestamptz
3.2 transaction_line_item
id, transaction_id, product_id (nullable), inventory_unit_id (nullable),description, qty, unit_price, discount_amount, discount_reason,tax_rate, line_total, created_at
3.3 discount
id, company_id, location_id, name, discount_type (percent|fixed),discount_value, applies_to (order|line_item|category),requires_approval_above (threshold amount), is_active,valid_from, valid_until, created_at
3.4 discount_audit
id, transaction_id, transaction_line_item_id, discount_id,applied_by (employee_id), approved_by (employee_id, nullable),original_amount, discounted_amount, reason, created_at
4. Discount & Adjustment Rules
-
Discounts are applied at line item or order level
-
Discounts exceeding manager threshold require approval — logged in discount_audit
-
Manual price overrides treated as discounts — require reason code
-
Promotional codes validated against discount table before application
-
All discounts appear as line items on invoice — original price shown
-
Discount audit records are immutable — no deletion permitted
5. Payment Methods
Method
Integration
Notes
Card present
Stripe Terminal WiFi
Desktop — WisePOS E reader
Card present (BT)
Stripe Terminal BT
iOS — Bluetooth reader at conventions
Card keyed
Stripe Elements
Desktop — PCI safe, card data never touches app
Cash
Manual entry
Change calculated, drawer tracked
Check
Manual entry
Check number recorded
Account charge
Internal
Charges to account balance — billed later