PSA/ee/docs/plans/2026-02-19-storage-extraction-and-phase2-cleanup/SCRATCHPAD.md

Scratchpad — Storage Extraction & Phase 2 Cleanup

• Plan slug: storage-extraction-and-phase2-cleanup
• Created: 2026-02-19

What This Is

Rolling notes for the combined PR that finishes Phase 2 remainders and extracts @alga-psa/storage from @alga-psa/documents.

Decisions

• (2026-02-19) Storage extraction scope: move file-storage infrastructure only (StorageService, providers, factory, config, types, FileStoreModel). Keep avatar utils + entity image service in documents -- they have circular deps with documentActions.
• (2026-02-19) The storage/api/ subfolder (key-value storage service) is a DIFFERENT system from file StorageService. Leave it in documents for now -- it's unrelated to the cross-package violation problem.
• (2026-02-19) blocknoteUtils (formatting) is the cleanest extraction candidate (zero deps) but out of scope for this PR. Save for a separate @alga-psa/formatting extraction.
• (2026-02-19) Document-association migration: server version uses BaseModel.getTenant(), package version uses requireTenantId(). Tests mock DocumentAssociation directly -- need to update mock paths. The DocumentAssociation is not exported from packages/documents/src/models/index.ts barrel yet -- need to add export.
• (2026-02-19) Email shim: only 1 actual source caller (surveyService.ts). The rest are docs/README references (not real imports). Verify at implementation time.
• (2026-02-19) The server/src/lib/storage/StorageService.ts file also imports from @alga-psa/documents (StorageProviderFactory + generateStoragePath). This is a SEPARATE server-side StorageService wrapper that will need updating too.

Discoveries / Constraints

• (2026-02-19) StorageService.ts has @ts-nocheck at line 1 -- intentional for sharp dynamic import.
• (2026-02-19) StorageService depends on @alga-psa/event-bus/publishers for workflow events -- the new storage package will need this dependency.
• (2026-02-19) StorageService depends on @alga-psa/auth/getCurrentUser -- import exists but only used in one internal path. Keep dependency.
• (2026-02-19) StorageProviderFactory uses dynamic import for S3 provider (EE only): await import('./providers/S3StorageProvider') -- no S3 provider file exists in CE, that's expected.
• (2026-02-19) server/scripts/portal-domain-sessions-prune.ts imports from 'server/src/lib/models/PortalDomainSessionToken' -- this path doesn't exist anymore. The function is exported from @alga-psa/auth.
• (2026-02-19) FileStoreModel lives in packages/documents/src/models/storage.ts -- must move with StorageService since it's a direct dependency.
• (2026-02-19) External consumers of StorageService (outside documents): billing (1), client-portal (1), jobs (2), server (1) = 5 files.
• (2026-02-19) External consumers of StorageProviderFactory/generateStoragePath (via main documents index): server (3 files).
• (2026-02-19) External consumer of FileStore type: billing (1 file).

Commands / Runbooks

# Verify build after changes
npm run build

# Check for remaining references to old paths
grep -r "from '@alga-psa/documents/storage" packages/ server/ ee/ --include="*.ts" --include="*.tsx"
grep -r "StorageProviderFactory.*from '@alga-psa/documents'" packages/ server/ ee/ --include="*.ts" --include="*.tsx"
grep -r "from '@alga-psa/documents/types/storage" packages/ server/ ee/ --include="*.ts" --include="*.tsx"

# Check no references remain to deleted files
grep -r "document-association" server/src/test/ --include="*.ts" --include="*.tsx"
grep -r "lib/models/PortalDomainSessionToken" server/ --include="*.ts"
grep -r "from '@/lib/email'" server/ --include="*.ts" --include="*.tsx"
grep -r "from '../lib/email'" server/ --include="*.ts" --include="*.tsx"

Links / References

• Analysis source: .ai/stale-code-and-cross-package-analysis.md
• Previous cleanup plan: docs/plans/2026-02-17-stale-code-cleanup-phases-2c-2f/
• Storage source files: packages/documents/src/storage/
• Storage config: packages/documents/src/config/storage.ts
• Storage types: packages/documents/src/types/storage.ts
• Storage model: packages/documents/src/models/storage.ts

Open Questions

• Should server/src/lib/storage/StorageService.ts (server-side wrapper around documents' StorageProviderFactory) also be updated or moved? It's a different file from the package StorageService. For this PR: just update its import from @alga-psa/documents to @alga-psa/storage.

2026-02-20 Updates

• F001: Updated server/scripts/portal-domain-sessions-prune.ts to import pruneExpiredPortalDomainOtts from @alga-psa/auth to fix broken path.
• F002: Exported DocumentAssociation from packages/documents/src/models/index.ts barrel for package consumers.
• F003: Updated documentActions.upload.test.ts to mock/import DocumentAssociation from @alga-psa/documents/models/documentAssociation.
• F004: Switched documentPermissionsIntegration.test.ts to import DocumentAssociation from the documents package model path.
• F005: Removed obsolete server/src/models/document-association.ts after test imports migrated.
• F006: Updated server/src/services/surveyService.ts to import TenantEmailService from @alga-psa/email.
• F007: Deleted server/src/lib/email/index.ts shim after confirming no source imports remain.
• F008: Created packages/storage/package.json scaffold with required dependencies and build/typecheck scripts.
• F009: Added packages/storage/project.json with scope:storage + type:horizontal tags.
• F010: Added packages/storage/tsconfig.json extending the root config.
• F011: Moved packages/documents/src/types/storage.ts to packages/storage/src/types/storage.ts.
• F012: Moved packages/documents/src/config/storage.ts to packages/storage/src/config/storage.ts.
• F013: Moved StorageProvider base class to packages/storage/src/providers/StorageProvider.ts.
• F014: Moved LocalStorageProvider to packages/storage/src/providers/LocalStorageProvider.ts.
• F015: Moved FileStoreModel (models/storage.ts) into packages/storage/src/models/storage.ts.
• F016: Moved StorageProviderFactory.ts into packages/storage/src/StorageProviderFactory.ts.
• F017: Moved StorageService.ts to packages/storage/src/StorageService.ts.
• F018: Fixed relative imports inside storage package files (StorageProviderFactory, StorageService, provider classes) after move.
• F019: Added packages/storage/src/index.ts barrel exporting storage services, models, config, and types.
• F020: Added exports map to packages/storage/package.json for storage subpath entrypoints.
• F021: Updated billing invoiceJobActions.ts to import StorageService from @alga-psa/storage.
• F022: Updated client portal client-project-details.ts to import StorageService from @alga-psa/storage.
• F023: Updated jobs jobService.ts to import StorageService from @alga-psa/storage.
• F024: Updated jobs jobScheduler.ts to import StorageService from @alga-psa/storage.
• F025: Updated server/src/lib/imports/importActions.ts to import StorageService from @alga-psa/storage.
• F026: Updated server/src/services/pdf-generation.service.ts to import storage helpers from @alga-psa/storage.
• F027: Updated documents view API route to import StorageProviderFactory from @alga-psa/storage.
• F028: Updated server wrapper StorageService to import storage helpers from @alga-psa/storage.
• F029: Updated billing pdfGenerationService.ts to import FileStore from @alga-psa/storage/types/storage.
• F030: Updated document handlers to import StorageService from @alga-psa/storage/StorageService.
• F031: Updated fileActions.ts to import StorageService from @alga-psa/storage/StorageService.
• F032: Updated documentActions.ts to import StorageService from @alga-psa/storage/StorageService.
• F033: Updated entityImageService.ts to import StorageService from @alga-psa/storage/StorageService.
• F034: Re-exported StorageProviderFactory and generateStoragePath from @alga-psa/storage in documents index.
• F035: Added documents package export for ./types/storage and added thin re-export stubs for StorageService and storage types.
• F036: Added @alga-psa/storage dependency to packages/documents/package.json.
• F037: Added @alga-psa/storage dependency to billing, client-portal, and jobs package.json files.
• F038: Verified original storage implementation files removed from documents package; only thin re-export shims remain for compatibility.
• F039: Registered @alga-psa/storage path mappings in tsconfig.base.json (project.json already added earlier).
• T001: Verified portal-domain-sessions-prune import now points to @alga-psa/auth.
• T002: Confirmed DocumentAssociation is exported from documents models barrel.
• T003: Verified documentActions upload test imports DocumentAssociation from documents package.
• T004: Verified documentPermissions integration test now imports DocumentAssociation from documents package.
• T005: Confirmed server/src/models/document-association.ts has been removed.
• T006: Verified surveyService.ts imports TenantEmailService from @alga-psa/email.
• T007: Confirmed server/src/lib/email/index.ts removed.
• T008: rg found no remaining @/lib/email or ../lib/email imports in server source files.
• T009: Checked packages/storage/package.json for name, required deps, and exports entries.
• T010: Verified storage project tags include type:horizontal.
• T011: Confirmed storage tsconfig extends root tsconfig.
• T012: Confirmed ./StorageService export exists and source file is present in storage package.
• T013: Verified storage barrel exports StorageProviderFactory and generateStoragePath.
• T014: Confirmed ./types/storage export and source file exist in storage package.
• T015: Verified storage barrel exports FileStoreModel.
• T016: Confirmed storage providers export entry and source file for StorageError.
• T017: Ran npx tsc --noEmit -p packages/storage/tsconfig.json to confirm storage package imports resolve.
• T018: Verified billing invoiceJobActions imports StorageService from @alga-psa/storage.
• T019: Verified client portal project details action imports StorageService from @alga-psa/storage.
• T020: Verified jobs jobService imports StorageService from @alga-psa/storage.
• T021: Verified jobs jobScheduler imports StorageService from @alga-psa/storage.
• T022: Verified server importActions imports StorageService from @alga-psa/storage.
• T023: Verified pdf-generation service uses storage package imports.
• T024: Verified documents view route imports StorageProviderFactory from storage package.
• T025: Verified server StorageService wrapper imports storage helpers from @alga-psa/storage.
• T026: Verified billing pdfGenerationService imports FileStore from storage types.
• T027: Verified all document handlers import StorageService from @alga-psa/storage.
• T028: Verified fileActions imports StorageService from @alga-psa/storage.
• T029: Verified documentActions imports StorageService from @alga-psa/storage.
• T030: Verified entityImageService imports StorageService from @alga-psa/storage.
• T031: Confirmed documents index re-exports StorageProviderFactory from storage package.
• T032: Confirmed documents index re-exports generateStoragePath from storage package.
• T033: Verified documents exports include ./storage/StorageService shim and file exists.
• T034: Verified documents exports include ./types/storage shim and file exists.
• T035: Confirmed storage dependency present in documents, billing, client-portal, and jobs package.json files.
• T036: Confirmed original storage implementation files are removed from documents package (only compatibility shims remain).
• T037: Verified tsconfig path mappings include @alga-psa/storage.
• Added F040/T041: Next.js build failed resolving @alga-psa/storage/StorageService because server tsconfig paths lacked storage mapping; adding explicit path mapping to server/tsconfig.json.
• F040: Added @alga-psa/storage path mappings to server/tsconfig.json to satisfy Next.js module resolution.
• T041: Verified server tsconfig now maps @alga-psa/storage paths.
• Added F041/T042: Next build exposed VideoDocumentHandler still importing storage factory from deleted path; update to storage package.
• F041: Updated VideoDocumentHandler to import StorageProviderFactory from @alga-psa/storage.
• T042: Verified VideoDocumentHandler now imports StorageProviderFactory from storage package.
• Build attempt: npm run build timed out after 240s during Next.js build (no error before timeout).
• T039: Confirmed no source files reference server/src/models/document-association.
• T040: Confirmed no source files reference lib/models/PortalDomainSessionToken.
• Build attempt: npm run build progressed to Next.js build, then failed with OOM (heap out of memory) after warnings about workflow export conflicts and webpack critical deps.
• Added F042/T043: Next build failed because fileActions still referenced removed documents storage model/type paths; updated to storage package.
• F042: Updated fileActions.ts to pull FileStoreModel and FileStore from the storage package.
• T043: Verified fileActions imports storage model and type from @alga-psa/storage.
• Build attempt: NODE_OPTIONS=--max-old-space-size=8192 npm run build ran through Next build with warnings and static page generation, but command timed out at 6m (no success signal).
• T038: NODE_OPTIONS=--max-old-space-size=8192 npm run build completed successfully (warnings only).