PSA/ee/docs/plans/2026-01-15-nx-monorepo-modularization/ralph-loop.local.md

Ralph Loop State - NX Monorepo Modularization

Current Progress: 38 features implemented

Completed Horizontal Slice Modules

@alga-psa/core (F004-F008)

• Location: packages/core/
• Contents:
  • Logger (winston-based logging)
  • Secret providers (8 files: ISecretProvider, EnvSecretProvider, FileSystemSecretProvider, CompositeSecretProvider, VaultSecretProvider, secretProvider, vaultLoader, getSecret)
  • Event publisher (with workflow dependencies from @alga-psa/shared)
  • Encryption utilities (hashPassword, verifyPassword, generateSecurePassword)

@alga-psa/db (F009-F014)

• Location: packages/db/
• Contents:
  • Knex configuration (knexfile.ts)
  • Knex turbopack shim (dialect patching)
  • Tenant context management (getConnection, withTransaction)
  • Admin connection (getAdminConnection, destroyAdminConnection)
  • Connection management (cleanupConnections)
  • Transaction helpers (withKnexTransaction, withAdminTransaction)

@alga-psa/types (F015-F017)

• Location: packages/types/
• Contents:
  • Core types: attributes, general, tax, temporal
  • Email types: outbound (EmailMessage, EmailProviderConfig) and inbound (InboundEmailMessage, InboundEmailProviderConfig)
  • Interface definitions: client, contact, user, tag, subscription, validation, microsoft365-diagnostics
  • Ticket interfaces: ITicket, ITicketListItem, ITicketListFilters, IPriority, ITicketStatus, ITicketCategory, ITicketWithDetails
  • Project interfaces: IProject, IProjectPhase, IProjectTask, IProjectStatusMapping, ITaskChecklistItem
  • Status interfaces: IStatus, IStandardStatus, StatusItemType
  • Invoice interfaces: IInvoice, IInvoiceCharge, IInvoiceTemplate, InvoiceStatus, InvoiceViewModel, etc.
  • Contract interfaces: IContract, IContractWithClient, IClientContract, IContractLine, ContractStatus, etc.
  • Schedule interfaces: IScheduleEntry, IRecurrencePattern, IResource, IWorkItem, WorkItemType, etc.

@alga-psa/validation (F018-F021)

• Location: packages/validation/
• Contents:
  • Validation utilities (isValidEmail, validateData, validateArray, isValidUUID, validateTenantAccess)
  • Common Zod schemas (iso8601, plainDate, tenant, uuid, email, phone, currency, pagination)

@alga-psa/ui-kit (F022, F024, F025) - Pre-existing

• Location: packages/ui-kit/
• Contents:
  • 11 existing components
  • Theme tokens CSS
  • Component hooks

@alga-psa/auth (F026, F028)

• Location: packages/auth/
• Contents:
  • Session utilities (getSessionMaxAge, getSessionCookieName, getSessionCookieConfig)
  • JWT encoding (encodePortalSessionToken, buildSessionCookie)
  • Secret management (getNextAuthSecret, getNextAuthSecretSync)

Completed Vertical Slice Modules

@alga-psa/clients (F031, F035)

• Location: packages/clients/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Client model (tenant-explicit API for multi-tenant safety)
  • Client validation schemas (ClientSchema, CreateClientSchema, UpdateClientSchema)
• Pending:
  • F032: 26 action files migration (tightly coupled to Next.js Server Actions)
  • F033: 32 client components migration
  • F034: 12 contact components migration

@alga-psa/billing (F038, F045)

• Location: packages/billing/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Invoice model (tenant-explicit API for multi-tenant safety)
  • Contract model (tenant-explicit API with expiration management)
  • Invoice interfaces (IInvoice, IInvoiceCharge, InvoiceStatus, etc.) in @alga-psa/types
  • Contract interfaces (IContract, IContractWithClient, IClientContract, etc.) in @alga-psa/types
• Pending:
  • F039: 120 billing-dashboard components migration
  • F040-F044: Invoice actions, contract actions, payment, credit, tax service migration

@alga-psa/projects (F047, F050)

• Location: packages/projects/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Project model (tenant-explicit API for multi-tenant safety)
  • Phase management (add, update, delete phases)
• Pending:
  • F048: 50 project components migration
  • F049: Project actions migration

@alga-psa/tickets (F052, F055)

• Location: packages/tickets/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Ticket model (tenant-explicit API for multi-tenant safety)
  • Priority model (tenant-explicit API, shared with projects)
  • Status model (tenant-explicit API, shared across modules)
• Pending:
  • F053: 19 ticket components migration
  • F054: Ticket actions migration

@alga-psa/scheduling (F057, F062)

• Location: packages/scheduling/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • ScheduleEntry model (tenant-explicit API for multi-tenant safety)
  • Schedule interfaces (IScheduleEntry, IRecurrencePattern, IResource, IWorkItem, etc.) in @alga-psa/types
• Pending:
  • F058: 32 time-management components migration
  • F059-F060: Schedule and technician-dispatch components
  • F061: Time entry actions migration

@alga-psa/workflows (F064)

• Location: packages/workflows/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models
• Pending:
  • F065: 24 workflow components migration
  • F066: product-workflows package consolidation
  • F067: Workflow actions migration

@alga-psa/documents (F069)

• Location: packages/documents/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models, handlers
• Pending:
  • F070: 18 document components migration
  • F071: 13 document handlers migration
  • F072: Document actions migration

@alga-psa/assets (F074)

• Location: packages/assets/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models
• Pending:
  • F075: 37 asset components migration
  • F076: Asset actions migration

@alga-psa/surveys (F078)

• Location: packages/surveys/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models
• Pending:
  • F079: 25 survey components migration
  • F080: Survey actions migration

@alga-psa/integrations (F082)

• Location: packages/integrations/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models, email
• Pending:
  • F083: 11 integration components migration
  • F084: 5 email packages consolidation
  • F085: QuickBooks integration migration
  • F086: Webhook handlers migration

@alga-psa/client-portal (F088)

• Location: packages/client-portal/
• Contents:
  • Module structure (package.json, tsconfig.json)
  • Placeholder directories for actions, components, models
• Pending:
  • F089: 42 client-portal components migration
  • F090: product-client-portal-domain consolidation

Remaining Work

Horizontal Slices (Deferred)

• F023: Migrate 81 UI components to @alga-psa/ui-kit (large task)
• F027: Migrate auth strategies (tightly coupled to NextAuth)
• F029: Migrate permission utilities (tightly coupled to User model and database)
• F030: Migrate getCurrentUser function (placeholder - depends on NextAuth)

Vertical Slices (Remaining Component Migrations)

• F058-F063: @alga-psa/scheduling component/action/model migrations (structure done in F057)
• F065-F068: @alga-psa/workflows component/action migrations (structure done in F064)
• F070-F073: @alga-psa/documents component/handler/action migrations (structure done in F069)
• F075-F077: @alga-psa/assets component/action migrations (structure done in F074)
• F079-F081: @alga-psa/surveys component/action migrations (structure done in F078)
• F083-F087: @alga-psa/integrations component/email/webhook migrations (structure done in F082)
• F089-F091: @alga-psa/client-portal component migrations (structure done in F088)

Technical Features (F092-F104)

• TypeScript path aliases
• CE/EE separation pattern
• NX computation caching
• NX remote caching for CI
• nx affected commands
• Module boundary enforcement

Backwards Compatibility (F105-F110)

• Re-exports from shared package
• Consumer updates

Tests Added

@alga-psa/billing tests

• Location: packages/billing/tests/
• Contents:
  • invoice.test.ts - Tests for Invoice model validation logic (tenant required, integer validation for amounts)
  • contract.test.ts - Tests for Contract model validation logic (tenant required for all operations)

@alga-psa/scheduling tests

• Location: packages/scheduling/tests/
• Contents:
  • scheduleEntry.test.ts - Tests for ScheduleEntry model validation logic (tenant required, recurrence pattern parsing)

Known Issues

1. TypeScript errors about @alga-psa/core, @alga-psa/types not found - expected until npm install links workspaces
2. Event publisher has temporary workflow dependencies from @alga-psa/shared
3. 81 UI components remain in server/src/components/ui (needs incremental migration)
4. getCurrentTenantId is tightly coupled to Next.js (headers, session) - vertical slice models use explicit tenant parameter
5. Server actions ('use server') cannot be migrated to packages - they stay in server/src but can call into package business logic

Summary Statistics

• Total Features: 110
• Implemented: 38 (34.5%)
• Phase 1 Complete: Yes (foundation modules established)
• Phase 2 Complete: All 11 vertical slice module structures created
• Phase 3-4: Model migrations in progress (clients, tickets, projects, billing, scheduling models done)