alldigital/PSA
2
0
Fork 0
Code Issues Pull Requests Actions 15 Packages Projects Releases Wiki Activity
PSA/ee/docs/plans/2026-02-26-teams-v2-improvements/SCRATCHPAD.md
Hermes 284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Details
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Details
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
Details
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
Details
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Details
Integration Tests / Check for relevant changes (push) Waiting to run
Details
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Details
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Details
Mobile checks / Mobile unit tests (push) Waiting to run
Details
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Details
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Details
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Details
Temporal Readiness / fast-readiness (push) Waiting to run
Details
Temporal Readiness / docker-parity (push) Waiting to run
Details
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Details
Unit Tests / Skipped-test budget (push) Waiting to run
Details
Unit Tests / Nx affected unit tests (push) Waiting to run
Details
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Details
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Details
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
Details
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Details
Initial import of AlgaPSA codebase from PSA server 
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz

Source: /opt/alga-psa on psa.joliet.tech
2026-06-22 16:12:17 -05:00

14 KiB
Raw Blame History

Scratchpad — Teams V2 Improvements

  • Plan slug: teams-v2-improvements
  • Created: 2026-02-26
  • Parent plan: docs/plans/2026-02-26-teams-v2-org-hierarchy-operational-teams/

Decisions

  • (2026-02-26) Reversing the original non-goal: "Team logos or custom team icons" — now adding team avatar infrastructure.
  • (2026-02-26) Tab name changed from "Org Chart" to "Structure" (user confirmed).
  • (2026-02-26) Node click in org chart opens UserDetails drawer (user confirmed) — reuses existing drawer pattern from UserList.
  • (2026-02-26) Using ReactFlow for org chart (already installed v11.11.4, extensively used in workflow visualization).
  • (2026-02-26) Merging two ViewSwitchers into one row in CardHeader — eliminates duplicate list/org toggle.
  • (2026-02-26) Team avatars use existing document_associations + EntityImageService pattern — no new storage infrastructure needed.
  • (2026-02-26) TeamAvatar component follows exact pattern of UserAvatar (thin wrapper around EntityAvatar).
  • (2026-02-26) Extract team logic from MultiUserPicker into a new MultiUserAndTeamPicker component (user confirmed). Follows the same pattern as UserPicker → UserAndTeamPicker. MultiUserPicker stays team-free. Call sites swap via teams-v2 feature flag.

Discoveries / Constraints

  • (2026-02-26) EntityType is defined in 4 separate files that all need updating:
    • packages/media/src/lib/avatarUtils.ts (canonical backend)
    • packages/users/src/lib/avatarUtils.ts (user-specific copy)
    • packages/formatting/src/avatarUtils.ts (formatting copy)
    • packages/ui/src/components/EntityImageUpload.tsx (UI component)
  • (2026-02-26) document_associations CHECK constraint currently allows: 'asset','client','contact','contract','project_task','tenant','ticket','user' — need to add 'team'.
  • (2026-02-26) Latest constraint migration: server/migrations/20251020000001_add_document_folders_preview_and_contract_association.cjs uses NOT VALID pattern.
  • (2026-02-26) document_associations is distributed in Citus — migration needs exports.config = { transaction: false }.
  • (2026-02-26) reactflow v11.11.4 is already a dependency in both root and server package.json.
  • (2026-02-26) ReactFlow needs dynamic import with { ssr: false } in Next.js — proven pattern in packages/workflows/src/components/visualization/DynamicReactFlow.tsx.
  • (2026-02-26) Current org chart is simple recursive <ul> list at UserManagement.tsx lines 535-589 (buildOrgTree) and 570-589 (renderOrgNode).
  • (2026-02-26) Two duplicate ViewSwitchers for list/org toggle exist at lines 668-673 (list view) and 701-705 (org view).
  • (2026-02-26) UserAndTeamPicker.tsx lines 404-407 uses hardcoded gray circle + TeamIcon — 1 location to update.
  • (2026-02-26) MultiUserPicker.tsx has 4 locations with hardcoded TeamIcon (lines ~352, ~376, ~465, ~641).
  • (2026-02-26) MultiUserPicker has team logic deeply baked in: team props (lines 34-37), team filtering (lines 143-150), team rendering in trigger (lines 348-389, 458-488), team rendering in dropdown (lines 614-649), stale value cleanup (lines 116-127). This logic will move to MultiUserAndTeamPicker.
  • (2026-02-26) packages/teams/package.json currently only depends on @alga-psa/core, @alga-psa/db, @alga-psa/types, @alga-psa/validation. Needs: @alga-psa/media, @alga-psa/auth, swr.
  • (2026-02-26) Teams package has ./actions and ./hooks exports in package.json already.
  • (2026-02-26) useUserAvatar.ts is 29 lines — SWR hook pattern to replicate for teams.
  • (2026-02-26) User avatar actions in userActions.ts lines 1019-1179 — uploadUserAvatar, deleteUserAvatar — pattern to follow.

Links / References

  • Original teams-v2 plan: docs/plans/2026-02-26-teams-v2-org-hierarchy-operational-teams/
  • EntityAvatar component: packages/ui/src/components/EntityAvatar.tsx
  • UserAvatar component: packages/ui/src/components/UserAvatar.tsx
  • EntityImageUpload component: packages/ui/src/components/EntityImageUpload.tsx
  • EntityImageService: packages/media/src/services/EntityImageService.ts
  • Avatar utils (media): packages/media/src/lib/avatarUtils.ts
  • User avatar actions: packages/users/src/actions/user-actions/userActions.ts (lines 1019-1179)
  • User avatar hook: packages/users/src/hooks/useUserAvatar.ts
  • UserManagement: server/src/components/settings/general/UserManagement.tsx
  • UserDetails drawer: server/src/components/settings/general/UserDetails.tsx
  • TeamDetails: server/src/components/settings/general/TeamDetails.tsx
  • UserAndTeamPicker: packages/ui/src/components/UserAndTeamPicker.tsx
  • MultiUserPicker: packages/ui/src/components/MultiUserPicker.tsx
  • MultiUserAndTeamPicker (new): packages/ui/src/components/MultiUserAndTeamPicker.tsx
  • ViewSwitcher: packages/ui/src/components/ViewSwitcher.tsx
  • DynamicReactFlow pattern: packages/workflows/src/components/visualization/DynamicReactFlow.tsx
  • Workflow nodes: packages/workflows/src/components/visualization/nodes/
  • Team actions: packages/teams/src/actions/team-actions/teamActions.ts
  • Team model: packages/teams/src/models/team.ts

Open Questions

  • (None remaining — all questions resolved during planning)

Updates

  • (2026-02-27) Added migration server/migrations/20260227000001_add_team_to_document_associations_entity_type.cjs to include team in document_associations entity_type constraint with NOT VALID and transaction disabled.
  • (2026-02-27) Added team to media EntityType union in packages/media/src/lib/avatarUtils.ts.
  • (2026-02-27) Added team to users EntityType union in packages/users/src/lib/avatarUtils.ts.
  • (2026-02-27) Added team to formatting EntityType union in packages/formatting/src/avatarUtils.ts.
  • (2026-02-27) Added team to UI EntityType union in packages/ui/src/components/EntityImageUpload.tsx.
  • (2026-02-27) Added getTeamAvatarUrl helper to packages/media/src/lib/avatarUtils.ts.
  • (2026-02-27) Added TeamAvatar component in packages/ui/src/components/TeamAvatar.tsx as a thin EntityAvatar wrapper.
  • (2026-02-27) Added uploadTeamAvatar action with team update permission checks in packages/teams/src/actions/team-actions/avatarActions.ts.
  • (2026-02-27) Added deleteTeamAvatar action with team update permission checks in packages/teams/src/actions/team-actions/avatarActions.ts.
  • (2026-02-27) Added getTeamAvatarUrlAction in packages/teams/src/actions/team-actions/avatarActions.ts.
  • (2026-02-27) Added getTeamAvatarUrlsBatchAction with batch query logic in packages/teams/src/actions/team-actions/avatarActions.ts.
  • (2026-02-27) Exported team avatar actions from packages/teams/src/actions/team-actions/index.ts.
  • (2026-02-27) Added @alga-psa/media, @alga-psa/auth, and swr dependencies to packages/teams/package.json.
  • (2026-02-27) Added useTeamAvatar SWR hook in packages/teams/src/hooks/useTeamAvatar.ts.
  • (2026-02-27) Exported useTeamAvatar from packages/teams/src/hooks/index.ts.
  • (2026-02-27) Added team avatar upload UI to server/src/components/settings/general/TeamDetails.tsx using EntityImageUpload.
  • (2026-02-27) Wired team avatar upload UI to refresh avatar URL after changes via useTeamAvatar.
  • (2026-02-27) Added OrgChartNode ReactFlow node component in server/src/components/settings/general/org-chart/OrgChartNode.tsx.
  • (2026-02-27) Added OrgChartFlow component with ReactFlow canvas/provider in server/src/components/settings/general/org-chart/OrgChartFlow.tsx.
  • (2026-02-27) Added OrgChart layout logic to build hierarchy from reports_to and compute node positions in server/src/components/settings/general/org-chart/OrgChart.tsx.
  • (2026-02-27) Added smoothstep edges between parent/child nodes in OrgChart layout.
  • (2026-02-27) Confirmed OrgChartFlow uses fitView, zoom/pan, and non-draggable nodes for org chart interaction.
  • (2026-02-27) Wired OrgChart node clicks to open UserDetails via useDrawer.
  • (2026-02-27) Added batch avatar URL fetch for org chart nodes via getUserAvatarUrlsBatchAction.
  • (2026-02-27) Switched OrgChart flow rendering to dynamic import with ssr: false for ReactFlow safety.
  • (2026-02-27) Merged list/structure and portal-type ViewSwitchers into the CardHeader row in UserManagement.
  • (2026-02-27) Removed duplicate list/structure ViewSwitcher from list view toolbar in UserManagement.
  • (2026-02-27) Removed duplicate org view ViewSwitcher row from UserManagement.
  • (2026-02-27) Renamed org chart ViewSwitcher label to "Structure" in UserManagement.
  • (2026-02-27) Replaced nested-list org chart rendering with OrgChart component in UserManagement.
  • (2026-02-27) Removed legacy buildOrgTree and renderOrgNode helpers from UserManagement.
  • (2026-02-27) Confirmed Structure toggle and OrgChart rendering are gated behind the teams-v2 flag.
  • (2026-02-27) Swapped TeamIcon for TeamAvatar in UserAndTeamPicker team option rendering.
  • (2026-02-27) Added optional getTeamAvatarUrlsBatch prop to UserAndTeamPicker.
  • (2026-02-27) Added team avatar batch fetching on dropdown open in UserAndTeamPicker.
  • (2026-02-27) Created MultiUserAndTeamPicker component as a copy of MultiUserPicker in packages/ui/src/components/MultiUserAndTeamPicker.tsx.
  • (2026-02-27) Replaced TeamIcon usages with TeamAvatar in MultiUserAndTeamPicker.
  • (2026-02-27) Added team avatar batch fetching and getTeamAvatarUrlsBatch prop to MultiUserAndTeamPicker.
  • (2026-02-27) Removed team props and rendering logic from MultiUserPicker to make it user-only.
  • (2026-02-27) Swapped ticket filter assignee picker to MultiUserAndTeamPicker when teams-v2 is enabled.
  • (2026-02-27) Passed getTeamAvatarUrlsBatchAction into ticket filter MultiUserAndTeamPicker.
  • (2026-02-27) Team pickers now rely on TeamAvatar fallback initials instead of generic gray icons.
  • (2026-02-27) Added vitest coverage for migration constraint update (T082).
  • (2026-02-27) Marked T083 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T084 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T085 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T086 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T087 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T088 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T089 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T090 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T091 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T092 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T093 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T094 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T095 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T096 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T097 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T098 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T099 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T100 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T101 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T102 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T103 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T104 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T105 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T106 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T107 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T108 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T109 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T110 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T111 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T112 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T113 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T114 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T115 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T116 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T117 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T118 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T119 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T120 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T121 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T122 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T123 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T124 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T125 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T126 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T127 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T128 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T129 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T130 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T131 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T132 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T133 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T134 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T135 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T136 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T137 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T138 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T139 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T140 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T141 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T142 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T143 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T144 covered by teams-v2 improvements test suite.
  • (2026-02-27) Marked T145 covered by teams-v2 improvements test suite.
  • (2026-02-27) Added team avatar batch action to ticket detail picker (T146).
  • (2026-02-27) Marked ticket filter team avatar batch coverage (T147).
  • (2026-02-27) Marked no-TeamIcon picker coverage (T148).