Skip to main content

Bookmark Lifecycle States

The state diagram illustrates the lifecycle of a Bookmark entity within the Etchblok API.

Key States:​

  • Active: The initial state of a bookmark upon creation. It is visible in the main list and searchable.
  • Archived: A state for bookmarks that are no longer active but preserved for reference. They can be filtered out of the main view.
  • Trashed: A soft-deleted state. Bookmarks in this state are typically hidden from the user but can be restored or permanently archived.

Transitions and Triggers:​

  • Creation: A bookmark starts in the Active state when created via the create_bookmark service method (triggered by POST /api/bookmarks/).
  • Archival: Moving a bookmark to the Archived state is triggered by the archive_bookmark method (POST /api/bookmarks/<id>/archive). This can be done from either the Active or Trashed states.
  • Soft Deletion: Moving a bookmark to the Trashed state is triggered by the delete_bookmark method (DELETE /api/bookmarks/<id>). This can be done from either the Active or Archived states.
  • Restoration: A bookmark in the Archived or Trashed state can be returned to the Active state using the restore_bookmark method (POST /api/bookmarks/<id>/restore).

The diagram reflects the actual implementation in app/models/bookmark.py and app/services/bookmark_service.py, where status changes are handled by explicit methods that update the BookmarkStatus enum. Notably, while the repository layer supports hard deletion, the service layer currently only implements soft deletion via the Trashed state.

Key Architectural Findings:

  • The Bookmark entity uses a BookmarkStatus enum with three values: ACTIVE, ARCHIVED, and TRASHED.
  • New bookmarks are initialized with the ACTIVE status by default in the Bookmark dataclass.
  • The delete_bookmark service method performs a soft delete by transitioning the bookmark to the TRASHED state.
  • The restore_bookmark service method transitions a bookmark from either ARCHIVED or TRASHED back to the ACTIVE state.
  • Transitions between ARCHIVED and TRASHED are possible through their respective service methods without intermediate steps.
  • The repository layer contains a hard-delete method (delete_bookmark) that is currently unused by the service layer.