Smart Collection Logic

In this project, collections provide a way to organize bookmarks beyond simple tagging. The implementation distinguishes between static, user-managed groups and dynamic, rule-based groups through the Collection model and the CollectionType enumeration.

Manual vs. Smart Collections

The nature of a collection is defined by the CollectionType enum found in app/models/collection.py:

class CollectionType(Enum):
    """The kind of collection."""

    MANUAL = "manual"
    SMART = "smart"

Manual Collections

Manual collections are the default type. They function as an ordered list of bookmark IDs that a user explicitly manages. When a user adds a bookmark to a manual collection via the BookmarkService.add_to_collection method, the system appends the ID to the bookmark_ids list.

Smart Collections

Smart collections are intended to auto-populate based on a filter_rule. Instead of manual management, these collections store a query string that defines which bookmarks should be included. This is reflected in the Collection class attributes:

class Collection:
    name: str
    collection_type: CollectionType = CollectionType.MANUAL
    bookmark_ids: List[str] = field(default_factory=list)
    filter_rule: str = ""
    # ...

Filter Logic and Constraints

The core logic for smart collections resides in the _apply_filter method. This method performs a case-insensitive keyword search against the title and description of a list of bookmarks:

def _apply_filter(self, bookmarks: list) -> List[str]:
    """Evaluate the filter_rule against a list of bookmarks.

    Internal method used by the service layer to populate smart collections.
    """
    if not self.filter_rule:
        return []
    keyword = self.filter_rule.lower()
    return [b.id for b in bookmarks if keyword in b.title.lower() or keyword in b.description.lower()]

Enforcement of Collection Type

The codebase enforces a strict separation of concerns between these two types. Specifically, smart collections are "read-only" regarding manual additions. The add_bookmark method explicitly prevents adding IDs if the collection is smart:

def add_bookmark(self, bookmark_id: str) -> bool:
    """Add a bookmark to a manual collection.

    Returns:
        True if added, False if already present or collection is smart.
    """
    if self.is_smart or bookmark_id in self.bookmark_ids:
        return False
    self.bookmark_ids.append(bookmark_id)
    return True

This design ensures that the integrity of a smart collection's membership is maintained by its rule, rather than arbitrary user input.

Service Layer Integration

The BookmarkService in app/services/bookmark_service.py acts as the gatekeeper for these operations. When add_to_collection is called, it relies on the model's internal validation:

def add_to_collection(self, collection_id: str, bookmark_id: str) -> bool:
    """Add a bookmark to a collection."""
    collection = self._repo.get_collection(collection_id)
    if not collection:
        return False
    if not collection.add_bookmark(bookmark_id):
        return False
    self._repo.save_collection(collection)
    return True

If a developer attempts to manually add a bookmark to a collection where collection_type == CollectionType.SMART, the add_bookmark call returns False, and the service layer subsequently fails the operation.

Design Tradeoffs and Current State

The current implementation of smart collections follows a "pull" model where the logic for filtering exists (_apply_filter), but it is not yet automatically triggered by the BookmarkRepository or BookmarkService during standard retrieval.

1. Static Membership: Currently, bookmark_ids are stored as a static list in the repository. For smart collections, this means the filter_rule acts more as a metadata field or a template for future population rather than a live-updating view.
2. Internal Filtering: The _apply_filter method is marked as internal (prefixed with _). This suggests that the design intent is for the service layer to periodically "refresh" smart collections by running the filter against the entire bookmark set, rather than calculating the membership on every read request.
3. Reordering Restrictions: The reorder method requires the exact same set of IDs. This is useful for manual collections where a user wants to customize the display order, but it is functionally incompatible with the dynamic nature of smart collections if they were to be updated automatically.

This structure provides a foundation for powerful automated organization while maintaining a simple, predictable API for manual grouping.