lunarfront-app/planning/12_Domain_Accounting_Journal_Entries.md

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