284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
81 lines
6.1 KiB
Markdown
81 lines
6.1 KiB
Markdown
# 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/*`.
|