PSA/ee/docs/plans/company-sync-to-xero.md

Company ↔ Accounting System Sync Plan

Phase 1 – Discovery & Architecture (Status: ✅ Completed)

1. Audit current company usage (done):
   • Reviewed tenant_external_entity_mappings for existing company/client records and realm handling.
   • Catalogued required company fields across Xero and QuickBooks APIs.
   • Documented gaps between Alga’s company model and external requirements.
2. Define shared abstractions (done):
   • Specified AccountingCompanyAdapter interface and shared types.
   • Delivered orchestrator service (CompanyAccountingSyncService) contract and responsibilities.
   • Shipped server/src/lib/services/companySync module with service, repository, adapters, and normalizer skeleton.
   • Established metadata schema for stored mappings (sync tokens, raw payloads, realm-awareness).

Phase 2 – Shared Sync Layer Implementation (Status: ✅ Completed)

1. Implement orchestrator (done):
   • Built lookup/create/update workflow with tenant + realm awareness and in-memory caching.
   • Leveraged DB uniqueness for concurrency protection and handled duplicate insert races.
   • Left structured logging hooks for future telemetry pass.
2. Update AccountingMappingResolver (done):
   • Added ensureCompanyMapping helper and adapter-type normalization with caching.
   • Replaced direct table lookups with orchestrator integration.
3. Provide utility for data normalization (done):
   • Added DTO builder to convert Alga company data with sensible fallbacks for optional fields and contacts.

Phase 3 – Adapter Integrations (Status: 🟡 In Progress)

1. Xero (done):
   • Implemented XeroCompanyAdapter using XeroClientService with duplicate detection + metadata preservation.
   • Refactored XeroAdapter invoice transform to call ensureCompanyMapping during exports.
2. QuickBooks Online/Desktop (partial):
   • Delivered QuickBooksOnlineCompanyAdapter with sync token handling and wired invoice transform through ensureCompanyMapping.
   • Outstanding: QuickBooks Desktop parity and any additional realm nuances.
3. Manual sync endpoints (not started):
   • API triggers for per-company refresh remain to be designed and scoped.

Phase 4 – UI & Admin Enhancements

1. Integration settings:
   • Display company mapping status list (mapped/unmapped, last sync).
   • Provide “Link existing” and “Sync now” controls that invoke the shared service.
2. Export dashboard:
   • Surface mapping errors originating from the new service.
   • Indicate when a company was auto-created during export.

Phase 5 – Testing & Quality

1. Unit tests:
   • Extend xeroAdapter.spec.ts for creation vs reuse scenarios.
   • Update xeroClientService.spec.ts with contact payload/idempotency cases.
   • Add analogous tests for QuickBooks company adapters and client services.
2. Integration tests:
   • Expand exportDashboard.integration.test.ts to cover auto-create, reuse, and concurrency.
   • Add API-level tests for manual sync endpoints.
3. Sandbox QA:
   • Validate end-to-end flows in a tenant with both Xero and QuickBooks connections.
   • Run backfill script and verify mappings/audit logs.

Phase 6 – Rollout & Backfill

1. Deployment readiness:
   • Document configuration changes, feature flags, and rollback steps.
   • Ensure observability dashboards/alerts are in place.
2. Backfill execution:
   • Run orchestrator-driven job to populate missing company mappings.
   • Monitor for failures; re-run or queue manual review as needed.
3. Post-release monitoring:
   • Track export success rates and mapping creation events.
   • Collect feedback from finance teams for iterative improvements.