Archive, Delete, and Restore Flow

Archive, Delete, and Restore Flow.

This file explains how archiving, soft delete, and restore currently work in the project.

​

Table of Contents

1. Overview
2. The Two Different States
3. User Archive Flow
4. User Delete Flow
5. User Restore Flow
6. Self Delete Flow
7. Role of the Archivable Trait
8. Important Testing Notes

---

​

1. Overview

This project uses two separate mechanisms:

1. custom archive state through archived_at
2. Laravel soft delete through deleted_at

These are not the same thing.

---

​

2. The Two Different States

​

Archive State

• controlled by the custom Archivable trait
• stored in archived_at
• archived records are hidden by the trait’s global scope
• archived records can be brought back with unarchive()

​

Soft Delete State

• controlled by Laravel SoftDeletes
• stored in deleted_at
• soft-deleted records are not physically removed from the database
• soft-deleted records can be restored with Laravel restore()

---

​

3. User Archive Flow

Endpoint:

POST /api/user/{id}/archive

Controller:

App\Http\Controllers\UsersController::archive()

​

Success Response

{
  "message": "User archived successfully."
}

What happens internally:

• the controller finds the user
• it calls $user->archive()
• the Archivable trait sets archived_at = now()

To fetch archived users, the project supports:

GET /api/users?company_id=1&only_archived=true

---

​

4. User Delete Flow

Endpoint:

DELETE /api/user/{id}/delete

Controller:

App\Http\Controllers\UsersController::delete()

​

Success Response

{
  "message": "User force deleted successfully."
}

Important note:

• despite the response message, the controller calls:

$user->delete();

That means:

• this is a Laravel soft delete
• the row is not hard-deleted from the database
• it can still be restored later

Also note:

• this endpoint only works on users fetched from User::onlyArchived()
• so the intended flow is usually:

1. archive the user first
2. then call delete

---

​

5. User Restore Flow

There are two different restore behaviors in the project.

​

Unarchive Archived User

Endpoint:

POST /api/user/{id}/unarchive

Controller:

App\Http\Controllers\UsersController::unarchive()

​

Success Response

{
  "message": "User restored successfully.",
  "user": {
    "id": 7,
    "archived_at": null
  }
}

This only clears:

• archived_at

It does not restore a Laravel soft-deleted row.

​

Restore Soft-Deleted User

Endpoint:

POST /api/users/{userId}/restore

Controller:

App\Http\Controllers\AuthController::restore_account()

​

Success Response

{
  "message": "User has been restored successfully.",
  "user_id": 7
}

This restores:

• deleted_at

It does not automatically explain or manage archive state in the response.

---

​

6. Self Delete Flow

Endpoint:

POST /api/delete_my_account

Controller:

App\Http\Controllers\AuthController::delete_my_account()

​

Request JSON

{
  "password": "secret123",
  "reason": "No longer using the platform."
}

​

Success Response

{
  "message": "Your account has been deleted (soft). You can no longer sign in."
}

What happens internally:

• password is verified
• all current personal access tokens are deleted
• the user row is soft-deleted with Laravel delete()

Important restriction:

• admins
• super-admins
• instructors

cannot self-delete through this endpoint

---

​

7. Role of the Archivable Trait

The custom trait lives in:

app/Traits/Archivable.php

Main behavior:

• adds a global scope that hides archived rows where archived_at is not null
• provides archive()
• provides unarchive()
• provides scopeOnlyArchived()
• provides scopeWithArchived()

Practical impact:

• normal queries may hide archived rows automatically
• onlyArchived() is required when you want archived rows back

---

​

8. Important Testing Notes

• archive and delete are different operations.
• unarchive and restore are different operations.
• the message User force deleted successfully. is misleading because the controller performs a soft delete.
• if you want to test the full admin lifecycle in Postman, a safe order is:

1. POST /api/user/{id}/archive
2. POST /api/user/{id}/unarchive
3. POST /api/user/{id}/archive
4. DELETE /api/user/{id}/delete
5. POST /api/users/{userId}/restore