# NSCC w/Accounting, HR and Payroll

> **AUTO-MAINTAINED** by `scripts/generate-finance-hr-payroll-blueprint.mjs`.  
> Do not hand-edit the generated module / collection tables below — change the source JS or the curated narrative file, then re-run the generator.  
> **Build:** `20260822_regdead1` · **Generated:** 2026-08-22

## How this stays current

1. Edit product prose in `scripts/finance-hr-payroll-blueprint-curated.md`.
2. Add/rename modules in `assets/nscc-back-office.js` (`ACCOUNTING_TABS`, `PAYROLL_TABS`, `HR_TABS`, and QBO subsets).
3. Add Firestore finance/HR keys in `assets/nscc-finance-config.js` (`FINANCE_COL_KEYS`).
4. Run `node scripts/generate-finance-hr-payroll-blueprint.mjs` (also on `scripts/ship.*` and CI deploy).

Agents: see `.cursor/rules/finance-hr-payroll-blueprint.mdc`.

---

## Product narrative

**NSCC w/Accounting, HR and Payroll** embeds Accounting, Payroll, and HR & Compliance in the same NorthStar Courier Command console as dispatch and field ops. Live production can still stage to Sage 300 CRE; the native stack keeps GL, AR, AP, bank, payroll, and HR workflows inside NSCC.

## Dual-mode architecture

| Mode | Surfaces | System of record |
|------|----------|------------------|
| Sage bridge | Live production console | Sage 300 CRE for posted AR / payroll / job cost; NSCC stages and verifies |
| Native (NSCC w/Accounting, HR and Payroll) | Demo 2 / native SKU | Firestore-backed GL, AR, AP, bank, payroll GL, HR workflows in NSCC |

## Design principles

1. **Operations → books** — delivered trips / shifts can draft AR and feed payroll time.
2. **One console** — Accounting, Payroll, and HR share left-nav + folder-tab chrome.
3. **Easy + Advanced** — QBO-style curated tabs by default; Advanced unlocks the full module set. **Pay field work** sits next to Invoices in Easy Accounting (not under Planning). Ops Easy keeps `Inventory`, `Projects`, `Trip & Shift Costing`, and **Checklists & Inspections**; Advanced adds work orders, **Quotes** (quote → accept as contract project → Job Cost), issued gear, maintenance / PM, subcontractors, and the coverage board. Ops **Projects** is a contract / site PM board (budget burn, health, milestones, linked work orders). Ops **Checklists & inspections** is the site/post schedule board; fillable templates live in **Forms** (including mobile apps) and submissions update Ops runs. Overlaps (Forms vs Ops checklists, Coverage vs HR Scheduling, Projects vs Trip & Shift Costing, Inventory vs Issued Gear) stay as separate screens with cross-links — hide unused ones in System Configuration. HR **Training** is Advanced-only immersive LMS (NSCC product-use course plus HR modules: video, docs, graphs, images, Open-in-NSCC jumps, assignments, compliance). Every folder option has a hover description for demos; modules a tenant will not use can stay tucked in Advanced or be **hidden** in System Configuration.
4. **QBO-level ease (outcomes over jargon)** — staff should achieve what they need (bill the client, run pay, close the week) without knowing accounting vocabulary. Labels, buttons, and empty states speak in ops language (“Create today’s invoices”, “Pay field work”, “Approve & post”) and hide ledger terms behind Advanced / tooltips. Clerks and supervisors are not expected to be accountants. **Pay field work** (Accounting) pays trips/hours from the field (including **personal-vehicle per-trip stipend** when mobile marks personal vs agency fleet); Payroll → **Pay runs** is tax / ACH / office pay runs. Native mode does **not** also enqueue Sage writeback on deliver.
5. **Auditability** — consequential finance actions write immutable audit events.
6. **Multi-state people ops** — HR regulations, filings, WC, and leave span IPS jurisdictions.
7. **Feature selection is System Configuration** — which HR/product modules are on, which outside payroll/screening companies apply, and tenant SKUs live in **System Configuration**, not on day-to-day Accounting / HR / Payroll screens. Staff see plain status (“Paying through: Practice mode”) and never choose API keys. Connection passwords stay in **Admin Console**. Unused modules can be turned off so they disappear from navigation. See `docs/NSCC_SYSTEM_CONFIGURATION.md`.

## Employee master (current vs target)

**Payroll-critical on the personnel HR record:** tax identity (legal name, DOB, SSN last 4 / ITIN), modern W-4 steps (filing status, multiple jobs, dependents $, other income, deductions, extra withholding), multi-state/local tax (resident state, work state(s), local jurisdiction), FLSA + employment class, cost center / GL, work location(s), direct deposit (bank + last-4 + type + %), termination / rehire. Saving the master record best-effort syncs W-4 / tax states onto the pay profile.

**Secondary on the same modal (not the payroll path):** I-9 status and emergency contact — workflow chrome, collapsed under “Secondary”.

**On the pay profile (separate):** pay basis/rate, modern W-4 + multi-state withholding (aligned with master), generic deductions, W-2 flag, cost center / FLSA mirrors.

**Still vaulted / confidential (do not publish full values):** full SSN (not last-4 only), licenses, benefit enrollments, garnishments, and PTO balances (Demo2 localStorage / side collections — not required on the master payroll path).

## Related documents

- UI / screen chrome standards: `docs/NSCC_UI_STANDARDS.md`
- Leadership brief: `docs/NSCC_NATIVE_FINANCE_EXECUTIVE_BRIEF.md` (charts/PDF via `scripts/build_native_finance_executive_pdf.py` when available; prose uses **NSCC w/Accounting, HR and Payroll**)
- Customer pack (CEO one-pager vs Sage + system + pay/billing for IPS): `docs/NSCC_ACCT_HR_PAYROLL_CUSTOMER_PACK.md`
- Implementation plan (module grid, setup order, training, timeline, RACI): `docs/NSCC_IMPLEMENTATION_PLAN.md`
- Pay & invoice scenarios appendix: `docs/NSCC_ACCT_PAY_INVOICE_SCENARIOS.md`
- Assumptions / questions: `docs/NSCC_ACCT_PAYROLL_ASSUMPTIONS.md` · `docs/NSCC_ACCT_PAYROLL_CUSTOMER_QUESTIONS.md`
- Enterprise readiness prep (tax/bureau/ACH; subscribe vs AI regs): `docs/NSCC_ENTERPRISE_READINESS_PREP.md` — Phase 0 includes Estimate-only tax banners and Leadership **Pillar readiness**. Customer **Decisions A/B** (risk · reward · cost) live in `docs/NSCC_ENTERPRISE_DECISIONS_AB.md` and System Configuration → Enterprise decisions.
- System Configuration (features, vendors, law packs vs Administration): `docs/NSCC_SYSTEM_CONFIGURATION.md`
- Data Dictionary (Firestore / pay-profile / Sage staging appendix): `docs/NSCC_DATA_DICTIONARY.md`
- System Documentation (overview + appendix TOC): `docs/SYSTEM_DOCUMENTATION.md`
- OAuth sign-in (high-level): `docs/OAUTH_SIGNIN.md`
- Sage bridge: `docs/NSCC_AR_AND_PAYROLL_IN_SAGE_300_CRE.md`
- Sage consultant: `docs/NSCC_SAGE_CONSULTANT_BRIEF.md`

---

## Accounting — full module catalog (26)

| Id | Label | Hint | Group |
|----|-------|------|-------|
| `overview` | Overview | Accounting home — open AR, cash position, net income, and shortcuts to the work you do most. | Day to day |
| `ar` | Invoices & Collections | Create and send customer invoices, apply payments, and chase open receivables. | Day to day |
| `fieldpayroll` | Pay field work | Pay courier/patrol/guard hours and trips from delivered work before a full payroll run. | Day to day |
| `statements` | Statements & Dunning | Customer balance statements and polite / firm dunning letters for overdue AR. | Day to day |
| `recurring` | Recurring Billing | Automate retainers and monthly contract invoices on a schedule. | Day to day |
| `banking` | Banking | Bank accounts, deposits, transfers, and reconcile the books to the bank. | Day to day |
| `feeds` | Bank Feeds | Import bank activity (CSV / OFX / API) and match rules to GL lines. | Day to day |
| `ap` | Bills & Payments | Enter vendor bills, approve them, and run payment batches. | Day to day |
| `credits` | Vendor Credits | Apply vendor credits and manage AP aging actions. | Day to day |
| `purchasing` | Purchasing | Purchase orders and three-way match against vendor bills. | Day to day |
| `attachments` | Attachments | Store PDFs and images on invoices, bills, and POs. | Day to day |
| `gl` | Journal Entries | Post journals and manual GL adjustments with audit-friendly detail. | Ledger |
| `coa` | Chart of Accounts | Maintain the GL account list and account structure. | Ledger |
| `assets` | Fixed Assets | Fleet and equipment register with depreciation tracking. | Ledger |
| `dimensions` | Dimensions | Tag transactions by department, class, customer, or site for reporting. | Ledger |
| `budget` | Budget | Annual budget vs actual so leadership can see plan vs spend. | Planning |
| `close` | Period Close | Month-end close checklist, period locks, and role controls. | Planning |
| `reports` | Reports | Operational registers and management financial packs (P&L, BS, aging). | Insights |
| `cashflow` | Cash Flow | 13-week cash forecast from AR, AP, and payroll timing. | Insights |
| `tax` | Tax & Deferred | Sales tax and deferred/retainer liability tracking. | Insights |
| `taxpacks` | Tax Filing Packs | Jurisdiction filing packs for sales/use and related returns. | Insights |
| `analytics` | Analytics | Trends, anomalies, and financial health signals for controllers. | Insights |
| `compliance` | Compliance | 1099 and payroll-tax reconciliation helpers. | Insights |
| `consolidation` | Consolidation | Division / entity P&L consolidation views. | Insights |
| `icmatch` | IC Matching | Intercompany matching and eliminations across entities. | Insights |
| `audit` | Audit Trail | Immutable finance log of who changed what and when. | Insights |


### Accounting — QBO easy mode (11)

| Id | Label | Hint | Group |
|----|-------|------|-------|
| `overview` | Dashboard | Accounting home — open AR, cash, and net income at a glance. | Accounting |
| `ar` | Invoices | Create customer invoices, apply payments, and collect open AR. | Sales |
| `fieldpayroll` | Pay field work | Pay field hours and trips from delivered work (before a full payroll run). | Sales |
| `statements` | Statements | Customer statements and dunning letters for open balances. | Sales |
| `recurring` | Recurring | Retainers and monthly contract billing on a schedule. | Sales |
| `ap` | Bills | Vendor bills, approvals, and payment runs. | Expenses |
| `banking` | Banking | Bank accounts, deposits, transfers, and reconciliation. | Expenses |
| `coa` | Chart of Accounts | GL account list and structure for the books. | Books |
| `gl` | General Ledger | Journals and manual GL entries with full detail. | Books |
| `reports` | Reports | Registers and management packs — P&L, balance sheet, aging. | Reports |
| `advanced` | Advanced | Show every accounting module. Many sites only need Easy mode — unused modules can stay hidden here or be turned off in System Configuration. | Mode |


## Payroll — full module catalog (12)

| Id | Label | Hint |
|----|-------|------|
| `profiles` | Pay Profiles | Rates, work states, deductions, and direct-deposit setup per employee. |
| `taxsetup` | Tax Setup | Multi-state withholding and SUI tax configuration. |
| `premiums` | Premiums | Armed, differential, hazard, and tip premium rules. |
| `garnishments` | Garnishments | Child support and levy garnishments on pay. |
| `calc` | Pay Calc | Gross-to-net calculation engine for a pay run. |
| `timeimport` | Time Import | Pull trips and shifts into payroll hours. |
| `ptosync` | PTO Sync | Sync approved leave into the pay calculation. |
| `today` | Pay Runs | Preview, approve, and post an office or combined pay run. |
| `ach` | ACH / Direct Deposit | Build NACHA / direct-deposit batch files for the bank. |
| `certified` | Certified Payroll | Prevailing-wage / certified payroll packs for contracts. |
| `pay-reports` | Payroll Reports | Registers, stubs, and labor cost reports. |
| `yearend` | Year-End | W-2 and 1099 year-end packages. |


### Payroll — QBO easy mode (5)

| Id | Label | Hint | Group |
|----|-------|------|-------|
| `today` | Pay runs | Preview tax, ACH, and office pay runs. Field hours/trips also live under Accounting → Pay field work. | Payroll |
| `profiles` | Employees | Employee pay profiles — rates, states, deductions, and deposits. | Setup |
| `pay-reports` | Reports | Payroll registers, stubs, and labor-cost reports. | Close-out |
| `yearend` | Year-End | Year-end W-2 and 1099 packages for filing. | Close-out |
| `advanced` | Advanced | Show every payroll module. Sites that do not need premiums, garnishments, or certified payroll can leave them hidden or turn modules off in System Configuration. | Mode |


## HR — full module catalog (21)

| Id | Label | Hint |
|----|-------|------|
| `hr` | Overview | Workforce hub with headcount, compliance flags, and state-rule awareness. |
| `org` | Org Chart | Reporting lines and org structure for the company. |
| `recruitment` | Recruitment | Candidate pipeline from application through hire stages. |
| `offers` | Offers / E-Sign | Offer letters and e-sign workflow for new hires. |
| `background` | Background Checks | Background screening requests and status tracking. |
| `i9` | I-9 / E-Verify | I-9 employment eligibility and E-Verify workflow. |
| `lifecycle` | Lifecycle | Hire → onboard → offboard status for each employee. |
| `leave` | Leave | PTO, sick, and PFML leave requests and balances. |
| `expenses` | Travel & Expense | Employee travel and expense report submission. |
| `benefits` | Benefits | Benefits enrollment and open-enrollment windows. |
| `scheduling` | Scheduling | Availability and headcount scheduling for HR planning. |
| `training` | Training | Advanced immersive LMS — NSCC product course plus HR modules with video, docs, graphs, images, and Open-in-NSCC walkthroughs (not on Easy HR). |
| `appraisals` | Appraisals | Performance reviews and appraisal cycles. |
| `documents` | Documents | Handbooks and personnel file documents. |
| `discipline` | Discipline | Personnel discipline log and corrective actions. |
| `wc` | WC Claims | Workers’ compensation claims tracking. |
| `wchandoff` | WC Handoff | Hand off a field incident into a WC claim. |
| `filings` | Filings | State SUI and new-hire filings. |
| `regulations` | Regulations | Multi-state HR regulations repository for IPS markets. |
| `retention` | Retention | Turnover and retention analytics. |
| `hr-reports` | Reports | HR reports — roster, training, WC, and filings. |


### HR — QBO easy mode (6)

| Id | Label | Hint | Group |
|----|-------|------|-------|
| `hr` | Overview | Workforce hub — headcount, compliance flags, and jump-ins to HR work. | HR |
| `lifecycle` | Employees | Hire → onboard → offboard lifecycle for each employee. | Hire |
| `leave` | Leave | PTO, sick, and PFML leave request workflows. | Employ |
| `documents` | Documents | Handbooks and personnel document files. | Employ |
| `hr-reports` | Reports | Roster, training, WC, and filings reports. | Insights |
| `advanced` | Advanced | Show every HR module. Many tenants will not need recruiting, benefits, or WC — hide unused modules in System Configuration so staff only see what they use. | Mode |


## Ops Field & Executive (14 tabs)

### Ops Field

| Id | Label | Hint |
|----|-------|------|
| `inventory` | Inventory | Track uniforms, PPE, radios, and similar stock issued to the field. |
| `projects` | Projects | Customer contracts with budget burn, milestones, health, and linked work orders. |
| `jobcost` | Trip & Shift Costing | See margin by trip and shift for field profitability. |
| `workorders` | Work Orders | Service tickets for site visits, repairs, and special coverage work. |
| `quotes` | Quotes | Formal quote → accept as contract project → track margin in Trip & Shift Costing (Advanced CRM pipeline). |
| `gear` | Issued Gear | Which radios, armor, devices, and kits are issued to which person or post. |
| `checklists` | Checklists & Inspections | Open / close, QC, and compliance walk completion by site and shift. |
| `maintenance` | Maintenance / PM | Preventive maintenance schedules for fleet-adjacent vehicles and field equipment. |
| `subcontractors` | Subcontractors | Vendor field crews, where they worked, and hours or units tied to the job. |
| `coverage` | Coverage Board | Open posts versus available people without opening full HR scheduling. |


### Executive dashboard

| Id | Label | Hint |
|----|-------|------|
| `executive` | Executive Summary | Company-wide CEO snapshot — finance, workforce, ops, and risk. |
| `controller` | Controller / CFO | Controller view: AR, AP, close, budget, and payroll cost. |
| `trends` | Trends & KPIs | Trailing-month trends and KPI sparklines for leadership. |
| `division` | Division & Regional | Line-of-business and regional scorecards. |


## Firestore collection keys (finance / payroll / HR)

| Constant | Collection key |
|----------|----------------|
| `CHART_OF_ACCOUNTS` | `chartOfAccounts` |
| `AR_INVOICES` | `arInvoices` |
| `AR_CUSTOMERS` | `arCustomers` |
| `AP_VENDORS` | `apVendors` |
| `AP_BILLS` | `apBills` |
| `AP_POS` | `apPurchaseOrders` |
| `PURCHASE_ORDERS` | `purchaseOrders` |
| `AP_PAYMENT_RUNS` | `apPaymentRuns` |
| `GL_ENTRIES` | `glEntries` |
| `SALES_TAX_CONFIG` | `salesTaxConfig` |
| `FINANCE_FOOTNOTES` | `financeFootnotes` |
| `INTERCOMPANY_BALANCES` | `intercompanyBalances` |
| `REGULATORY_REPOSITORY` | `regulatoryRepository` |
| `BANK_ACCOUNTS` | `bankAccounts` |
| `BANK_TRANSACTIONS` | `bankTransactions` |
| `BANK_RULES` | `bankRules` |
| `BUDGET_LINES` | `budgetLines` |
| `FIXED_ASSETS` | `fixedAssets` |
| `RECURRING_JOURNALS` | `recurringJournals` |
| `FISCAL_PERIODS` | `fiscalPeriods` |
| `CLOSE_CHECKLIST` | `closeChecklist` |
| `FINANCE_AUDIT_EVENTS` | `financeAuditEvents` |
| `MANUAL_JE_DRAFTS` | `manualJeDrafts` |
| `DEFERRED_REVENUE` | `deferredRevenue` |
| `VARIANCE_NOTES` | `varianceNotes` |
| `FOOTNOTES` | `financeFootnotes` |
| `PAYROLL_RUNS` | `payrollRuns` |
| `PAYROLL_SETTLEMENTS` | `payrollSettlements` |
| `PAYROLL_SYNC_REQUESTS` | `payrollSyncRequests` |
| `EMPLOYEE_PAY_PROFILES` | `employeePayProfiles` |
| `BACKGROUND_CHECK_REQUESTS` | `backgroundCheckRequests` |
| `WORKERS_COMP_CLAIMS` | `workersCompClaims` |
| `DISCIPLINE_LOG` | `disciplineLog` |
| `REGULATORY_FILINGS` | `regulatoryFilings` |
| `REGULATORY_DEADLINE_REMINDERS` | `regulatoryDeadlineReminders` |
| `HR_REGULATIONS` | `hrRegulations` |
| `PERSONNEL_DISCIPLINE` | `personnelDiscipline` |
| `HR_TRAINING` | `hrTraining` |
| `COLLECTION_CASES` | `collectionCases` |
| `MODULE_DOCUMENTS` | `moduleDocuments` |
| `OPS_HISTORY` | `opsHistory` |
| `HR_RECRUITMENT` | `hrRecruitment` |
| `HR_LEAVE_REQUESTS` | `hrLeaveRequests` |
| `HR_LEAVE_BALANCES` | `hrLeaveBalances` |
| `HR_APPRAISALS` | `hrAppraisals` |
| `HR_LIFECYCLE` | `hrLifecycle` |
| `HR_DOCUMENTS` | `hrDocuments` |
| `PERSONNEL_HR_RECORDS` | `personnelHrRecords` |
| `DEPARTMENTS` | `departments` |
| `COST_CENTERS` | `costCenters` |
| `EXPENSE_REPORTS` | `expenseReports` |
| `INVENTORY_ITEMS` | `inventoryItems` |
| `PROJECTS` | `projects` |
| `OPS_WORK_ORDERS` | `opsWorkOrders` |
| `OPS_QUOTES` | `opsQuotes` |
| `OPS_ISSUED_GEAR` | `opsIssuedGear` |
| `OPS_CHECKLISTS` | `opsChecklists` |
| `OPS_MAINTENANCE` | `opsMaintenance` |
| `OPS_SUBCONTRACTORS` | `opsSubcontractors` |
| `OPS_COVERAGE_BOARD` | `opsCoverageBoard` |
| `AR_STATEMENTS` | `arStatements` |
| `AR_DUNNING` | `arDunning` |
| `AR_RECURRING` | `arRecurring` |
| `BANK_FEEDS` | `bankFeeds` |
| `AP_VENDOR_CREDITS` | `apVendorCredits` |
| `IC_MATCHES` | `icMatches` |
| `TAX_FILINGS` | `taxFilings` |
| `DOC_ATTACHMENTS` | `docAttachments` |
| `PAY_TIME_IMPORT` | `payTimeImport` |
| `PAY_PREMIUMS` | `payPremiums` |
| `PAY_GARNISHMENTS` | `payGarnishments` |
| `PAY_ACH_BATCHES` | `payAchBatches` |
| `PAY_TAX_SETUP` | `payTaxSetup` |
| `PAY_CERTIFIED` | `payCertified` |
| `PAY_PTO_SYNC` | `payPtoSync` |
| `HR_ORG_CHART` | `hrOrgChart` |
| `HR_BENEFITS` | `hrBenefits` |
| `HR_I9` | `hrI9` |
| `HR_SCHEDULING` | `hrScheduling` |
| `HR_OFFERS` | `hrOffers` |
| `HR_RETENTION` | `hrRetention` |


## Key source files

- `assets/nscc-back-office.js` — Accounting / Payroll / HR tab catalogs
- `assets/nscc-finance-accounting.js` — Accounting shell renderer
- `assets/nscc-finance-config.js` — Firestore collection keys + native mode
- `assets/nscc-finance-hub.js` — Overview / hubs
- `assets/nscc-payroll-connect-ui.js` — Payroll Connect UI
- `assets/nscc-payroll-profiles.js` — Employee pay profiles
- `assets/nscc-payroll-adapter.js` — Provider adapters (Check / Gusto / sandbox)
- `assets/nscc-hr-regulations.js` — Multi-state regulations
- `assets/nscc-employee-center.js` — Employee center bridge
- `app-master-data.js` — Personnel master roster
- `app-nav.js` — Left nav + chrome folder tabs

## Live surfaces

| Surface | URL |
|---------|-----|
| Live | https://northstar-beacon.web.app/ |
| Demo | https://northstar-beacon.web.app/demo/ |
| Demo 2 (native finance) | https://northstar-beacon.web.app/demo2/ |
| Docs library | https://northstar-beacon.web.app/docs/library.html |