Skip to main content

Bookmark Domain Entity Relationship Diagram

The data model for the Etchblok API is centered around three core domain entities: Bookmark Fundamentals, Tagging and Categorization, and Managing Collections. These entities are implemented as Python dataclasses and managed by an in-memory repository.

Core Entities​

  • Bookmark: Represents a saved URL. It includes metadata like title and description, and tracks its lifecycle via a BookmarkStatus (Active, Archived, or Trashed). It also supports arbitrary key-value pairs in a metadata field for extensibility.
  • Tag: A label that can be applied to bookmarks for organization. Each tag has a name and a TagColor. The system tracks usage_count to monitor how many bookmarks are associated with each tag.
  • Collection: A grouping mechanism for bookmarks. Collections can be Manual (where users explicitly add bookmarks) or Smart (where bookmarks are automatically included based on a filter_rule that matches text in the title or description).

Relationships​

  • Many-to-Many (Bookmark <-> Tag): A bookmark can have multiple tags, and a single tag can be applied to many bookmarks. This is managed via a list of tag IDs within the Bookmark entity.
  • Many-to-Many (Collection <-> Bookmark): A collection contains multiple bookmarks, and a bookmark can belong to multiple collections. For manual collections, this is stored as a list of bookmark IDs. Smart collections resolve this relationship dynamically at runtime using their filter rules.

The architecture uses a clean separation between the domain models (dataclasses) and the persistence logic (repository), allowing for easy transition from the current in-memory storage to a persistent database in the future.

Key Architectural Findings:

  • Entities are implemented as Python dataclasses with UUID-based identifiers.
  • Relationships are managed through lists of IDs (e.g., Bookmark.tags, Collection.bookmark_ids), representing many-to-many associations.
  • The Bookmark entity includes a status enum (ACTIVE, ARCHIVED, TRASHED) to manage its lifecycle.
  • Collections support two modes: Manual (static list of IDs) and Smart (dynamic filtering based on rules).
  • Tags include a usage counter that is incremented/decremented as bookmarks are tagged or untagged.
Loading diagram...