Use cases

This section presents the main use cases derived from the functional requirements. Each use case includes actors, requirements traceability, detailed flows, and alternative scenarios.

Use case notation

Element

Description

UC-X.Y

Use case identifier (section X, item Y)

Actors

User types involved

Priority

P0-P3 (matches requirement priority)

Requirements

Links to FR and NFR

Preconditions

State required before use case

Main flow

Primary success scenario

Alternative flows

Variations and edge cases

Postconditions

State after successful completion

1. User management use cases

Use Case: Create user account UC-1_1
status: open
priority: P0
actors: Anonymous User → Registered User
links outgoing: FR-1_1
links incoming: FR-1_1

User creates a new account to access synchronization and cloud features.

Preconditions:

  • User is not logged in

  • User has valid email address

Main flow:

  1. User navigates to registration screen

  2. User enters email address and password

  3. System validates email format and uniqueness

  4. System validates password strength (8+ chars, mixed case, number)

  5. System creates account in inactive state

  6. System sends verification email

  7. User clicks verification link

  8. System activates account

  9. User is redirected to login screen

Alternative flows:

A1: Email already registered

  • At step 3, if email exists:

    • System displays “Email already registered” error

    • User can choose to log in or recover password

A2: Weak password

  • At step 4, if password is too weak:

    • System displays password requirements

    • User must enter a stronger password

A3: Verification link expired

  • At step 7, if link expired (24 hours):

    • System displays expiration message

    • User can request new verification email

Postconditions:

  • New user account exists

  • User can log in with credentials
Use Case: Login with credentials UC-1_2
status: open
priority: P0
actors: Registered User
links outgoing: FR-1_2
links incoming: FR-1_2

User authenticates using email and password.

Preconditions:

  • User has registered account

  • Account is verified and active

Main flow:

  1. User navigates to login screen

  2. User enters email and password

  3. System validates credentials

  4. System creates session token

  5. User is redirected to library

Alternative flows:

A1: Invalid credentials

  • At step 3, if credentials invalid:

    • System displays “Invalid email or password”

    • Failed attempt is logged

    • After 5 failures, temporary lockout (15 minutes)

A2: Account not verified

  • At step 3, if account not verified:

    • System prompts to resend verification email

A3: Account disabled

  • At step 3, if account disabled:

    • System displays account disabled message

    • User is directed to support contact

Postconditions:

  • User is authenticated

  • Session token is stored on device

  • User has access to their library
Use Case: Login with Google account UC-1_3
status: open
priority: P1
actors: Registered User
links outgoing: FR-1_3
links incoming: FR-1_3

User authenticates via Google OAuth 2.0.

Preconditions:

  • User has Google account

  • Device has internet connection

Main flow:

  1. User selects “Sign in with Google”

  2. System redirects to Google OAuth

  3. User authorizes application

  4. Google returns authorization code

  5. System exchanges code for user info

  6. If new user, system creates account

  7. System creates session token

  8. User is redirected to library

Alternative flows:

A1: User denies authorization

  • At step 3, if user denies:

    • System returns to login screen

    • Message: “Google sign-in cancelled”

A2: Link to existing account

  • At step 6, if email matches existing account:

    • System prompts to link accounts

    • User confirms linking

Postconditions:

  • User is authenticated

  • Google account linked to Papyrus account
Use Case: Use application offline UC-1_4
status: open
priority: P0
actors: Anonymous User, Registered User
links outgoing: FR-1_4, NFR-2_1
links incoming: FR-1_4

User accesses application without internet connection.

Preconditions:

  • Application is installed on device

  • For registered users: at least one previous online session

Main flow:

  1. User opens application without internet

  2. System detects offline state

  3. System loads local data

  4. User accesses library and books

  5. User can read, annotate, organize

  6. Changes are stored locally

  7. Offline indicator is displayed

Alternative flows:

A1: First launch (Anonymous)

  • User can immediately use all local features

  • No account required

A2: First launch (Registered, never synced)

  • System shows “Connect to sync your data”

  • User can continue with empty library

A3: Sync when online

  • When internet restored:

    • System begins background sync

    • Pending changes indicator updates

Postconditions:

  • User can use reading and management features

  • Changes are queued for sync
Use Case: Recover password UC-1_5
status: open
priority: P1
actors: Registered User
links outgoing: FR-1_5
links incoming: FR-1_5

User resets forgotten password via email.

Preconditions:

  • User has registered account

  • User has access to registered email

Main flow:

  1. User clicks “Forgot password”

  2. User enters registered email

  3. System sends recovery email with link

  4. User clicks link (valid 24 hours)

  5. User enters new password

  6. System validates password strength

  7. System updates password

  8. All existing sessions are invalidated

  9. User is redirected to login

Alternative flows:

A1: Email not found

  • At step 3, system still shows success message (security)

  • No email sent if account doesn’t exist

A2: Link expired

  • At step 4, if link expired:

    • System displays expiration message

    • User can request new link

Postconditions:

  • Password is updated

  • User must log in with new password
Use Case: Delete account UC-1_6
status: open
priority: P1
actors: Registered User
links outgoing: FR-1_6
links incoming: FR-1_6

User permanently deletes their account and all data.

Preconditions:

  • User is logged in

  • User understands consequences

Main flow:

  1. User navigates to account settings

  2. User selects “Delete account”

  3. System displays warning about data loss

  4. User confirms by entering password

  5. System marks account for deletion

  6. System logs user out

  7. Account and data deleted within 30 days

Alternative flows:

A1: Export data first

A2: Cancel deletion

  • Within 7 days, user can log in to cancel

  • Account is restored to active state

Postconditions:

  • Account is deleted

  • User data removed from server

  • Local data remains on device

2. Book management use cases

Use Case: Import book files UC-2_1
status: open
priority: P0
actors: Reader
links outgoing: FR-2_6, FR-7_2
links incoming: FR-2_6, FR-7_2

User adds books to library from files.

Preconditions:

  • User has book files in supported format

Main flow:

  1. User selects “Add books”

  2. User chooses import source (device, cloud, URL)

  3. User selects files

  4. System uploads/imports files

  5. System extracts metadata from files

  6. System checks for duplicates

  7. Books are added to library

  8. User receives confirmation

Alternative flows:

A1: Unsupported format

  • System displays format error

  • Lists supported formats

A2: Duplicate detected

  • System shows existing book

  • User can: skip, replace, keep both

A3: Bulk import

  • User selects folder

  • System imports all supported files

  • Progress shown for large imports

A4: Import from URL

  • User enters URL

  • System downloads and imports

Postconditions:

  • Books are in user’s library

  • Metadata is populated
Use Case: Convert book formats UC-2_2
status: open
priority: P2
actors: Reader
links outgoing: FR-2_1
links incoming: FR-2_1

User converts book to different format.

Preconditions:

  • Book exists in library

  • Source format supports conversion

Main flow:

  1. User opens book details

  2. User selects “Convert format”

  3. User chooses target format

  4. User sets conversion options (optional)

  5. System processes conversion

  6. Converted file is added to library

  7. Original file is preserved

Alternative flows:

A1: Conversion fails

  • System shows error details

  • User can retry with different options

A2: Large file

  • Progress indicator shown

  • Conversion runs in background

  • Notification when complete

Postconditions:

  • New file in target format exists

  • Original file unchanged
Use Case: Edit book metadata UC-2_3
status: open
priority: P0
actors: Reader
links outgoing: FR-2_2, FR-2_13
links incoming: FR-2_2, FR-2_3, FR-2_13

User modifies book information.

Preconditions:

  • Book exists in library

Main flow:

  1. User opens book details

  2. User selects “Edit”

  3. User modifies metadata fields

  4. User saves changes

  5. System validates and stores changes

Alternative flows:

A1: Fetch metadata online

  • User clicks “Fetch metadata”

  • System searches online sources

  • User reviews and selects matches

  • Selected metadata is applied

A2: Edit cover image

  • User can upload new cover

  • User can crop/adjust cover

  • User can fetch cover online

Postconditions:

  • Book metadata is updated
Use Case: Organize books into shelves UC-2_4
status: open
priority: P0
actors: Reader
links outgoing: FR-2_9
links incoming: FR-2_9

User creates and manages book collections.

Preconditions:

  • User has books in library

Main flow:

  1. User navigates to Shelves

  2. User creates new shelf (name, description, color)

  3. User adds books to shelf

  4. Shelf is saved

Alternative flows:

A1: Add from library view

  • User long-presses book

  • User selects “Add to shelf”

  • User chooses shelf(s)

A2: Create nested shelf

  • User creates shelf within existing shelf

  • Hierarchy is maintained

A3: Drag and drop

  • User drags book to shelf

  • Book is added to shelf

Postconditions:

  • Books are organized in shelves
Use Case: Tag books UC-2_5
status: open
priority: P0
actors: Reader
links outgoing: FR-2_10
links incoming: FR-2_10

User assigns colored labels to books.

Preconditions:

  • User has books in library

Main flow:

  1. User opens book details or context menu

  2. User selects “Tags”

  3. User creates or selects tags

  4. Tags are applied to book

Alternative flows:

A1: Create new tag

  • User enters tag name

  • User selects color

  • Tag is created and applied

A2: Batch tagging

  • User selects multiple books

  • User applies tags to all

Postconditions:

  • Books have assigned tags

  • Tags visible in library view
Use Case: Search books UC-2_6
status: open
priority: P0
actors: Reader
links outgoing: FR-2_7, FR-2_8, FR-2_11
links incoming: FR-2_7, FR-2_8, FR-2_11

User finds books using search and filters.

Preconditions:

  • User has books in library

Main flow:

  1. User opens search

  2. User enters query

  3. System searches metadata

  4. Results are displayed

  5. User can filter/sort results

Alternative flows:

A1: Full-text search

  • User searches book contents

  • Results show matched text with context

A2: Advanced filters

  • User uses filter panel

  • Multiple criteria combined

A3: Query language

  • User types query like author:"Name" AND year:>2000

  • System parses and executes

A4: Save search

  • User saves search as filter

  • Filter available for reuse

Postconditions:

  • Matching books are displayed
Use Case: Export books and data UC-2_7
status: open
priority: P0
actors: Reader
links outgoing: FR-2_4, FR-2_5
links incoming: FR-2_4, FR-2_5

User exports library data for backup or migration.

Preconditions:

  • User has books in library

Main flow:

  1. User navigates to Export

  2. User selects what to export (books, metadata, annotations)

  3. User chooses format (ZIP, JSON, CSV)

  4. System creates export file

  5. User downloads export

Alternative flows:

A1: Selective export

  • User selects specific books

  • Only selected items exported

A2: Export to cloud

  • User chooses cloud destination

  • File uploaded directly

Postconditions:

  • Export file is created

  • User has backup of data
Use Case: Scan ISBN barcode UC-2_8
status: open
priority: P2
actors: Reader
links outgoing: FR-2_12
links incoming: FR-2_12

User adds physical book by scanning barcode.

Preconditions:

  • Device has camera

  • Physical book has ISBN barcode

Main flow:

  1. User selects “Scan ISBN”

  2. Camera opens

  3. User scans barcode

  4. System decodes ISBN

  5. System fetches metadata

  6. User reviews and confirms

  7. Book is added as physical

Alternative flows:

A1: Manual ISBN entry

  • If scan fails, user types ISBN

  • System fetches metadata

A2: No metadata found

  • System shows “Not found”

  • User can enter details manually

Postconditions:

  • Physical book added to library
Use Case: Track physical book UC-2_9
status: open
priority: P1
actors: Reader
links outgoing: FR-2_14
links incoming: FR-2_14

User manages physical books in library.

Main flow:

  1. User selects “Add physical book”

  2. User enters book details

  3. User sets reading status

  4. User can add location (e.g., “Shelf 3”)

  5. Book is added to library

Alternative flows:

A1: Mark as lent

  • User marks book as lent

  • User enters borrower info

  • Reminder can be set

Postconditions:

  • Physical book tracked in library

3. Reading and viewer use cases

Use Case: Read books with integrated viewer UC-3_1
status: open
priority: P0
actors: Reader, E-ink Reader
links outgoing: FR-3_1
links incoming: FR-3_1

User reads e-books in the viewer.

Preconditions:

  • Book exists in library

  • Book format is supported

Main flow:

  1. User opens book from library

  2. System loads book in viewer

  3. System restores last position

  4. User reads and navigates

  5. System saves progress automatically

Alternative flows:

A1: Navigate via TOC

  • User opens table of contents

  • User selects chapter

A2: Go to page/position

  • User enters page number or percentage

  • System jumps to position

A3: E-ink mode

  • System detects e-ink display

  • UI adapts (no animations, high contrast)

Postconditions:

  • Reading position is saved

  • Time tracked for statistics
Use Case: Customize reading experience UC-3_2
status: open
priority: P0
actors: Reader, E-ink Reader
links outgoing: FR-3_2
links incoming: FR-3_2

User personalizes viewer appearance.

Preconditions:

  • Book is open in viewer

Main flow:

  1. User opens reader settings

  2. User adjusts typography (font, size, spacing)

  3. User sets colors (background, text)

  4. User configures layout (margins, mode)

  5. Changes apply immediately

  6. Settings are saved

Alternative flows:

A1: Quick theme switch

  • User taps theme button

  • Cycles through presets

A2: E-ink optimized

  • User enables e-ink mode

  • High contrast, no animations

Postconditions:

  • Reader customized to preference
Use Case: Manage reading profiles UC-3_3
status: open
priority: P1
actors: Reader, E-ink Reader
links outgoing: FR-3_3
links incoming: FR-3_3

User saves and switches reader configurations.

Preconditions:

  • Reader settings have been customized

Main flow:

  1. User opens profile management

  2. User creates new profile

  3. User names profile (e.g., “Night reading”)

  4. Current settings saved to profile

  5. User can switch between profiles

Alternative flows:

A1: Set default profile

  • User marks profile as default

  • Applied to new books

A2: Export/import profiles

  • User exports profile to file

  • Can import on other devices

Postconditions:

  • Profiles saved for quick switching
Use Case: Manage bookmarks UC-3_4
status: open
priority: P0
actors: Reader
links outgoing: FR-3_4
links incoming: FR-3_4

User creates and uses bookmarks.

Preconditions:

  • Book is open in viewer

Main flow:

  1. User taps bookmark button

  2. Bookmark created at current position

  3. User can add note (optional)

  4. Bookmark saved

Alternative flows:

A1: View all bookmarks

  • User opens bookmark panel

  • Sees list with positions

  • Taps to navigate

A2: Delete bookmark

  • User swipes or long-press

  • Confirms deletion

Postconditions:

  • Bookmark saved and accessible

4. Annotations and notes use cases

Use Case: Create text annotations UC-4_1
status: open
priority: P0
actors: Reader
links outgoing: FR-4_1
links incoming: FR-4_1

User highlights text while reading.

Preconditions:

  • Book is open in viewer

Main flow:

  1. User selects text

  2. Context menu appears

  3. User chooses highlight color

  4. User adds note (optional)

  5. Annotation saved

Alternative flows:

A1: Quick highlight

  • User selects and taps color

  • Instant highlight without menu

Postconditions:

  • Text is highlighted

  • Annotation appears in panel
Use Case: Create book notes UC-4_2
status: open
priority: P0
actors: Reader
links outgoing: FR-4_2
links incoming: FR-4_2

User creates free-form notes for books.

Preconditions:

  • Book exists in library

Main flow:

  1. User opens book notes

  2. User creates new note

  3. User enters title and content

  4. Note saved

Alternative flows:

A1: Rich text editing

  • User uses formatting (bold, lists)

  • Markdown syntax supported

Postconditions:

  • Note attached to book
Use Case: Manage annotations UC-4_3
status: open
priority: P0
actors: Reader
links outgoing: FR-4_3
links incoming: FR-4_3

User edits or deletes annotations.

Preconditions:

  • Annotations exist for book

Main flow:

  1. User opens annotation panel

  2. User selects annotation

  3. User edits (color, note) or deletes

  4. Changes saved

Postconditions:

  • Annotations updated
Use Case: Export annotations UC-4_4
status: open
priority: P1
actors: Reader
links outgoing: FR-4_4
links incoming: FR-4_4

User exports annotations to file.

Preconditions:

  • Book has annotations

Main flow:

  1. User opens export options

  2. User selects format (Markdown, PDF, TXT)

  3. User configures options (include context, metadata)

  4. System generates export

  5. User downloads file

Postconditions:

  • Annotations exported to file
Use Case: Search annotations UC-4_5
status: open
priority: P1
actors: Reader
links outgoing: FR-4_5
links incoming: FR-4_5

User searches through annotations.

Preconditions:

  • User has annotations

Main flow:

  1. User opens annotation search

  2. User enters search query

  3. Results from all books shown

  4. User can filter by book, color, date

Postconditions:

  • Matching annotations displayed

5. Progress tracking use cases

Use Case: Track reading progress UC-5_1
status: open
priority: P0
actors: Reader
links outgoing: FR-5_1
links incoming: FR-5_1

System tracks and displays reading activity.

Preconditions:

  • User reads books in viewer

Main flow:

  1. System monitors reading sessions

  2. System records time and pages

  3. User views progress dashboard

  4. Statistics displayed (charts, metrics)

Postconditions:

  • Reading activity is tracked

  • Statistics available
Use Case: Filter progress statistics UC-5_2
status: open
priority: P1
actors: Reader
links outgoing: FR-5_2
links incoming: FR-5_2

User customizes statistics view.

Preconditions:

  • Reading data exists

Main flow:

  1. User opens statistics

  2. User selects time range

  3. User filters by books/shelves

  4. Filtered results displayed

Postconditions:

  • Statistics filtered to selection

6. Goal management use cases

Use Case: Create reading goals UC-6_1
status: open
priority: P1
actors: Reader
links outgoing: FR-6_1
links incoming: FR-6_1

User sets reading objectives.

Main flow:

  1. User opens Goals

  2. User creates new goal

  3. User selects type (books, pages, time)

  4. User sets target and period

  5. Goal is saved and tracking begins

Postconditions:

  • Goal is active

  • Progress tracked automatically
Use Case: Manage goal progress UC-6_2
status: open
priority: P1
actors: Reader
links outgoing: FR-6_2, FR-6_3
links incoming: FR-6_2, FR-6_3, FR-6_4

User and system update goal progress.

Preconditions:

  • Active goal exists

Main flow:

  1. System updates progress automatically

  2. User can manually adjust if needed

  3. Progress displayed with visualizations

  4. Notifications sent at milestones

Postconditions:

  • Goal progress is current

7. Storage and synchronization use cases

Use Case: Configure storage options UC-7_1
status: open
priority: P0
actors: Registered User, System Administrator
links outgoing: FR-7_1, FR-7_1_1
links incoming: FR-7_1, FR-7_1_1

User configures metadata server connection and file storage backend(s) for synchronization and book storage.

Preconditions:

  • Application is installed

  • Internet connection available (for server configuration)

Main flow (Metadata server):

  1. User opens Settings > Sync & Storage

  2. User selects metadata server option:

    • Official hosted server (default)

    • Self-hosted server (enter URL)

  3. User logs in or registers on metadata server

  4. System validates connection

  5. Sync capabilities are enabled

Main flow (File Storage Backend):

  1. User opens Settings > Storage > File Storage

  2. User clicks “Add Storage Backend”

  3. User selects backend type (Google Drive, WebDAV, MinIO, etc.)

  4. User configures credentials:

    • OAuth flow for Google/OneDrive/Dropbox

    • URL + credentials for WebDAV/MinIO

  5. System validates connection and shows storage info

  6. User sets backend as primary (optional)

  7. Backend is available for file storage

Alternative flows:

A1: Cloud storage OAuth (Google Drive, OneDrive, Dropbox)

  1. User clicks “Connect with [Provider]”

  2. OAuth popup opens

  3. User authorizes Papyrus access

  4. System stores tokens securely

  5. Storage folder is created automatically

A2: Self-hosted metadata server

  1. User enters server URL (e.g., https://papyrus.home.local)

  2. System tests connection and retrieves server info

  3. User registers or logs in on self-hosted server

  4. Connection is established

A3: WebDAV server (Nextcloud, etc.)

  1. User enters WebDAV URL

  2. User enters username and password

  3. System tests connection

  4. User specifies folder path

A4: MinIO/S3-compatible storage

  1. User enters endpoint URL

  2. User enters bucket name

  3. User enters access key and secret key

  4. System tests connection

A5: Local-only mode (no sync)

  1. User skips metadata server setup

  2. User uses only local storage

  3. All data stored on device only

  4. No cross-device sync available

A6: Dedicated Papyrus server for files

  1. User selects “Papyrus Server” as file storage

  2. Files stored on same server as metadata

  3. Single server handles everything

Postconditions:

  • Metadata server connected (optional)

  • File storage backend(s) configured

  • Cross-device sync enabled (if metadata server connected)

  • Books can be uploaded to selected storage

See Server architecture for technical details.
Use Case: Process scanned documents UC-7_2
status: open
priority: P2
actors: Reader
links outgoing: FR-7_3
links incoming: FR-7_3

System applies OCR to scanned books.

Preconditions:

  • PDF with scanned images uploaded

Main flow:

  1. System detects scanned content

  2. System queues OCR processing

  3. OCR runs in background

  4. Text extracted and indexed

  5. User notified of completion

Postconditions:

  • Book content is searchable
Use Case: Synchronize data across devices UC-7_3
status: open
priority: P0
actors: Registered User
links outgoing: FR-5_3, NFR-2_1
links incoming: FR-5_3

System keeps metadata, reading progress, and annotations consistent across devices via the metadata server.

Preconditions:

  • User logged into metadata server on multiple devices

  • At least one device has internet connection

Main flow:

  1. User makes changes on device A (e.g., reads pages, adds annotation)

  2. Changes are saved locally immediately

  3. Changes are queued in sync queue

  4. When online, client pushes changes to metadata server

  5. Metadata server records changes with timestamps

  6. Device B polls or receives push notification

  7. Device B fetches changes from metadata server

  8. Device B applies changes to local storage

  9. UI updates to reflect synchronized state

Synchronized data:

  • Reading position (page, chapter, percentage)

  • Annotations (highlights, notes)

  • Bookmarks

  • Book metadata edits

  • Shelf and tag assignments

  • Reading goals and progress

  • Reading session statistics

Alternative flows:

A1: Conflict detected (same book, both devices)

  1. System compares timestamps

  2. For reading position: latest timestamp wins

  3. For metadata: merge non-conflicting fields, latest wins for conflicts

  4. For annotations: keep both (no conflict, additive)

  5. User notified of resolved conflicts (optional)

A2: Offline changes accumulated

  1. User works offline on device A

  2. Multiple changes queued locally

  3. When device comes online, all queued changes sync

  4. Server processes changes in timestamp order

A3: Book file sync

  1. If book exists on server but not locally

  2. User can download for offline access

  3. File downloaded from configured storage backend

  4. Local reading position preserved after download

A4: Metadata server unavailable

  1. Client detects connection failure

  2. UI shows “Offline” or “Sync unavailable” indicator

  3. All changes continue to be saved locally

  4. Sync resumes automatically when server available

Postconditions:

  • All devices have consistent metadata

  • Reading position synchronized

  • Annotations available on all devices

See Server architecture for sync details.
Use Case: Browse OPDS catalog UC-7_4
status: open
priority: P2
actors: Reader
links outgoing: FR-7_5
links incoming: FR-7_5

User downloads books from online catalogs.

Preconditions:

  • OPDS catalog URL known

  • Internet connection available

Main flow:

  1. User adds OPDS catalog URL

  2. System loads catalog

  3. User browses or searches

  4. User selects book to download

  5. Book added to library

Alternative flows:

A1: Protected catalog

  • User enters credentials

  • System authenticates

Postconditions:

  • Book downloaded to library