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

PRD — Storage Extraction & Phase 2 Cleanup

• Slug: storage-extraction-and-phase2-cleanup
• Date: 2026-02-19
• Status: Draft
• Analysis source: .ai/stale-code-and-cross-package-analysis.md

Summary

Single PR combining two concerns: (1) finish Phase 2 cleanup remainders (3 small mechanical fixes), and (2) extract @alga-psa/storage as a new horizontal package from @alga-psa/documents, eliminating ~10 cross-package violations where non-document packages import storage infrastructure from the documents domain package.

Problem

Phase 2 remainders: Three leftover items from previous cleanup phases:

• A broken import in portal-domain-sessions-prune.ts (references deleted file)
• 2 test files still importing from a server-side model that should use the package equivalent
• 1 re-export shim (server/src/lib/email/index.ts) with 1 source-code caller that should import directly

Storage in documents: The @alga-psa/documents package houses generic file-storage infrastructure (StorageService, StorageProviderFactory, providers, config, types) that has nothing to do with the documents domain. Five packages (billing, client-portal, jobs, server) import storage from documents, creating cross-package coupling. Storage is a horizontal concern that should be its own package.

Goals

1. Fix the 3 Phase 2 remainder items (broken import, stale test imports, email shim)
2. Create @alga-psa/storage package containing all file-storage infrastructure
3. Update all consumers (5 external + 5 documents-internal) to import from the new package
4. Add re-exports from @alga-psa/documents for backwards compatibility
5. Maintain build green throughout
6. Net reduction in cross-package violations

Non-goals

• No extraction of avatar/image utilities (they depend on documentActions -- circular)
• No extraction of formatting utilities (blocknoteUtils -- separate future PR)
• No extraction of the key-value storage API (storage/api/ -- different system entirely)
• No behavioral changes to any storage, email, or document functionality
• No new tests beyond verifying existing ones pass
• No Phase 2g (tax import porting) or Phase 3 work

Users and Primary Flows

Developer experience improvement. No end-user flows affected. File uploads, downloads, image handling, email, and portal domain sessions continue to work identically.

Requirements

Functional Requirements

Part A: Phase 2 Remainders

• FR-01: Fix broken import in server/scripts/portal-domain-sessions-prune.ts -- change 'server/src/lib/models/PortalDomainSessionToken' to '@alga-psa/auth'
• FR-02: Migrate 2 test files off server/src/models/document-association.ts:
  • server/src/test/unit/documentActions.upload.test.ts -- update mock to use @alga-psa/documents/models/documentAssociation
  • server/src/test/integration/documentPermissionsIntegration.test.ts -- update import to use @alga-psa/documents/models/documentAssociation
  • Add DocumentAssociation export to packages/documents/src/models/index.ts barrel
  • Delete server/src/models/document-association.ts
• FR-03: Update server/src/services/surveyService.ts to import from @alga-psa/email instead of ../lib/email
  • Delete server/src/lib/email/index.ts if no remaining source-code callers
  • Keep server/src/lib/email/README.md if it exists (documentation only)

Part B: Create @alga-psa/storage package

• FR-04: Create packages/storage/ with standard NX package scaffolding:

  • package.json with name @alga-psa/storage, dependencies on @alga-psa/db, @alga-psa/core, @alga-psa/auth, @alga-psa/event-bus, @alga-psa/shared, @alga-psa/validation
  • project.json with tags: ["scope:storage", "type:horizontal"]
  • tsconfig.json extending root
  • src/index.ts barrel file

• FR-05: Move these files from packages/documents/src/ to packages/storage/src/:

  • storage/StorageService.ts -> src/StorageService.ts
  • storage/StorageProviderFactory.ts -> src/StorageProviderFactory.ts
  • storage/providers/StorageProvider.ts -> src/providers/StorageProvider.ts
  • storage/providers/LocalStorageProvider.ts -> src/providers/LocalStorageProvider.ts
  • config/storage.ts -> src/config/storage.ts
  • types/storage.ts -> src/types/storage.ts
  • models/storage.ts -> src/models/storage.ts

• FR-06: Update all internal imports within moved files to use relative paths within the new package

• FR-07: Set up package.json exports for the new package:

  • . -> main barrel (StorageService, StorageProviderFactory, generateStoragePath, types)
  • ./StorageService -> src/StorageService.ts
  • ./types/storage -> src/types/storage.ts
  • ./providers/StorageProvider -> src/providers/StorageProvider.ts
  • ./config/storage -> src/config/storage.ts

Part C: Update consumers

• FR-08: Update 5 external consumers of StorageService to import from @alga-psa/storage/StorageService:

  • packages/billing/src/actions/invoiceJobActions.ts
  • packages/client-portal/src/actions/client-portal-actions/client-project-details.ts
  • packages/jobs/src/lib/jobService.ts
  • packages/jobs/src/lib/jobs/jobScheduler.ts
  • server/src/lib/imports/importActions.ts

• FR-09: Update 3 server consumers of StorageProviderFactory/generateStoragePath to import from @alga-psa/storage:

  • server/src/services/pdf-generation.service.ts
  • server/src/app/api/documents/view/[fileId]/route.ts
  • server/src/lib/storage/StorageService.ts

• FR-10: Update 1 consumer of FileStore type to import from @alga-psa/storage/types/storage:

  • packages/billing/src/services/pdfGenerationService.ts

• FR-11: Update 5 documents-internal consumers to import from @alga-psa/storage/StorageService (or relative within-package path):

  • packages/documents/src/handlers/OfficeDocumentHandler.ts
  • packages/documents/src/handlers/GenericFileDocumentHandler.ts
  • packages/documents/src/handlers/ImageDocumentHandler.ts
  • packages/documents/src/handlers/PDFDocumentHandler.ts
  • packages/documents/src/actions/file-actions/fileActions.ts
  • packages/documents/src/actions/documentActions.ts

• FR-12: Update packages/documents/src/lib/entityImageService.ts -- it imports StorageService, update path to @alga-psa/storage/StorageService

Part D: Backwards compatibility

• FR-13: Add re-exports to packages/documents/:
  • In src/index.ts: re-export StorageProviderFactory, generateStoragePath from @alga-psa/storage
  • In package.json exports: keep ./storage/StorageService pointing to @alga-psa/storage/StorageService (or re-export wrapper)
  • In package.json exports: keep ./types/storage pointing to @alga-psa/storage/types/storage (or re-export wrapper)
• FR-14: Add @alga-psa/storage as dependency in packages/documents/package.json

Non-functional Requirements

• Build must be green after the full PR
• No runtime behavioral changes to any storage, upload, download, or email functionality
• The @alga-psa/storage package must be tagged type:horizontal so the ESLint cross-package rule allows any package to import from it

Data / API / Integrations

No database, API, or integration changes. The external_files table continues to be accessed via FileStoreModel -- just from a different package location.

Security / Permissions

No security implications. All code changes are import-path redirections or file moves with identical implementations.

Rollout / Migration

No migration needed. Changes are internal to the build system. Ship as a single branch merged to main.

The re-exports in @alga-psa/documents ensure any consumers we miss (or that are added between now and merge) continue to work.

Open Questions

None -- all details verified via codebase analysis on 2026-02-19.

Acceptance Criteria (Definition of Done)

1. server/scripts/portal-domain-sessions-prune.ts imports from @alga-psa/auth and compiles
2. server/src/models/document-association.ts is deleted; tests import from @alga-psa/documents/models
3. server/src/lib/email/index.ts is deleted; surveyService.ts imports from @alga-psa/email
4. packages/storage/ exists with all 7 moved files
5. All 14 external + internal consumers updated to import from @alga-psa/storage
6. @alga-psa/documents re-exports storage symbols for backwards compatibility
7. npm run build passes
8. No new lint errors