PSA/ee/docs/plans/2026-01-20-modularity-dependency-slices/PRD.md

PRD — Modular Dependency Slices (Eliminate Billing ↔ Clients Cycles)

• Slug: modularity-dependency-slices
• Date: 2026-01-20
• Status: Implemented

Summary

We have “domain slice” packages (e.g. @alga-psa/billing, @alga-psa/clients) intended to be vertically-owned modules. Today, billing ↔ clients have a bidirectional dependency that creates circular build graph issues and has prompted dynamic-import “escape hatches”.

This plan introduces a new lower slice that owns the cross-domain surface area (data access + server actions + (optionally) shared UI primitives) so dependencies go down (billing/clients → shared slice), and dynamic imports are removed.

Scope expansion (2026-01-20): additional NX build cycles were discovered involving @alga-psa/ui importing vertical slice actions/components (e.g. tenancy/users/clients/client-portal). This plan now also covers refactoring UI so it remains a true horizontal “lower slice” (no vertical imports), eliminating ui ↔ <domain> cycles that block nx run-many -t build.

Problem

Billing and Clients currently need each other:

• Billing needs client-facing data/actions/components (e.g. client selection, lookups, contracts per client, default tax region).
• Clients need billing domain logic/models (e.g. “reactivate expired contract” when a client contract assignment changes; tax settings UI embeds billing components).

This creates a bidirectional dependency which:

• Breaks static dependency analysis (NX graph cycles) and produces brittle build behavior.
• Encourages dynamic import patterns that can mask missing rebuilds and cause runtime-only failures.
• Violates the modularization goal: dependencies should be layered and flow down, not sideways.

Separately, @alga-psa/ui contains multiple “app feature” components that import vertical slice actions (users/tenancy/clients/client-portal). Because many vertical slices depend on @alga-psa/ui, this turns @alga-psa/ui into a pseudo-vertical and creates cycles like:

• ... -> auth -> ui -> tenancy -> client-portal -> clients -> ui

Goals

• Remove the billing ↔ clients bidirectional dependency entirely.
• Replace dynamic-import wrappers with static imports from a lower slice so builds and typechecking remain correct.
• Define a clear ownership boundary for “cross-domain” concerns (contracts assignments, client lookup for billing, client tax default region).
• Keep runtime behavior and UX unchanged (refactor only).
• Keep @alga-psa/ui “horizontal”: no imports from vertical slices (@alga-psa/* domains) so dependency flow is strictly down from features/apps into UI primitives.

Non-goals

• A full re-architecture of all domain slices across the repo.
• Redesigning billing/contracts or client onboarding UX.
• Consolidating all “tax” concerns across the whole product (scope is only what’s needed to remove the current cycles).
• Performance/observability work beyond what’s needed for safe refactoring.
• Comprehensive new automated test coverage (this effort focuses on restoring deterministic typechecks/builds and removing dependency cycles; build/typecheck checks are the primary validation).

Users and Primary Flows

Primary persona: internal engineers working on modularization, billing, and clients.

Primary flow:

1. Developer changes code in billing or clients.
2. The correct dependency chain triggers rebuild/typecheck deterministically.
3. No runtime-only failures caused by hidden dynamic imports or missing package builds.

Proposed Architecture

“Cross-dependencies” live in @alga-psa/shared

Use the existing @alga-psa/shared lower slice as the home for the shared surface area between billing and clients.

This shared module should:

• Depend only on lower layers (e.g. @alga-psa/db, @alga-psa/types, @alga-psa/core, @alga-psa/validation, @alga-psa/ui if UI primitives are moved there).
• Export server actions and/or models used by both @alga-psa/billing and @alga-psa/clients.
• Contain the “cross-domain” operations currently duplicated/entangled across slices:
  • Client contract assignment operations backed by client_contracts and contracts tables (create/update/get/list).
  • Client lookup for billing admin UIs (paginated lists, filtering by billing cycle ranges).
  • Default client tax region code retrieval used by invoice generation.

Shared UI primitives

Where feasible, move UI components that are “pure UI” (no domain-side imports) into @alga-psa/ui so all slices can use them without pulling in a domain package.

In-scope: move ClientPicker into @alga-psa/ui (it renders a picker but does not fetch clients; it receives clients as props).

UI “feature” code must move up

Any UI code that calls server actions or imports vertical slices must live in the owning vertical slice or in the top-level app (server / client-portal), not in @alga-psa/ui.

Examples of out-of-scope-for-UI patterns:

• @alga-psa/ui importing @alga-psa/tenancy/actions for tenant settings UI.
• @alga-psa/ui importing @alga-psa/users/actions for user management/profile UIs.
• @alga-psa/ui importing @alga-psa/clients/actions for client pickers/lists (UI can accept data via props instead).

Removing dynamic import escape hatches

After shared modules exist and imports are redirected, remove:

• packages/billing/src/lib/clientsHelpers.ts dynamic wrappers.
• packages/clients/src/lib/billingHelpers.ts dynamic wrappers (as applicable).
• Any remaining dynamic imports introduced only to break cycles (e.g. importing billing models from clients actions).

Requirements

Functional Requirements

• Billing UI can fetch clients and render billing screens without importing from @alga-psa/clients.
• Billing backend code can access client default tax region and relevant client data without importing from @alga-psa/clients.
• Clients-side operations that require billing contract logic can call into the new shared slice without importing from @alga-psa/billing.
• The dependency graph has no cycles between @alga-psa/billing and @alga-psa/clients.
• @alga-psa/ui contains only reusable UI primitives/hooks and does not import vertical slices (tenancy/users/clients/client-portal/auth/etc).

Non-functional Requirements

• Static dependencies only across packages; no dynamic import indirection used to bypass the build graph.
• Clear package ownership: cross-domain code lives in the shared slice; billing/clients slices remain vertically-owned.

Data / API Notes

No schema changes are expected; this is a code movement/refactor.

Server actions currently located in @alga-psa/clients/actions that are used by billing UIs should be relocated or wrapped (statically) in the shared slice.

Risks

• Moving server actions across packages can break import paths in Next.js client/server boundaries (must keep use server usage correct).
• Incremental build tools may require updating tsconfig path mappings / package exports.
• UI component moves (e.g. ClientPicker) can impact downstream imports across many packages.

Rollout / Migration Plan

1. Introduce the new shared slice package with a minimal exported surface.
2. Move/refactor the smallest “cycle-causing” APIs first (tax region + client contract assignment).
3. Redirect @alga-psa/billing and @alga-psa/clients to import from the shared slice (static imports).
4. Remove dynamic import helpers and verify the dependency graph is cycle-free.
5. Optional: move pure UI primitives (e.g. ClientPicker) into @alga-psa/ui and update imports repo-wide.

Open Questions

1. What should the @alga-psa/shared export surface and module path be for these cross-domain APIs (chosen: @alga-psa/shared/billingClients)?

Acceptance Criteria (Definition of Done)

• No code in @alga-psa/billing imports from @alga-psa/clients (actions or components).
• No code in @alga-psa/clients imports from @alga-psa/billing (actions, components, or models).
• No dynamic imports exist solely to break the billing↔clients dependency cycle.
• Dependency tooling (nx graph) reports no billing↔clients cycle or, if nx graph is too slow/unavailable in the current environment, we verify via (a) import-greps and (b) tsc --listFilesOnly / --explainFiles that billing does not compile clients and vice versa.
• npm run build (or the relevant package builds) succeeds with correct incremental rebuild behavior (changes in a dependency trigger builds).
• nx run-many -t build does not report cycles rooted in @alga-psa/ui (e.g. ui -> tenancy -> client-portal -> clients -> ui).