slp-modular-cms/aidlc-docs/features/cms-frontend/construction/plans/unit-5-functional-design-plan.md

Functional Design Plan — Unit 5: User Management

Status: 🚧 In Progress

Unit Context

Unit: Unit 5 — User Management Type: Frontend (React/TypeScript) + minor backend addition Depends on: Unit 3 (AppLayout, RoleGuard), Unit 4 (TanStack Query patterns established) Stories Covered: US-10 (View list of users), US-11 (Invite a new user), US-12 (Share invite link)

Key Deliverables (from unit-of-work.md):

• frontend/src/api/useUsers.ts — useUsers hook (user list), useInviteUser mutation
• Update frontend/src/api/useInvitation.ts — align with established patterns
• frontend/src/components/users/InviteUserDialog.tsx — two-step: invite form → share link
• frontend/src/pages/UsersPage.tsx — replace placeholder with user table + invite dialog
• MSW mocks for user endpoints
• i18n keys for user management (en + nl)
• Unit tests

API Endpoints (backend):

• GET /api/v1/Users — list all users (NOT YET IMPLEMENTED in backend — see Q1)
• POST /api/v1/Users/invite — invite a user (requires AdminOnly policy; returns { inviteLink: string })
• GET /api/v1/Invitation/validate?token=... — validate token (anonymous, existing)
• POST /api/v1/Invitation/complete — complete invitation (anonymous, existing)

Key Observations:

• UsersPage.tsx is currently a placeholder ("Coming soon.") — full implementation needed
• useInvitation.ts uses raw useState/useEffect with local interfaces diverging from types.ts; Unit 4 established TanStack Query as the standard
• userHandlers.ts has a placeholder GET /Users MSW mock — needs full implementation
• Backend has no GET /Users endpoint yet — decision needed (Q1)

---

Functional Design Steps

• Step 1: Analyze unit context and existing code patterns
• Step 2: Generate questions, collect answers
• Step 3: Create domain-entities.md
• Step 4: Create business-rules.md
• Step 5: Create business-logic-model.md
• Step 6: Create frontend-components.md
• Step 7: Present completion message and await approval

---

Questions

Please fill in the letter after each [Answer]: tag.

---

Question 1: Backend GET /Users endpoint

The frontend needs a list of all users for UsersPage, but UsersController currently has no GET /Users endpoint. How should this be handled?

A) Add GET /api/v1/Users to the backend (UsersController) in this unit — returning id, email, displayName, role, isActive per user (recommended — required for the feature to function end-to-end) B) Use only the data already available in AuthContext (current logged-in user only) — no user list shown C) Other

---

Question 2: Who can access User Management?

The backend POST /Users/invite has [Authorize(Policy = "AdminOnly")]. Which roles should be able to view the UsersPage and invite users?

A) Owner and Administrator can view the user list and invite users; User role has no access to UsersPage (recommended — consistent with backend AdminOnly policy) B) Owner and Administrator can view the user list; only Owner can invite users C) All authenticated users can view the user list; only Owner and Administrator can invite D) Other

---

Question 3: Invitable roles

When inviting a user via the dialog, which roles can be assigned to the invitee?

A) Administrator and User only — Owner role is excluded (Owner is created via initial setup; there can only be one) (recommended — consistent with system design) B) All three roles: Owner, Administrator, User C) User only — no role selection; role is always User D) Other

Answer: D, Administrator and User only, but it is false that there can only be 1 Owner. Another owner can make another Admin an owner. Users cannot become an owner directly. There always has to be at least 1 owner

---

Question 4: User table columns

Which columns should the user table on UsersPage show?

A) Name, Email, Role, Status (Active/Inactive) — four columns, clean and informative (recommended) B) Name, Email, Role, Status, Created At — five columns including timestamp C) Email, Role, Status only — minimal D) Other

---

Question 5: TanStack Query migration for useInvitation.ts

The existing useInvitation.ts (from Unit 2) uses raw useState/useEffect and has local interfaces that diverge from types.ts. Unit 4 established TanStack Query as the standard for data fetching. Should useInvitation.ts be migrated to TanStack Query in this unit?

A) Yes — migrate useValidateInvitation (useQuery) and useCompleteInvitation (useMutation) to TanStack Query and align with types.ts (recommended — keeps all data-fetching uniform and removes the divergence) B) No — leave useInvitation.ts as-is; only new hooks (useUsers, useInviteUser) use TanStack Query C) Other

---

Question 6: InviteUserDialog — Step 1 form fields

Step 1 of the invite dialog collects the information to send an invitation. What should the form contain?

A) Email address + Role selector (Administrator / User) — two fields, minimal and sufficient (recommended — the backend InviteUserRequest only needs email and role) B) Email address, Role selector, and a display name field so the invitation is personalized C) Email address only — role defaults to User D) Other

---

Question 7: InviteUserDialog — Step 2 share link

After submitting the invite form successfully, the backend returns an inviteLink. How should Step 2 present the link to the inviting user?

A) Show the full invite link in a read-only text input with a "Copy to clipboard" button + close button (recommended — usable, transparent, and standard pattern) B) Show only a "Copy link" button — no visible URL in the UI C) Show a success message only with instructions to share the link manually (no copy button) D) Other

Answer: A, also make it possible to copy the link at a later point and also to refresh an invite token, for example when it is expired or you just require a new one for security reasons. The invite link should also be visible on the user details page for invited users that haven't completed their invitation yet.

---

Question 8: Unit test scope

Which parts of Unit 5 should have unit tests?

A) useUsers hook + useInviteUser mutation + InviteUserDialog (step 1 → step 2 flow) + UsersPage render with table data (recommended — covers all logic and UI paths) B) UsersPage integration test only — renders table + dialog flow end-to-end via MSW C) useUsers and useInviteUser hooks only — skip component tests D) Other