Specification — User Management in Poolia

1. Objective

Provide REST-based user management for Poolia, covering user creation, retrieval, update, self-identification, password change, and logical deletion.

The user domain is the foundation for all other business areas because roles such as owner, technician, and admin determine access to pools, visits, invitations, and messaging.

2. Functional Approach

User management is modeled around a single User document stored in MongoDB through Beanie.

The system currently supports:

• listing users;
• creating users;
• retrieving a user by id;
• retrieving the authenticated user;
• updating user data;
• changing the authenticated user password;
• soft deleting a user.

The design distinguishes between two flows:

• administrative or system-level user CRUD
• self-service actions for the authenticated user

3. Data Design

3.1. User

The users collection stores identity, role, and lifecycle data.

Main fields

• name
• lastName
• email
• passwordHash
• role
• status
• createdAt
• lastLoginAt
• deletedAt

Roles

Allowed roles are:

• admin
• owner
• technician

Status values

Allowed status values are:

• active
• blocked
• pending
• deleted

Indexing

The model defines a unique email index to guarantee one account per email address.

4. Business Rules

Create user

User creation fails when another user already exists with the same email.

Update user

Update is partial and only modifies explicitly provided fields.

Change password

Changing the current user password requires:

• a current password;
• a new password;
• the current password must match the stored hash;
• the new password must be different from the current password.

Soft delete

User deletion is implemented as a logical deletion:

• status becomes deleted
• deletedAt is set

The current implementation does not physically remove the document.

5. REST Endpoints

5.1. List users

GET /users

Behavior

Returns all users from the collection.

Response

Array of User documents.

5.2. Create user

POST /users

Request body

{
  "name": "Grace",
  "lastName": "Hopper",
  "email": "grace@example.com",
  "passwordHash": "hashed-password",
  "role": "technician",
  "status": "pending"
}

Behavior

• validates unique email;
• creates a new User document.

Note

This endpoint expects passwordHash, not a plain password, because it uses the generic user schema rather than the auth registration flow.

5.3. Get current user

GET /users/me

Behavior

Returns the user resolved from the bearer token.

Access

Protected route.

5.4. Change current user password

POST /users/me/change-password

Request body

{
  "currentPassword": "old-secret",
  "newPassword": "new-secret"
}

Behavior

• validates the existing password;
• rejects equal old/new values;
• rehashes the new password;
• saves the updated user.

Access

Protected route.

5.5. Get user by id

GET /users/{user_id}

Behavior

Returns a single user or 404 if not found.

5.6. Update user

PATCH /users/{user_id}

Behavior

• loads the user;
• applies partial updates;
• persists the document.

5.7. Soft delete user

DELETE /users/{user_id}

Behavior

• loads the user;
• marks the user as deleted;
• returns a simple confirmation payload.

Response shape

{
  "ok": true,
  "id": "user-id",
  "status": "deleted"
}

6. Backend Logic Summary

Read operations

• list_users returns all documents.
• get_user validates existence before returning.

Write operations

• create_user validates unique email.
• update_user applies partial field mutation.
• soft_delete_user marks the user as deleted instead of removing it.

Self-service operations

• get_me returns the authenticated user.
• change_my_password verifies the current password and writes a new hash.

7. Frontend Integration Notes

Administrative flows

Admin panels or back-office screens can use:

• GET /users
• POST /users
• PATCH /users/{id}
• DELETE /users/{id}

Authenticated self flows

User profile flows can use:

• GET /users/me
• POST /users/me/change-password

Important distinction

For account onboarding through a normal sign-up experience, frontend should prefer /auth/register instead of /users, because /users expects already prepared password-hash data.

8. UX Considerations

Password change

Frontend should clearly separate:

• current password
• new password
• confirmation of the new password on the client side

Soft deletion

Because deletion is logical, management screens may eventually need filters or labels for deleted users instead of assuming hard removal.

9. Current Scope

The current implementation covers:

• role-based user modeling;
• CRUD-style user management;
• password change for the authenticated user;
• soft deletion.

It does not currently cover:

• avatar management inside the user resource itself;
• password reset by email;
• account activation workflow;
• user search and pagination;
• role-based admin authorization at the route layer.

10. Future Recommendations

A future version could add:

• pagination and filtering for /users;
• explicit admin-only protection for sensitive user management endpoints;
• user profile editing through /users/me;
• restore flow for soft-deleted users;
• password reset and account recovery.

11. Final Summary

User management in Poolia is centered on a single User document and supports both generic CRUD operations and authenticated self-service actions. The implementation is consistent with the current REST architecture and provides the identity and role foundation required by the rest of the system.