Beacon/docs/domain-model.md

Domain model

User is an authenticated account. A Workspace is a community and WorkspaceMember assigns its ADMIN or MEMBER role. A user may be in multiple workspaces.

MediaItem is one external or manual work. Manual works use MANUAL plus an application-generated external identifier. A Recommendation is the one active personal recommendation for a media item in a workspace; its uniqueness is (workspaceId, mediaItemId). RecommendationStatus is per user and recommendation, while reactions and comments reinforce the existing recommendation instead of duplicating it.

Provider/external ID identifies media globally. A work can appear in different workspaces. Soft deletion is available for recommendations and comments. Invitation tokens are stored hashed. Audit metadata is deliberately non-sensitive.

Status values are PENDING, INTERESTED, IN_PROGRESS, COMPLETED, DROPPED and NOT_INTERESTED. Strength values NORMAL, HIGH and MUST_EXPERIENCE express insistence, not quality. Ratings are optional and intended for completed works.