Introduction to BookmarkService

The BookmarkService class, located in app/services/bookmark_service.py, serves as the central facade and primary entry point for the application's business logic. It orchestrates complex operations that involve data persistence, full-text search indexing, and caching, ensuring that these disparate systems remain synchronized.

Singleton Architecture

The BookmarkService is implemented as a singleton. This design ensures that a single instance manages the application state—specifically the internal cache—across different Flask blueprints.

class BookmarkService:
    _instance: Optional["BookmarkService"] = None

    def __new__(cls) -> "BookmarkService":
        """Singleton — share state across blueprint modules."""
        if cls._instance is None:
            cls._instance = super().__new__(cls)
            cls._instance._init_services()
        return cls._instance

When the service is initialized via _init_services, it bootstraps its three primary dependencies:

• BookmarkRepository: Handles direct database interactions.
• LRUCache: A local cache (max size 256) used to speed up bookmark retrieval.
• SearchIndex: Manages full-text search capabilities, initialized with a reference to the repository.

Orchestration and Data Consistency

The core responsibility of BookmarkService is to coordinate actions across the repository, search index, and cache. This is most evident in the create_bookmark and update_bookmark methods.

The Write Path

When a bookmark is created or updated, the service follows a strict sequence to maintain consistency:

1. Validation: Uses internal validators like _validate_url and _validate_title from app.models._validators.
2. Persistence: Saves the entity to the BookmarkRepository.
3. Indexing: Updates the SearchIndex so the new data is immediately searchable.
4. Invalidation: Clears the specific entry from the LRUCache to prevent stale data reads.

def create_bookmark(self, data: Dict[str, Any]) -> Tuple[Optional[Bookmark], Optional[str]]:
    error = _validate_url(data.get("url", "")) or _validate_title(data.get("title", ""))
    if error:
        return None, error

    bookmark = Bookmark.from_dict(data)
    self._repo.save_bookmark(bookmark)
    self._search.index_bookmark(bookmark)
    self._cache.invalidate(bookmark.id)
    return bookmark, None

The Read Path (Cache-Aside)

For single bookmark retrieval, the service implements a cache-aside pattern in get_bookmark. It first attempts to resolve the request from the LRUCache before falling back to the repository and subsequently populating the cache.

def get_bookmark(self, bookmark_id: str) -> Optional[Bookmark]:
    """Retrieve a bookmark by ID, using cache when available."""
    cached = self._cache.get(bookmark_id)
    if cached is not None:
        return cached
    bookmark = self._repo.get_bookmark(bookmark_id)
    if bookmark:
        self._cache.put(bookmark.id, bookmark)
    return bookmark

Cross-Entity Operations

The service handles operations that span multiple entity types, such as the relationship between tags and bookmarks. A notable example is delete_tag, which performs a cascading cleanup. When a tag is deleted, the service:

1. Identifies all bookmarks associated with that tag via self._repo.get_bookmarks_with_tag(tag_id).
2. Removes the tag reference from each bookmark.
3. Saves the updated bookmarks and invalidates their respective cache entries.
4. Finally, deletes the tag itself from the repository.

Integration with API Routes

Flask blueprints in this project do not interact with the database or search index directly. Instead, they instantiate the BookmarkService singleton and delegate all logic to it. This separation of concerns is visible in app/routes/bookmarks.py and app/routes/tags.py.

# app/routes/bookmarks.py
from app.services.bookmark_service import BookmarkService

bookmarks_bp = Blueprint("bookmarks", __name__)
_service = BookmarkService()

@bookmarks_bp.route("/", methods=["POST"])
def create_bookmark():
    data = request.get_json(force=True)
    bookmark, error = _service.create_bookmark(data)
    if error:
        return jsonify({"error": error}), 400
    return jsonify(bookmark.to_dict()), 201

By centralizing logic in the BookmarkService, the application ensures that side effects—like updating the search index or clearing the cache—are never missed by the API layer.