ryan/lunarfront-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aae5a022a8f65f06c005348d61fef03a8069a429
lunarfront-app/planning/12_Domain_Accounting_Journal_Entries.md
Ryan Moon 5f8726ee4e Add planning documents for Forte music store platform 
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
2026-03-27 14:51:23 -05:00

1219 lines
17 KiB
Markdown
Raw Blame History

Music Store Management Platform
Domain Design: Accounting & Journal Entries
Version 1.0 | Draft
# 1. Overview
The Accounting domain ensures every financial event in the platform produces correct double-entry journal entries. The platform does not replace QuickBooks — it generates journal entries that the store's accountant imports into QuickBooks on a regular schedule (daily, weekly, or monthly).
This is the Hybrid approach: the platform owns all operational financial data and generates the accounting records. QuickBooks owns the general ledger, financial statements, and tax reporting. The accountant works in a familiar tool. No real-time API dependency on QuickBooks is required.
Responsibility
Owner
Operational records
Platform — transactions, rentals, lessons, repairs, discounts, drawer
Journal entry generation
Platform — automatic on every financial event
Journal entry export
Platform — CSV export by date range, importable to QuickBooks
General ledger
QuickBooks — accountant imports exported entries
Financial statements
QuickBooks — P&L, balance sheet, tax reporting
Chart of accounts
Defined in platform, configurable per store to match QB setup
# 2. Chart of Accounts
The chart of accounts is defined in the platform and is store-configurable. Account codes and names should match the store's existing QuickBooks chart of accounts exactly to ensure clean imports. Default codes are provided below as a starting point.
## 2.1 Assets
Code
Account Name
Notes
1000
Cash - Store Drawer
Physical cash in main register
1010
Cash - Convention Drawer
iOS mobile POS cash
1100
Accounts Receivable
Amounts owed by customers
1200
Stripe Clearing
Card payments received but not yet paid out by Stripe
1300
Inventory - Sale Stock
Instruments and accessories for sale
1310
Inventory - Rental Fleet
Instruments held for rental
1320
Inventory - Parts & Supplies
Repair parts and consumables
## 2.2 Liabilities
Code
Account Name
Notes
2000
Sales Tax Payable
Tax collected from customers, owed to state
2100
Deferred Revenue - Rentals
Rental payments received for future periods
2110
Deferred Revenue - Lessons
Lesson payments received for future periods
2120
Deferred Revenue - RTO Equity
Rent-to-own equity portion — not earned until buyout
2200
Rental Deposits Held
Security deposits — liability until returned or applied
2300
Customer Credits
Store credits, makeup lesson credits
2400
Unearned Repair Revenue
Deposits on repairs not yet completed
## 2.3 Revenue
Code
Account Name
Notes
4000
Sales Revenue - Instruments
4010
Sales Revenue - Accessories
4020
Sales Revenue - Supplies
Strings, reeds, books, etc.
4100
Rental Revenue
Monthly rental income earned
4200
Lesson Revenue
Monthly lesson income earned
4300
Repair Revenue - Labor
4310
Repair Revenue - Parts
Parts billed to customer
4400
RTO Buyout Revenue
Recognized on rent-to-own completion
4500
Other Income
Kept deposits, late fees, misc
## 2.4 Contra Revenue
Code
Account Name
Notes
4900
Sales Discounts
Discounts applied at POS — keeps gross revenue clean
4910
Sales Returns & Refunds
Returned merchandise and refunded amounts
4920
Proration Credits Issued
Billing date change credits
## 2.5 Cost of Goods Sold
Code
Account Name
Notes
5000
COGS - Instruments
Cost of instruments sold
5010
COGS - Accessories
Cost of accessories sold
5020
COGS - Supplies
Cost of supplies sold
5100
Repair Parts Cost
Cost of parts used in repairs
## 2.6 Expenses
Code
Account Name
Notes
6000
Cash Over / Short
Drawer variance — over is credit, short is debit
6100
Payment Processing Fees
Stripe transaction fees
6200
Bad Debt Expense
Written-off account balances
6300
Inventory Shrinkage
Inventory adjustments and write-offs
# 3. Database Schema
## 3.1 account_code
Store-configurable chart of accounts. Each store maps platform account codes to their QuickBooks account names and numbers.
id, company_id, code (varchar), name (varchar),account_type (enum: asset|liability|revenue|contra_revenue|cogs|expense),quickbooks_account_name (varchar), ← must match QB exactly for importquickbooks_account_number (varchar),is_active (boolean), created_at
## 3.2 journal_entry
Header record for each accounting event. One journal entry per financial event — groups all debit and credit lines for that event.
Column
Type
Notes
id
uuid PK
company_id
uuid FK
entry_number
varchar
Human-readable JE number e.g. JE-2024-00142
entry_date
date
Accounting date — may differ from created_at
entry_type
enum
See section 4 for full list
source_entity_type
enum
transaction|rental|enrollment|repair|drawer_session|batch
source_entity_id
uuid
FK to the originating record
description
text
Human-readable description for accountant
total_debits
numeric(10,2)
Must equal total_credits
total_credits
numeric(10,2)
Must equal total_debits
export_batch_id
uuid
Set when entry is included in an export
exported_at
timestamptz
When exported — null if not yet exported
reconciled_at
timestamptz
When accountant confirmed import to QB
is_void
boolean
Voided entries excluded from exports
void_reason
text
Required if voided
created_by
uuid FK
System or employee
created_at
timestamptz
## 3.3 journal_entry_line
Individual debit and credit lines for each journal entry. Every entry must have at least one debit and one credit line and total_debits must equal total_credits.
Column
Type
Notes
id
uuid PK
journal_entry_id
uuid FK
account_code_id
uuid FK
Which account is affected
line_type
enum
debit | credit
amount
numeric(10,2)
Always positive — line_type determines direction
description
text
Line-level description
created_at
timestamptz
## 3.4 export_batch
Records each export operation for audit and reconciliation tracking.
id, company_id, exported_by (uuid FK), export_format (csv|iif),date_range_from, date_range_to, entry_count, total_amount,file_path (S3 URL), reconciled_at, created_at
# 4. Journal Entry Mappings
Every financial event generates one or more journal entries automatically. The following tables show the exact debit and credit mapping for each event type. All entries are generated by the platform — staff do not create journal entries manually.
## 4.1 Cash Sale
Debit
Credit
Notes
1000 Cash - Store Drawer
4000-4020 Sales Revenue
Revenue recognized at point of sale
1000 Cash - Store Drawer
2000 Sales Tax Payable
Tax collected from customer
5000-5020 COGS
1300 Inventory - Sale Stock
Cost of item removed from inventory
## 4.2 Card Sale (Stripe Terminal or Keyed)
Debit
Credit
Notes
1200 Stripe Clearing
4000-4020 Sales Revenue
Card payment in transit to bank
1200 Stripe Clearing
2000 Sales Tax Payable
Tax collected
5000-5020 COGS
1300 Inventory - Sale Stock
Cost of item sold
When Stripe pays out to bank account (triggered by Stripe payout webhook):
Debit
Credit
Notes
1000 Cash - Store Drawer
1200 Stripe Clearing
Funds settled from Stripe to bank
6100 Payment Processing Fees
1200 Stripe Clearing
Stripe fee deducted from payout
## 4.3 Discount Applied at POS
Debit
Credit
Notes
4900 Sales Discounts
4000-4020 Sales Revenue
Contra revenue — keeps gross revenue clean
Note: Gross revenue is always recorded at full price. The discount is recorded separately as a contra-revenue debit. Net revenue = Sales Revenue minus Sales Discounts. This gives the accountant visibility into both gross and net figures.
## 4.4 Sale Refund
Debit
Credit
Notes
4910 Sales Returns & Refunds
1000/1200 Cash or Stripe Clearing
Refund issued to customer
1300 Inventory - Sale Stock
5000-5020 COGS
Item returned to inventory at cost
2000 Sales Tax Payable
1000/1200 Cash or Stripe Clearing
Tax refunded
## 4.5 Rental Payment Received
Standard month-to-month rental — full payment is earned revenue:
Debit
Credit
Notes
1200 Stripe Clearing
4100 Rental Revenue
Monthly rental payment — earned immediately
1200 Stripe Clearing
2000 Sales Tax Payable
Tax if applicable to rentals in jurisdiction
## 4.6 Rent-to-Own Payment Received
RTO payments split between earned rental revenue and deferred equity portion:
Debit
Credit
Notes
1200 Stripe Clearing
4100 Rental Revenue
Rental portion — earned immediately
1200 Stripe Clearing
2120 Deferred Revenue - RTO Equity
Equity portion — not earned until buyout
## 4.7 Rent-to-Own Buyout Completed
When customer exercises buyout option — deferred equity is recognized as revenue:
Debit
Credit
Notes
2120 Deferred Revenue - RTO Equity
4400 RTO Buyout Revenue
Accumulated equity recognized on buyout
1200/1000 Stripe or Cash
4400 RTO Buyout Revenue
Remaining buyout balance collected
5000 COGS - Instruments
1310 Inventory - Rental Fleet
Cost of instrument transferred from fleet to sold
## 4.8 Rental Security Deposit Collected
Deposit is a liability — not revenue until earned or applied:
Debit
Credit
Notes
1000/1200 Cash or Stripe Clearing
2200 Rental Deposits Held
Deposit received — held as liability
## 4.9 Rental Deposit Returned
Debit
Credit
Notes
2200 Rental Deposits Held
1000/1200 Cash or Stripe Clearing
Deposit refunded to customer on return
## 4.10 Rental Deposit Kept (Damage)
Debit
Credit
Notes
2200 Rental Deposits Held
4500 Other Income
Deposit applied to damage — now earned income
## 4.11 Lesson Payment Received
Debit
Credit
Notes
1200 Stripe Clearing
4200 Lesson Revenue
Monthly lesson payment — earned for current month
Note: If the store policy is to recognize lesson revenue per session delivered rather than per month billed, the entry on payment would credit Deferred Revenue - Lessons (2110) and recognize revenue as each session is marked attended. Most small music stores bill monthly and recognize on billing — either approach is acceptable but must be consistent.
## 4.12 Makeup Lesson Credit Issued
Debit
Credit
Notes
4200 Lesson Revenue
2300 Customer Credits
Revenue reversed for undelivered lesson
## 4.13 Repair Payment Collected at Pickup
Debit
Credit
Notes
1000/1200 Cash or Stripe Clearing
4300 Repair Revenue - Labor
Labor charges collected
1000/1200 Cash or Stripe Clearing
4310 Repair Revenue - Parts
Parts charges collected
1000/1200 Cash or Stripe Clearing
2000 Sales Tax Payable
Tax on parts if applicable
5100 Repair Parts Cost
1320 Inventory - Parts & Supplies
Cost of parts consumed in repair
## 4.14 Repair Charged to Account
Debit
Credit
Notes
1100 Accounts Receivable
4300 Repair Revenue - Labor
Repair billed to account — not yet paid
1100 Accounts Receivable
4310 Repair Revenue - Parts
Parts billed to account
5100 Repair Parts Cost
1320 Inventory - Parts & Supplies
Cost of parts consumed
## 4.15 Account Payment Received
Debit
Credit
Notes
1000/1200 Cash or Stripe Clearing
1100 Accounts Receivable
Payment applied to outstanding balance
## 4.16 Bad Debt Write-Off
Debit
Credit
Notes
6200 Bad Debt Expense
1100 Accounts Receivable
Uncollectible balance written off — requires manager approval
## 4.17 Billing Date Change — Proration Credit
Debit
Credit
Notes
4920 Proration Credits Issued
1100/1200 AR or Stripe Clearing
Credit issued to customer for billing date shift
## 4.18 Billing Date Change — Proration Charge
Debit
Credit
Notes
1200 Stripe Clearing
4100/4200 Rental or Lesson Revenue
Additional charge for extended billing period
## 4.19 Inventory Purchase (Receiving PO)
Debit
Credit
Notes
1300 Inventory - Sale Stock
1100 Accounts Payable
Merchandise received — owed to vendor
1310 Inventory - Rental Fleet
1100 Accounts Payable
Rental fleet instruments received
## 4.20 Vendor Payment
Debit
Credit
Notes
1100 Accounts Payable
1000/1200 Cash or Bank
Payment to vendor for purchase order
## 4.21 Cash Drawer — Opening Float
Debit
Credit
Notes
1000 Cash - Store Drawer
1000 Cash - Store Drawer
Internal transfer — float set for shift (net zero)
## 4.22 Cash Drawer — Closing Variance
If drawer is over (more cash than expected):
Debit
Credit
Notes
1000 Cash - Store Drawer
6000 Cash Over / Short
Overage — credit to over/short account
If drawer is short (less cash than expected):
Debit
Credit
Notes
6000 Cash Over / Short
1000 Cash - Store Drawer
Shortage — debit to over/short account
## 4.23 Cash Drop Mid-Shift
Debit
Credit
Notes
1000 Cash - Safe / Vault
1000 Cash - Store Drawer
Cash moved from drawer to secure location
## 4.24 Batch Repair Invoice — School
Batch repair invoices follow the same pattern as individual repair payments but reference the batch record:
Debit
Credit
Notes
1100 Accounts Receivable
4300 Repair Revenue - Labor
Batch labor billed to school account
1100 Accounts Receivable
4310 Repair Revenue - Parts
Batch parts billed to school account
5100 Repair Parts Cost
1320 Inventory - Parts & Supplies
Cost of all parts used across batch
# 5. Journal Entry Validation
Every journal entry is validated before being written to the database. Validation failures block the originating financial event and alert staff.
- total_debits must equal total_credits — entries that do not balance are rejected
- Every line must reference a valid active account_code
- Entry date cannot be more than 30 days in the past without manager override
- Entry date cannot be in the future
- Voided entries generate a reversing entry — equal and opposite lines — rather than being deleted
- Reversing entries reference the original entry ID for traceability
# 6. QuickBooks Export
## 6.1 Export Format
Journal entries are exported as CSV in a format compatible with QuickBooks Desktop and QuickBooks Online import. Each row represents one journal entry line.
CSV Column
Source
Date
journal_entry.entry_date
Journal No
journal_entry.entry_number
Account
account_code.quickbooks_account_name — must match QB exactly
Debit
journal_entry_line.amount where line_type = debit
Credit
journal_entry_line.amount where line_type = credit
Description
journal_entry.description
Name
account.name where applicable — for AR/AP lines
Class
Optional — store name for multi-location QB setups
## 6.2 Export Workflow
- Staff or accountant selects date range for export
- System returns count of unexported entries in range for confirmation
- Export generated as CSV and stored in S3 — download link provided
- All included entries marked with export_batch_id and exported_at timestamp
- Entries already exported are excluded from subsequent exports by default
- Override option available to re-export a specific batch — requires manager approval
- Accountant imports CSV into QuickBooks — confirms successful import in platform
- Confirmed entries marked reconciled_at — visible in reconciliation report
## 6.3 Export Frequency Recommendation
Daily export is recommended for active stores to keep QuickBooks current. Weekly export is acceptable for lower-volume stores. Monthly export creates large import files and increases risk of errors going undetected. The platform supports any frequency — the accountant decides what works for their workflow.
# 7. In-Platform Accounting Reports
These reports are generated from journal entry data within the platform and do not require QuickBooks. They give the store owner operational financial visibility without waiting for the accountant's monthly close.
Report
Description
Revenue Summary
Revenue by category (instruments, rentals, lessons, repairs) by period
Gross vs Net Revenue
Gross revenue vs discounts vs net — shows discount impact
AR Aging
Outstanding account balances by age — current, 30, 60, 90+ days
Deferred Revenue
RTO equity, lesson credits, deposits held — future obligations
Cash Flow Summary
Cash in vs out by period — drawer, Stripe, deposits
Stripe Clearing Reconciliation
Amounts in clearing vs expected payouts — flags missing payouts
Export Status
Entries exported vs pending export — reconciliation tracking
Cash Over / Short History
Drawer variance by shift, employee, and register
COGS vs Revenue
Gross margin by product category
# 8. Business Rules
- Journal entries are generated automatically — staff never create entries manually
- Every financial event must produce a balanced journal entry before the event is committed
- Entries are immutable — corrections made via reversing entries only
- Voided entries generate equal and opposite reversing entries — never deleted
- Exported entries are not re-exported unless explicitly overridden with manager approval
- Chart of accounts is configurable per store — account names must match QuickBooks exactly
- Stripe clearing account must be reconciled against Stripe payout reports monthly
- Deferred revenue accounts reviewed quarterly — amounts that should have been recognized flagged
- Bad debt write-offs require manager approval and are logged in audit trail
- AIM migration historical transactions imported as journal entries with legacy_source tag — clearly separated from live entries in exports
Reference in New Issue View Git Blame Copy Permalink