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.7 KiB
Music Store Management Platform
Domain Design: Rentals
1. Overview
The Rentals domain manages instrument rental contracts, recurring billing, and rent-to-own tracking. Rentals are one of the most financially complex areas of the platform due to recurring Stripe subscriptions, multi-rental billing consolidation, and rent-to-own equity calculations.
2. Rental Types
Type
Description
Month-to-month
Standard rental — continues until returned or cancelled. No purchase obligation.
Rent-to-own
A percentage of each payment applies toward purchase price. Customer can buy out at any time.
Short-term
Hourly, daily, or weekly rental. Flat fee, no subscription. Common for events.
Lease purchase
Fixed-term contract with defined end purchase price.
3. Database Schema
3.1 rental
Column
Type
Notes
id
uuid PK
company_id
uuid FK
account_id
uuid FK
Billing account
member_id
uuid FK
Member who has the instrument
inventory_unit_id
uuid FK
Specific instrument rented
rental_type
enum
month_to_month | rent_to_own | short_term | lease_purchase
status
enum
active | returned | cancelled | completed
start_date
date
end_date
date
Null for open-ended rentals
monthly_rate
numeric(10,2)
Monthly charge amount
deposit_amount
numeric(10,2)
Security deposit collected
deposit_returned
boolean
billing_group
varchar
Groups rentals for consolidated billing
stripe_subscription_id
varchar
Stripe subscription reference
stripe_subscription_item_id
varchar
Line item if consolidated
rto_purchase_price
numeric(10,2)
Rent-to-own: full purchase price
rto_equity_percent
numeric(5,2)
% of payment applied to equity
rto_equity_accumulated
numeric(10,2)
Total equity built toward purchase
notes
text
legacy_id
varchar
AIM rental contract ID
created_at
timestamptz
3.2 rental_payment
Records each individual payment made against a rental — populated via Stripe webhook events.
id, rental_id, account_id, stripe_invoice_id, stripe_payment_intent_id,amount, rto_equity_applied, payment_date, status (paid|failed|refunded), created_at
4. Rent-to-Own Logic
When a rental is of type rent_to_own, each payment applies a percentage toward the purchase price.
-
rto_equity_accumulated increases by (monthly_rate × rto_equity_percent) each payment
-
Buyout amount = rto_purchase_price − rto_equity_accumulated
-
Staff can offer buyout at any time — triggers inventory_unit status change to 'sold'
-
On buyout, Stripe subscription is cancelled and a one-time charge is created for remaining balance
-
Invoice shows accumulated equity and remaining buyout balance
5. Billing Consolidation
5.1 Consolidated Billing
When billing_group is set to the same value on multiple rentals for the same account, they share one Stripe subscription with multiple line items. One charge per month covers all grouped rentals.
5.2 Split Billing
When billing_group is null, the rental has its own independent Stripe subscription. Useful when a customer wants rentals charged on different dates.
5.3 Adding a Rental Mid-Cycle
-
If consolidating: add new line item to existing subscription — Stripe prorates automatically
-
If split: create new standalone subscription with requested billing date
-
Invoice shows prorated amount for partial first month
6. Return Workflow
-
Staff records return — captures condition assessment
-
inventory_unit status updated to 'available' (or 'in_repair' if damage found)
-
Stripe subscription cancelled or line item removed
-
Deposit refund processed if applicable — logged in audit trail
-
Final invoice generated for any partial month charges
-
If damage found, repair ticket created automatically and linked to rental record