21 — Tax

Tax settings, rates, per-tenant config

CEO Summary

Tax settings determine how sales tax is calculated and reported. Per-tenant config. Business value: Compliance with local tax laws. Key metrics: Tax collected, accuracy. If this breaks: Incorrect tax on invoices; reporting errors.

Architecture

flowchart TB subgraph pos [POS / Invoicing] Cart[Cart] Inv[Invoice] end subgraph tax [Tax] TS[taxSettings.service] TR[taxSettings.routes] HR[hr/taxRates] BTI[hr/businessTaxInfo] end subgraph db [Tenant DB] TaxSettings[(tax_settings)] HRTables[(hr tables)] end Cart --> TS Inv --> TS TR --> TS HR --> HRTables BTI --> HRTables TS --> TaxSettings

Overview

Two tax domains: (1) Sales tax — POS, invoicing. (2) Payroll tax — HR.

Sales tax: taxSettings.service.js, taxSettings.routes.js
Payroll tax: hr/taxRates.routes.js, hr/businessTaxInfo.routes.js

File Structure

backend/
├── routes/
│   └── taxSettings.routes.js
├── services/
│   ├── tax.service.js
│   └── taxSettings.service.js
├── routes/hr/
│   ├── taxRates.routes.js      # Payroll tax rates
│   └── businessTaxInfo.routes.js
└── services/hr/
    ├── taxRates.service.js
    └── businessTaxInfo.service.js

Conventions

Term	Meaning
priceCents, taxCents	All amounts in cents
taxRateBps	Basis points (100 = 1%)

POS Integration

Cart has taxRateBps. Invoice stores tax_cents. Tax settings drive default rate per tenant/location. See 06 — POS & Invoicing.

HR Tax

taxRates: Payroll tax rates.

businessTaxInfo: Business tax info (EIN, etc.).

W-4: w4.service.js — employee withholding.

See 10 — HR & Payroll.

Integration Points

System	Connection
POS	Cart taxRateBps, Invoice tax_cents
Invoicing	coreInvoicing.service, invoicingConfig
HR	Payroll tax, W-4, business tax info

Key Paths

Path	Purpose
`backend/services/taxSettings.service.js`	Sales tax settings
`backend/config/invoicingConfig.js`	Tax defaults