PSA/ee/docs/plans/2026-02-20-phase2g-backnav-notifications/SCRATCHPAD.md

Scratchpad: Tax Import Service Porting + BackNav Fix + Notification Reconciliation

Decisions

1. Skip adapters and externalTaxImportService — Moving accounting adapters to @alga-psa/integrations creates a circular dependency: integrations→billing→integrations (adapters import AccountingMappingResolver etc. from billing; billing imports QboClientService/XeroClientService from integrations). Deferred to future PR with a strategy to extract shared types to @alga-psa/types first.

2. Adopt package notification email.ts version — rate limiting is centralized in TenantEmailService.sendEmail(), inline check in server version is redundant.

3. Keep server emailLocaleResolver.ts — sendEventEmail.ts imports it locally. Don't force server infrastructure to import from package.

4. Delete orphan invoiceAdapters.ts — zero callers in server; the billing package has its own independent copy at packages/billing/src/lib/adapters/invoiceAdapters.ts.

5. Use @alga-psa/core for parseCSV — csvTaxImportService currently imports from server/src/lib/utils/csvParser, but @alga-psa/core exports the same function (already used by XeroCsvTaxImportService in the integrations package).

Key File Paths

Tax Import Services

• Source: server/src/lib/services/csvTaxImportValidator.ts (745 LOC)
• Source: server/src/lib/services/csvTaxImportService.ts (595 LOC)
• Source: server/src/lib/utils/csvFieldNormalizer.ts (323 LOC)
• Target: packages/integrations/src/services/ and packages/integrations/src/lib/
• Barrel: packages/integrations/src/services/index.ts (currently: export * from './email')
• Reference pattern: packages/integrations/src/services/xeroCsvTaxImportService.ts
• Caller: server/src/lib/api/controllers/ApiCSVAccountingController.ts

BackNav Fix

• Fix: packages/ui/src/components/BackNav.tsx line 7
• Target: packages/ui/src/context/UnsavedChangesContext.tsx (identical API)

Notification Dual-Copies

• Delete: server/src/lib/notifications/email.ts (561 LOC)
• Delete: server/src/lib/notifications/emailChannel.ts (7 LOC, identical to package)
• Keep: server/src/lib/notifications/emailLocaleResolver.ts (255 LOC)
• Keep: server/src/lib/notifications/emailService.ts (273 LOC)
• Keep: server/src/lib/notifications/sendEventEmail.ts (509 LOC)
• Keep: server/src/lib/notifications/NotificationAccumulator.ts (459 LOC)
• Package barrel: packages/notifications/src/index.ts — add getEmailNotificationService export
• Package email.ts: packages/notifications/src/notifications/email.ts (504 LOC)
• Package emailChannel: packages/notifications/src/emailChannel.ts (already in barrel)

Orphan Deletion

• Delete: server/src/lib/adapters/invoiceAdapters.ts (0 callers)

Discoveries

Circular Dependency: Adapters ↔ Billing

• server/src/lib/adapters/accounting/quickBooksOnlineAdapter.ts imports from @alga-psa/billing (AccountingMappingResolver, CompanyAccountingSyncService, etc.)
• server/src/lib/adapters/accounting/xeroAdapter.ts imports from @alga-psa/billing (same)
• server/src/lib/adapters/accounting/quickBooksCSVAdapter.ts imports from @alga-psa/billing
• server/src/lib/adapters/accounting/xeroCsvAdapter.ts imports from @alga-psa/billing
• packages/billing/src/services/companySync/adapters/xeroCompanyAdapter.ts imports from @alga-psa/integrations
• packages/billing/src/services/companySync/adapters/quickBooksCompanyAdapter.ts imports from @alga-psa/integrations
• Adding @alga-psa/billing to integrations package.json → circular dependency

Type Availability

• TaxSource, IExternalTaxImport, IExternalTaxImportResult — all in @alga-psa/types ✓
• AccountingExportBatch, AccountingExportLine — in packages/types/src/interfaces/accountingExport.interfaces.ts but NOT exported from barrel (needed for future adapter migration)
• parseCSV — available from @alga-psa/core ✓

Notification Differences

• Server email.ts (561 LOC) vs package email.ts (504 LOC): server has inline rate limiting (lines 399-412) that package removed
• emailLocaleResolver: functionally identical between server (255 LOC) and package (212 LOC), just different import paths
• emailChannel: byte-for-byte identical (7 LOC each)
• Package barrel already exports emailChannel but NOT EmailNotificationService/getEmailNotificationService

Callers Summary

csvTaxImportService:

• server/src/lib/api/controllers/ApiCSVAccountingController.ts — getCSVTaxImportService

email.ts (EmailNotificationService):

• server/src/lib/jobs/handlers/expiringCreditsNotificationHandler.ts — getEmailNotificationService

emailChannel:

• server/src/lib/eventBus/subscribers/ticketEmailSubscriber.ts — getEmailEventChannel
• server/src/lib/eventBus/subscribers/projectEmailSubscriber.ts — getEmailEventChannel
• server/src/lib/eventBus/publishers/index.ts — getEmailEventChannel
• server/src/lib/api/services/TicketService.ts — getEmailEventChannel
• server/src/test/integration/ticketEmailDelimiters.test.ts — EMAIL_EVENT_CHANNEL

Implementation Order

1. Move csvFieldNormalizer.ts → packages/integrations/src/lib/
2. Move csvTaxImportValidator.ts → packages/integrations/src/services/ (update csvFieldNormalizer import)
3. Move csvTaxImportService.ts → packages/integrations/src/services/ (update db, types, parseCSV imports)
4. Update integrations services barrel
5. Update ApiCSVAccountingController.ts caller
6. Delete server copies of tax services + csvFieldNormalizer
7. Fix BackNav.tsx import
8. Add getEmailNotificationService to notifications barrel
9. Update 6 notification callers
10. Delete server email.ts and emailChannel.ts
11. Delete orphan invoiceAdapters.ts
12. Verify build (npm run build && npm run build:shared)

Gotchas

• parseCSV signature: verify @alga-psa/core's parseCSV returns string[][] (same as server's csvParser). XeroCsvTaxImportService uses it with as string[][] cast.
• csvTaxImportValidator.ts uses any type for knex parameter — keep as-is, don't try to type-narrow in this PR.
• The packages/integrations/src/services/index.ts currently only exports ./email. Adding CSV tax exports here. Make sure the export doesn't conflict with any existing names.
• After deleting server emailChannel.ts, verify that sendEventEmail.ts doesn't import from it (it doesn't — only imports from emailLocaleResolver).
• DISCOVERED during implementation: emailService.ts (kept in server) also imports from ./emailChannel — needed to update this caller too (not in original plan's caller list). Updated to @alga-psa/notifications.
• DISCOVERED during implementation: UnsavedChangesContext in packages/ui/src/context/UnsavedChangesContext.tsx was declared with const (not export const). The server version exports it directly. Had to add export keyword to the package version for BackNav.tsx to import it.

Commands

# Verify build after changes
npm run build:shared && npm run build

# Check for remaining boundary violations
grep -r "from 'server/src/lib/services/csvTaxImport" --include="*.ts" --include="*.tsx" | grep -v "docs/"
grep -r "from 'server/src/contexts/UnsavedChangesContext" --include="*.ts" --include="*.tsx" packages/
grep -r "from.*lib/notifications/emailChannel" --include="*.ts" --include="*.tsx" server/src/
grep -r "from.*lib/notifications/email'" --include="*.ts" --include="*.tsx" server/src/