Domain Entities — Unit 5: User Management

Overview

Unit 5 introduces user listing, invitation management, and role changes. Two new backend endpoints are required: GET /api/v1/Users (list with invitation state) and PUT /api/v1/Users/{userId}/role (role assignment). The frontend extends types.ts with new interfaces for these operations.

Entity Diagram

graph LR
    UserListItem["UserListItem\nid, email, name, role\nisActive, createdAt\ninvitationPending, inviteLink"]
    UserRole["UserRole\nOwner, Administrator, User"]
    InviteUserRequest["InviteUserRequest\nemail, role"]
    InviteUserResponse["InviteUserResponse\ninviteLink"]
    ChangeRoleRequest["ChangeRoleRequest\nnewRole"]

    UserListItem -->|has role| UserRole
    InviteUserRequest -->|assigns role| UserRole
    ChangeRoleRequest -->|assigns| UserRole

    classDef entity fill:#2196F3,stroke:#0d47a1,stroke-width:1px,color:#000
    classDef request fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000
    classDef enumType fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000

    class UserListItem entity
    class InviteUserRequest,InviteUserResponse,ChangeRoleRequest request
    class UserRole enumType

Text alternative: UserListItem (blauw) heeft een UserRole enum (geel); InviteUserRequest en ChangeRoleRequest (groen) wijzen een UserRole toe.

Field Descriptions

UserListItem — GET /api/v1/Users response item

Field	Type	Description
id	string (UUID)	Unique user identifier
email	string	User's email address
name	string	Display name (DisplayName ?? Email fallback, consistent with AuthResponse)
role	UserRole	Current role: Owner, Administrator, or User
isActive	bool	Whether the account is active
createdAt	string (ISO 8601)	Account creation timestamp
invitationPending	bool	True when the user has not yet completed invitation setup
inviteLink	string \| null	Full invite URL for pending users; null for active accounts

InviteUserRequest — POST /api/v1/Users/invite

Field	Type	Description
email	string	Email address of the invitee
role	'Administrator' \| 'User'	Role to assign — Owner is excluded by business rule

InviteUserResponse — POST /api/v1/Users/invite response

Field	Type	Description
inviteLink	string	Relative URL for the invitation (e.g. `/invite/complete?token=...`)

ChangeRoleRequest — PUT /api/v1/Users/{userId}/role

Field	Type	Description
newRole	UserRole	Role to assign to the target user

Type Extensions — frontend/src/api/types.ts

The existing User type covers the logged-in session user. Unit 5 adds:

// User item returned by GET /api/v1/Users
export interface UserListItem extends User {
    createdAt: string;          // ISO 8601
    invitationPending: boolean;
    inviteLink: string | null;
}

// POST /api/v1/Users/invite
export interface InviteUserRequest {
    email: string;
    role: Exclude<UserRole, 'Owner'>;   // Owner cannot be invited
}

export interface InviteUserResponse {
    inviteLink: string;
}

// PUT /api/v1/Users/{userId}/role
export interface ChangeRoleRequest {
    newRole: UserRole;
}

3.2 KiB Raw Blame History