Entities¶

This section defines the data model entities for Papyrus. These entities form the foundation for the database schema and represent the core data structures managed by the application.

Entity overview¶

Entity relationship diagram¶

erDiagram
    USER ||--o{ BOOK : owns
    USER ||--o{ SHELF : creates
    USER ||--o{ TAG : creates
    USER ||--o{ SERIES : creates
    USER ||--o{ ANNOTATION : makes
    USER ||--o{ NOTE : writes
    USER ||--o{ BOOKMARK : creates
    USER ||--o{ READING_SESSION : has
    USER ||--o{ READING_GOAL : sets
    USER ||--o{ READING_PROFILE : configures
    USER ||--o| METADATA_SERVER_CONFIG : connects_to
    USER ||--o{ FILE_STORAGE_BACKEND : configures
    USER ||--o{ SAVED_FILTER : saves

    BOOK }o--o| FILE_STORAGE_BACKEND : stored_in

    BOOK ||--o{ ANNOTATION : contains
    BOOK ||--o{ NOTE : has
    BOOK ||--o{ BOOKMARK : has
    BOOK ||--o{ READING_SESSION : tracked_in
    BOOK }o--o| SERIES : belongs_to

    BOOK }o--o{ SHELF : organized_in
    BOOK }o--o{ TAG : tagged_with

    SHELF }o--o| SHELF : parent_of

    USER {
        uuid user_id PK
        string email UK
        string display_name
        boolean is_anonymous
    }

    BOOK {
        uuid book_id PK
        uuid user_id FK
        string title
        string author
        boolean is_physical
        string reading_status
    }

    SHELF {
        uuid shelf_id PK
        uuid user_id FK
        uuid parent_shelf_id FK
        string name
    }

    TAG {
        uuid tag_id PK
        uuid user_id FK
        string name
        string color
    }

    SERIES {
        uuid series_id PK
        uuid user_id FK
        string name
    }

    ANNOTATION {
        uuid annotation_id PK
        uuid book_id FK
        string selected_text
        string highlight_color
    }

    NOTE {
        uuid note_id PK
        uuid book_id FK
        string title
        text content
    }

    BOOKMARK {
        uuid bookmark_id PK
        uuid book_id FK
        string position
        string note
    }

    READING_SESSION {
        uuid session_id PK
        uuid book_id FK
        timestamp start_time
        integer duration_minutes
    }

    READING_GOAL {
        uuid goal_id PK
        uuid user_id FK
        string goal_type
        integer target_value
    }

    READING_PROFILE {
        uuid profile_id PK
        uuid user_id FK
        string name
        json settings
    }

    STORAGE_CONFIG {
        uuid config_id PK
        uuid user_id FK
        string storage_type
        boolean is_primary
    }

    SAVED_FILTER {
        uuid filter_id PK
        uuid user_id FK
        string name
        string query
    }

Core entities¶

User¶

Represents a person who uses the system.

Attributes:

Relationships:

• One-to-many with Book, Shelf, Tag, Series
• One-to-many with Annotation, Note, Bookmark
• One-to-many with ReadingSession, ReadingGoal
• One-to-many with ReadingProfile, FileStorageBackend, SavedFilter
• One-to-one with MetadataServerConfig (optional)

Book¶

Represents a physical or digital book in the user's library.

Attributes:

Relationships:

• Many-to-one with User (owner)
• Many-to-one with Series (optional)
• Many-to-one with FileStorageBackend (optional, for digital books)
• Many-to-many with Shelf
• Many-to-many with Tag
• One-to-many with Annotation, Note, Bookmark, ReadingSession

Indexes:

• user_id (for library queries)
• title, author (for search)
• reading_status (for filtering)
• series_id (for series grouping)
• storage_backend_id (for storage queries)

Shelf¶

Represents a user-created collection for organizing books.

Attributes:

Relationships:

• Many-to-one with User (owner)
• Many-to-one with Shelf (parent, for nesting)
• One-to-many with Shelf (children)
• Many-to-many with Book

Default shelves:

• "Currently Reading" (is_default: true)
• "Want to Read" (is_default: true)
• "Finished" (is_default: true)

Tag¶

Represents a color-coded label for categorizing books.

Attributes:

Relationships:

• Many-to-one with User (owner)
• Many-to-many with Book

Constraints:

• Maximum 10 tags per book
• Tag name unique per user

Series¶

Represents a book series (e.g., "Harry Potter", "Lord of the Rings").

Attributes:

Relationships:

• Many-to-one with User (owner)
• One-to-many with Book

Annotation¶

Represents a text highlight with optional note in a digital book.

Attributes:

Relationships:

• Many-to-one with Book
• Many-to-one with User

Highlight colors (defaults):

• Yellow (#FFEB3B)
• Green (#4CAF50)
• Blue (#2196F3)
• Pink (#E91E63)
• Orange (#FF9800)

Note¶

Represents a free-form note associated with a book.

Attributes:

Relationships:

• Many-to-one with Book
• Many-to-one with User

Bookmark¶

Represents a saved position within a book for quick navigation.

Attributes:

Relationships:

• Many-to-one with Book
• Many-to-one with User

ReadingSession¶

Represents a period of reading activity.

Attributes:

Relationships:

• Many-to-one with Book
• Many-to-one with User

ReadingGoal¶

Represents a user-defined reading objective.

Attributes:

Relationships:

• Many-to-one with User

ReadingProfile¶

Represents saved reader customization settings.

Attributes:

Relationships:

• Many-to-one with User

Suggested profiles:

• "Day" - Light background, dark text
• "Night" - Dark background, light text
• "Sepia" - Warm tones for reduced eye strain
• "E-ink" - High contrast, no animations

MetadataServerConfig¶

Represents the user's connection to a metadata server for cross-device synchronization. Each user has at most one active metadata server connection.

Attributes:

Relationships:

• One-to-one with User

Notes:

• If null, user is in local-only mode (no sync)
• Server URL validated on save
• See Server Architecture for details

FileStorageBackend¶

Represents a configured file storage backend where book files are stored. Users can have multiple backends.

Attributes:

Relationships:

• Many-to-one with User
• One-to-many with Book (books reference storage backend)

Connection configuration examples:

// Google Drive
{
  "folder_id": "abc123",
  "folder_path": "/Papyrus/Books"
}

// WebDAV
{
  "server_url": "https://nextcloud.example.com/remote.php/dav/files/user/",
  "folder_path": "/Papyrus/Books"
}

// MinIO/S3
{
  "endpoint": "https://minio.example.com",
  "bucket": "papyrus-books",
  "region": "us-east-1"
}

// Papyrus Server
{
  "server_url": "https://papyrus.example.com"
}

Notes:

• Only one backend can be primary at a time
• Local backend always exists (implicit)
• See Server Architecture for details

SavedFilter¶

Represents a saved search or filter query for reuse.

Attributes:

Relationships:

• Many-to-one with User

Query language examples:

• author:"Isaac Asimov" AND year:>1970
• tag:science-fiction OR tag:fantasy
• status:in_progress AND rating:>=4
• shelf:"Currently Reading" AND format:epub

Junction tables¶

BookShelf¶

Many-to-many relationship between Book and Shelf.

BookTag¶

Many-to-many relationship between Book and Tag.

Entity relationships summary¶

By functional area¶

User management

• User owns all other entities through user_id foreign key
• User can be anonymous (no email) or registered

Book organization

• Books belong to Shelves (many-to-many)
• Books have Tags (many-to-many, max 10)
• Books can belong to a Series (many-to-one)
• Shelves can be nested (self-referential)

Reading experience

• Books have Annotations (one-to-many)
• Books have Notes (one-to-many)
• Books have Bookmarks (one-to-many)
• Users have ReadingProfiles (one-to-many)

Progress and goals

• Books have ReadingSessions (one-to-many)
• Users have ReadingGoals (one-to-many)

Configuration

• Users have MetadataServerConfig (one-to-one, optional)
• Users have FileStorageBackends (one-to-many)
• Users have SavedFilters (one-to-many)
• Books reference FileStorageBackend (many-to-one)

Data integrity rules¶

1. Cascade delete: When User is deleted, all owned entities are deleted
2. Nullify: When Series is deleted, Book.series_id is set to null
3. Restrict: Cannot delete Shelf/Tag while books are associated
4. Unique constraints:
5. User email must be unique
6. Tag name unique per user
7. Shelf name unique within parent