# Scratchpad — Modular Dependency Slices (Billing ↔ Clients)

- Plan folder: `ee/docs/plans/2026-01-20-modularity-dependency-slices/`
- Date started: `2026-01-20`

## Current State (Discovery)
- There is an active effort to break a circular dependency between `@alga-psa/billing` and `@alga-psa/clients`.
- Temporary mitigation already introduced: dynamic import wrappers in billing:
  - `packages/billing/src/lib/clientsHelpers.ts`
  - Used by billing backend (e.g. `packages/billing/src/services/invoiceService.ts`) and billing UI (e.g. `packages/billing/src/components/billing-dashboard/BillingCycles.tsx`).
- There is also a clients→billing dynamic import:
  - `packages/clients/src/actions/clientContractActions.ts` dynamically imports `@alga-psa/billing/models/contract` to call `checkAndReactivateExpiredContract(...)`.

## Goal
Replace dynamic-import “escape hatches” with a new shared slice so dependencies flow down:
- `billing` → `shared-cross-slice`
- `clients` → `shared-cross-slice`
- No `billing` ↔ `clients` imports.

## Candidate “Cross Slice” Responsibilities
- Client contract assignment APIs (create/update/get/list) currently in clients but used by billing screens.
- Client lookup APIs used by billing screens (paginated + billing-cycle-range filtered).
- Default client tax region lookup currently in clients but used by billing invoice generation.
- Contract reactivation logic currently in billing contract model but invoked from clients.

## Decisions (Pending)
### Confirmed
- “Cross-dependencies” live in the existing lower slice `@alga-psa/shared` (not a new domain package).
- Move `ClientPicker` into `@alga-psa/ui` as part of this effort.
- Keep “default client tax region lookup” in `@alga-psa/shared` for now (no separate tax slice in this scope).
- Move contract reactivation-on-assignment-update logic into `@alga-psa/shared` so no billing import is needed from clients/shared.
- Pragmatic rule: limited *copying* of code is allowed to break dependencies without exploding package boundaries; if the same logic is copied >4 times, centralize it.

### Still open
- Exact `@alga-psa/shared` export/module path for these APIs (chosen: `@alga-psa/shared/billingClients`).

## Notes / Commands
- Find remaining billing imports of clients: `rg -n \"@alga-psa/clients\" packages/billing/src`
- Find remaining clients imports of billing: `rg -n \"@alga-psa/billing\" packages/clients/src`
- Existing plan folder format example: `ee/docs/plans/2026-01-09-billing-cycle-anchors/`
- Some code duplication and intentional copying is permissible if it simplifies modularization. We should be pragmatic!

## Scope Adjustment (2026-01-20)
- Validation focus: **build/typecheck checks only** to ensure deterministic builds and a clean dependency graph. Comprehensive new business-logic tests are intentionally deferred for this effort.

## Build Gotcha (2026-01-20)
- `npm run build` was failing in `server/src/invoice-templates/assemblyscript` because the installed `assemblyscript@0.27.36` package was missing its `dist/` folder (so `bin/asc.js` could not import `../dist/asc.js`).
- Fix: pin `assemblyscript` to the local tarball `assemblyscript-0.27.36.tgz` and run `npm install` with a repo-local cache (`--cache ../../../../.npm-cache`) to avoid global npm cache permission issues.

## Nx Cycle Follow-up (2026-01-20)
- `nx run-many -t build` revealed an additional cycle: `auth -> ui -> onboarding -> licensing -> auth`.
- Root cause: `@alga-psa/ui` contained onboarding-specific UI (wizard + dashboard onboarding widgets) and imported `@alga-psa/onboarding`.
- Fix: move onboarding-specific UI into `@alga-psa/onboarding` and keep `@alga-psa/ui` limited to shared UI primitives (wizard chrome, shared components).
- Also moved the onboarding wizard data shape (`WizardData`, etc.) down into `@alga-psa/types` to avoid `tenancy <-> onboarding` cycles.

## Nx Cycle Follow-up — UI Vertical Imports (2026-01-20)
- Additional cycle observed: `... -> auth -> ui -> tenancy -> client-portal -> clients -> ui`.
- Root cause: `@alga-psa/ui` contains multiple “feature” components that import vertical slice actions/components, including:
  - `@alga-psa/tenancy/actions` (branding + locale + tenant settings UIs)
  - `@alga-psa/users/actions` (user settings/profile/admin UIs; mentions search in editor; notification dropdown user lookup)
  - `@alga-psa/clients/actions` and `@alga-psa/clients/components` (settings and activity UIs)
  - `@alga-psa/client-portal/*` (domain settings entry, invitation flows)
- Fix strategy: move those “feature” components out of `@alga-psa/ui` into the owning vertical slice (e.g. `users`, `tenancy`, `client-portal`) or into top-level app (`server`), leaving `@alga-psa/ui` as pure, reusable UI primitives only.

## Nx Tooling Note (2026-01-20)
- On this worktree, `npx nx ...` frequently hangs while “Calculating the project graph on the Nx Daemon” under `node v25.1.0`, and `NX_DAEMON=false` can fail with `Failed to start plugin worker.`.
- Mitigation: the repo now pins Node to a supported range via `.nvmrc` (`20`) and root `package.json` `engines` (`>=20 <25`).
- Validation for this effort therefore relies on:
  - package typechecks (`tsc --noEmit`) for touched packages, and
  - import-greps confirming the key layering breaks (e.g. no `@alga-psa/ui` imports of `@alga-psa/tenancy|users|clients|client-portal`).

## Build Fixes (2026-01-20)
- Added CE stub component for EE policy settings so `server:build` can typecheck:
  - `server/src/empty/components/settings/policy/PolicyManagement.tsx`
- Fixed CE build typing for Temporal runner factory:
  - `server/src/lib/jobs/JobRunnerFactory.ts` casts the dynamically-imported `TemporalJobRunner` to `IJobRunner` (CE stubs don’t structurally match the server interface).
- Made Nx build fully offline-friendly by avoiding networked installs during sample component builds:
  - `sdk/samples/component/secrets-demo/package.json` uses `alga build --skip-install`.
- Fixed `workflow-worker:build` in CE by resolving `@ee/*` imports to the `@alga-psa/ee-stubs` sources instead of `server/src/empty`:
  - `services/workflow-worker/tsconfig.json` maps `@ee/*` → `packages/ee/src/*`.