lunarfront-app/planning/03_Domain_Inventory.md

Music Store Management Platform

Domain Design: Inventory

Version 1.2 | Updated: Repair Parts Inventory, Bulk Materials, Suppliers

1. Overview

The Inventory domain manages all physical items in the store across three distinct inventories: sale inventory (items sold at POS), rental fleet (instruments held for rental), and repair parts inventory (materials consumed in repairs). Each inventory type has different tracking requirements, pricing models, and accounting treatment.

2. Inventory Types

Type

Tracking

Appears at POS

Examples

Sale — serialized

Per unit (serial #)

Yes — retail price

Guitars, trumpets, keyboards

Sale — non-serialized

Quantity on hand

Yes — retail price

Strings, reeds, books, picks

Rental fleet

Per unit (serial #)

No — rental only

Student rental instruments

Repair parts — discrete

Qty on hand (integer)

No — repair use only

Valve guides, springs, pads

Repair parts — bulk

Qty on hand (decimal)

No — repair use only

Bow hair, cork sheet, solder

Dual-use

Qty on hand (integer)

Yes — also used in repairs

Strings used in setups, valve oil

Shop supplies

Qty on hand (decimal)

No — overhead cost only

Cleaning patches, lubricant, sandpaper

3. Sale Inventory Schema

3.1 product

A product is the catalog definition — what an item is, not a specific physical unit. Applies to sale and rental fleet items.

Column

Type

Notes

id

uuid PK

company_id

uuid FK

Tenant scoping

location_id

uuid FK

Physical location — inventory is tracked per-location

sku

varchar

Store SKU

upc

varchar

Manufacturer barcode

name

varchar

description

text

brand

varchar

model

varchar

category_id

uuid FK

Product category

is_serialized

boolean

True = tracked per unit

is_rental

boolean

True = rental fleet item

is_dual_use_repair

boolean

True = also usable in repairs

cost

numeric(10,2)

Supplier cost

price

numeric(10,2)

Default retail price

min_price

numeric(10,2)

Minimum allowed sell price

rental_rate_monthly

numeric(10,2)

Default monthly rental rate

qty_on_hand

integer

Non-serialized items only

qty_reorder_point

integer

Low stock alert threshold

legacy_id

varchar

AIM inventory ID

created_at

timestamptz

3.2 inventory_unit

Individual physical units for serialized items and rental fleet instruments.

id, product_id, company_id, location_id, serial_number,condition (new|excellent|good|fair|poor),status (available|sold|rented|in_repair|retired),purchase_date, purchase_cost, notes,legacy_id, created_at

4. Repair Parts Inventory

Repair parts are a completely separate inventory from sale items. They are never sold at POS, never appear in the sales catalog, and are tracked specifically for repair cost accounting. The repair parts inventory is accessible only through the repairs module (MOD-REPAIRS).

4.1 Part Types

Part Type

Description

Invoice Treatment

billable

Parts charged to customer. Tracked at cost and bill rate.

Appears as line item on invoice at bill_rate

shop_supply

Consumed in repairs but not billed individually. Overhead cost.

Does not appear on invoice

dual_use

Also exists in sale inventory. Repair use decrements sale stock.

Billed at repair rate or retail

flat_rate_material

Material bundled into a flat-rate service charge. E.g. bow hair in a rehair service.

Included in flat rate line item — not itemized

4.2 Discrete vs Bulk Parts

Material Type

Tracked As

Examples

Discrete

Integer quantity — whole units only

Valve guides, pad sets, bridge blanks, spring sets

Bulk

Decimal quantity — fractional units allowed

Bow hair (hank), cork sheet, solder (spool), varnish (ml)

Bulk consumable

Decimal — consumed by drops/grams/ml

Lubricant, pad cement, shellac, jewelers rouge

4.3 repair_part

Column

Type

Notes

id

uuid PK

company_id

uuid FK

Tenant scoping

location_id

uuid FK

Physical location — repair parts stock is per-location

name

varchar

e.g. 'Bow Hair — Natural White (Standard)'

description

text

part_number

varchar

Manufacturer or supplier part number

part_type

enum

billable | shop_supply | dual_use | flat_rate_material

is_bulk

boolean

True = fractional qty tracking

unit_of_measure

varchar

each | hank | sheet | roll | spool | ml | gram | drop

qty_on_hand

numeric(10,3)

Decimal supports fractional bulk quantities

qty_reorder_point

numeric(10,3)

Low stock alert threshold

cost_per_unit

numeric(10,4)

What store pays per unit — 4 decimal places for small fractions

bill_rate_per_unit

numeric(10,2)

Nullable — what customer is charged per unit if billed per unit

billing_type

enum

per_unit | flat_rate | shop_supply

product_id

uuid FK

Nullable — links to sale inventory for dual_use parts

supplier_id

uuid FK

Primary supplier for reorders

instrument_categories

text[]

Which instrument types use this part

notes

text

is_active

boolean

created_at

timestamptz

4.4 repair_part_usage_template

Predefined templates define how much of a bulk material a specific job consumes. Technicians select a template rather than entering quantities manually. Particularly important for bow hair where qty varies by instrument size.

Column

Type

Notes

id

uuid PK

company_id

uuid FK

Tenant scoping

repair_part_id

uuid FK

Which part this template applies to

template_name

varchar

e.g. 'Full size violin bow rehair'

instrument_type

varchar

violin | viola | cello | bass | fractional | other

instrument_size

varchar

4/4 | 3/4 | 1/2 | 1/4 | 1/8 | full

qty_used

numeric(10,3)

Amount consumed e.g. 1.0 hank, 0.67 hank

billing_type

enum

per_unit | flat_rate | shop_supply

flat_rate_desc

varchar

Customer-facing description if flat rate

flat_rate_amount

numeric(10,2)

Nullable — flat rate bill amount

sort_order

integer

Display order in picker UI

created_at

timestamptz

Default Bow Hair Templates (System Seeded)

Template Name

Instrument

Qty Used

Typical Flat Rate

Full size violin/viola rehair

violin/viola

1.0 hank

$45-55 (store sets)

Cello bow rehair

cello

0.67 hank

$65-80

Bass bow rehair

bass

0.75 hank

$85-100

3/4 violin rehair

violin

0.75 hank

$35-45

1/2 violin rehair

violin

0.60 hank

$30-40

1/4 violin rehair

violin

0.50 hank

$25-35

1/8 and smaller

violin

0.40 hank

$20-30

4.5 repair_part_usage

Records each part consumed in a repair ticket. One record per part type per ticket. Referenced by repair_ticket for invoice generation and cost accounting.

Column

Type

Notes

id

uuid PK

repair_ticket_id

uuid FK

repair_part_id

uuid FK

Nullable for custom flat-rate entries

template_id

uuid FK

Nullable — set if selected from template

qty_used

numeric(10,3)

Actual quantity consumed

unit_of_measure

varchar

Recorded at time of use

unit_cost

numeric(10,4)

Cost at time of use — historical accuracy

total_cost

numeric(10,2)

qty_used * unit_cost

billing_type

enum

per_unit | flat_rate | shop_supply

billed_amount

numeric(10,2)

Amount on invoice — 0 for shop_supply

invoice_description

varchar

Customer-facing line item description

created_at

timestamptz

4.6 Bulk Material Examples

Material

Unit

Type

Notes

Bow hair — natural white standard

hank

flat_rate_material

Used via templates by bow size

Bow hair — natural white premium

hank

flat_rate_material

Higher grade — higher flat rate

Bow hair — black

hank

flat_rate_material

Bass/cello preference

Cork sheet — 1mm

sheet

billable

Cut to size for neck corks etc

Cork sheet — 2mm

sheet

billable

Thicker applications

Solder — silver bearing

spool

shop_supply

Overhead — not billed

Pad leather — natural

sheet

billable

Cut to size per pad

Shellac flakes

gram

shop_supply

Overhead

Pad cement

ml

shop_supply

Overhead

Valve oil (bulk)

bottle

shop_supply

Overhead — retail valve oil is separate sale item

Cleaning patches

each

shop_supply

Discrete but overhead

Abrasive paper — 220 grit

sheet

shop_supply

Overhead

Resonators — mylar

sheet

billable

Tone holes — billed per replacement

Fingerboard ebony blank

each

billable

Discrete — billed per blank used

Jewelers rouge

gram

shop_supply

Overhead

5. Supplier Management

Suppliers are the vendors from whom the store purchases repair parts and sale inventory. Common music repair suppliers include RS Musical, Ferree's Tools, and Allied Supply. Supplier records enable reorder tracking and purchase order generation.

5.1 supplier

Column

Type

Notes

id

uuid PK

company_id

uuid FK

Tenant scoping

name

varchar

e.g. 'RS Musical', 'Ferree’s Tools'

contact_name

varchar

Primary contact

email

varchar

phone

varchar

website

varchar

account_number

varchar

Store’s account number with this supplier

payment_terms

varchar

e.g. Net 30, COD, prepaid

notes

text

is_active

boolean

created_at

timestamptz

6. Repair Parts Reporting

• Parts on hand — current stock levels across all repair parts

• Low stock alerts — parts at or below reorder point

• Parts usage by period — which parts consumed most frequently

• Parts cost per repair ticket — material cost breakdown

• Technician material usage — parts consumed per technician

• Shop supply expense by period — overhead cost tracking

• Gross margin per repair — revenue vs labor cost vs parts cost

• Bow hair usage analysis — hanks used per month, yield per hank by bow type

• Reorder suggestions — parts below reorder point with preferred supplier

7. Business Rules

• Repair parts never appear in sale inventory search or POS catalog

• Dual-use parts decrement sale inventory qty_on_hand when used in repair

• Bulk qty_on_hand uses numeric(10,3) — supports fractional units down to 0.001

• cost_per_unit uses numeric(10,4) — supports very small per-unit costs for bulk materials

• Usage templates are store-configurable — seeded defaults provided, store can modify

• Shop supply parts reduce qty_on_hand but generate no invoice line item

• Flat-rate billing combines material + labor into one customer-facing line item

• Parts cost always recorded at time of use — price changes do not affect historical records

• Negative qty_on_hand not permitted — system warns technician when stock is insufficient