Non-functional requirements¶

This document defines the non-functional requirements (quality attributes) for Papyrus. These requirements specify how the system should perform rather than what it should do.

Priority levels¶

1. Storage¶

NFR-1.1: Maximum file size¶

Priority: P0

Maximum allowed file size shall not exceed 2048 MB (2 GB) per book file.

Acceptance criteria:

• Files up to 2 GB upload successfully
• Files exceeding 2 GB are rejected with clear error message
• Large file uploads show progress indicator
• Upload can be resumed after interruption (for files > 100 MB)

NFR-1.2: Storage backend support¶

Priority: P0

The system shall support multiple storage backends.

Supported Backends:

1. Local storage (device file system)
2. Cloud storage: Google Drive, OneDrive, Dropbox
3. Self-hosted server (MinIO, local file system)
4. Network-attached storage (NAS via SMB/NFS)

Acceptance criteria:

• Each backend can be configured independently
• User can switch between backends without data loss
• Backend credentials are stored securely (encrypted)
• Connection status is visible to user

NFR-1.3: Multi-backend configuration¶

Priority: P1

The system shall support multiple storage backends per user with automatic failover.

Acceptance criteria:

• User can configure up to 3 storage backends
• One backend is designated as primary
• Automatic failover to secondary if primary is unavailable
• Manual override to force specific backend

NFR-1.4: File encryption¶

Priority: P2

File encryption shall be available for sensitive content with user-controlled keys.

Acceptance criteria:

• AES-256 encryption for files at rest
• User-managed encryption keys
• Encrypted files are decrypted on-device only
• Key recovery mechanism available

2. Synchronization¶

NFR-2.1: Online/offline parity¶

Priority: P0

The system shall work in online and offline mode with full feature parity for core reading features.

Acceptance criteria:

• All reading features work offline
• Library management works offline
• Annotations and notes work offline
• Only sync and cloud features require connectivity
• Clear indicator of online/offline status

NFR-2.2: Offline change indicators¶

Priority: P0

Any changes made offline shall have an appropriate visual indicator.

Acceptance criteria:

• Unsynced items show sync-pending icon
• Last sync timestamp visible in settings
• Number of pending changes displayed
• User can manually trigger sync when online

NFR-2.3: Conflict resolution¶

Priority: P1

Synchronization conflicts shall be resolved with user-selectable strategies.

Resolution Strategies:

1. Server wins (default)
2. Client wins
3. Manual resolution (user chooses)
4. Merge (where possible)

Acceptance criteria:

• User can set default strategy in settings
• Per-conflict override option
• Conflict history log
• No silent data loss

NFR-2.4: Sync performance¶

Priority: P0

Cross-device synchronization shall complete within 30 seconds under normal network conditions (>= 1 Mbps).

Acceptance criteria:

• Reading position syncs within 30 seconds
• Metadata changes sync within 1 minute
• Book files sync based on file size and bandwidth
• Background sync does not impact reading performance

3. Platform support¶

NFR-3.1: Web browser support¶

Priority: P0

The system shall be available in modern web browsers.

Supported Browsers:

• Chrome 90+
• Firefox 90+
• Safari 14+
• Edge 90+

Acceptance criteria:

• All core features work in supported browsers
• Progressive Web App (PWA) installable
• Offline capability via service worker
• Responsive design for all viewport sizes

NFR-3.2: Desktop operating system support¶

Priority: P0

The system shall be available on major desktop operating systems.

Supported Operating Systems:

• Windows 10 or later
• macOS 10.15 (Catalina) or later
• Major Linux distributions (Ubuntu 20.04+, Fedora 35+, Debian 11+)

Acceptance criteria:

• Native application available for each platform
• Platform-specific keyboard shortcuts
• System tray/menu bar integration
• File association for supported formats

NFR-3.3: Mobile operating system support¶

Priority: P0

The system shall work on mobile devices.

Supported Platforms:

• Android 8.0 (API level 26) or later
• iOS 12.0 or later

Acceptance criteria:

• App available in Google Play Store and Apple App Store
• Touch-optimized interface
• Support for device orientation changes
• Background sync support
• Push notifications (optional)

NFR-3.4: E-ink device support¶

Priority: P1

The system shall support e-ink readers and tablets with touch interfaces.

Target Devices:

• Kobo readers (via sideloading)
• Android-based e-ink devices (Boox, Hisense)
• reMarkable (future consideration)

Acceptance criteria:

• E-ink optimized UI mode (high contrast, grayscale)
• Reduced/disabled animations
• Larger touch targets (minimum 48px)
• Support for hardware page-turn buttons
• Reduced screen refresh for battery efficiency
• Dark-on-light and light-on-dark themes optimized for e-ink

4. Performance¶

NFR-4.1: Application startup¶

Priority: P0

Application startup time shall not exceed 3 seconds on supported devices.

Acceptance criteria:

• Cold start < 3 seconds on mid-range devices (2020+)
• Warm start < 1 second
• Library view loads within 2 seconds of app start
• Progress indicator shown if startup exceeds 1 second

NFR-4.2: Book opening¶

Priority: P0

Book opening time shall not exceed 2 seconds for files up to 50 MB.

Acceptance criteria:

• EPUB < 50 MB opens in < 2 seconds
• PDF < 50 MB opens in < 3 seconds
• Progress indicator for larger files
• Last reading position restored automatically
• Opening performance measured on mid-range devices

NFR-4.3: Search performance¶

Priority: P0

Search results shall be returned within 1 second for libraries up to 10,000 books.

Acceptance criteria:

• Metadata search returns in < 500ms
• Full-text search returns in < 1 second
• Results are paginated for large result sets
• Search is cancelable
• Incremental results shown as available

NFR-4.4: Library scalability¶

Priority: P1

The system shall support libraries with up to 50,000 books without performance degradation.

Acceptance criteria:

• Library view loads in < 3 seconds with 50,000 books
• Search remains under 2 seconds
• Scrolling remains smooth (60 FPS on capable devices)
• Memory usage scales linearly with library size
• Virtual scrolling for large lists

NFR-4.5: E-ink performance¶

Priority: P1

The system shall be optimized for e-ink display refresh characteristics.

Acceptance criteria:

• Page turns complete in < 500ms
• Minimal full-refresh operations
• Partial refresh used where possible
• UI updates batched to reduce flicker
• Animation duration configurable (default: 0 for e-ink)

5. Usability¶

NFR-5.1: Design system¶

Priority: P0

The user interface shall follow Material 3 design guidelines.

Acceptance criteria:

• Consistent use of Material 3 components
• Dynamic color theming support
• Consistent typography scale
• Proper use of elevation and surfaces
• Dark/light theme support

NFR-5.2: Accessibility¶

Priority: P0

The application shall be accessible to users with disabilities (WCAG 2.1 AA compliance).

Acceptance criteria:

• Screen reader compatibility (TalkBack, VoiceOver)
• Minimum color contrast ratio 4.5:1
• All interactive elements keyboard accessible
• Focus indicators visible
• Text scalable up to 200%
• No information conveyed by color alone
• Touch targets minimum 44x44 points

NFR-5.3: RTL and internationalization¶

Priority: P1

The system shall support right-to-left (RTL) languages and internationalization.

Acceptance criteria:

• UI mirrors correctly for RTL languages
• Book content renders correctly for RTL text
• Date/time formats localized
• Number formats localized
• Bidirectional text support

NFR-5.4: Localization¶

Priority: P1

All user-facing text shall be localizable.

Acceptance criteria:

• English as primary language
• Localization framework in place for additional languages
• No hardcoded user-facing strings
• Locale can be overridden in settings
• Pluralization rules supported

NFR-5.5: E-ink usability¶

Priority: P1

The system shall provide optimized usability for e-ink displays.

Acceptance criteria:

• High contrast theme option
• Simplified UI with fewer visual elements
• Large, clear typography
• Reduced reliance on hover states
• Clear button/touch feedback without animations

6. Security¶

NFR-6.1: Password security¶

Priority: P0

User passwords shall be hashed using industry-standard algorithms.

Acceptance criteria:

• Passwords hashed with bcrypt or Argon2
• Minimum password length: 8 characters
• Password strength indicator during registration
• No plaintext password storage or transmission
• Secure password reset mechanism

NFR-6.2: Transport security¶

Priority: P0

All data transmission shall use TLS 1.3 or higher encryption.

Acceptance criteria:

• HTTPS required for all API communication
• Certificate pinning for mobile apps (optional)
• No fallback to unencrypted connections
• TLS 1.2 minimum (1.3 preferred)

NFR-6.3: Two-factor authentication¶

Priority: P2

The system shall support two-factor authentication (TOTP).

Acceptance criteria:

• TOTP-based 2FA (Google Authenticator compatible)
• Backup codes available
• 2FA can be enabled/disabled by user
• Graceful recovery if 2FA device lost

NFR-6.4: Session management¶

Priority: P0

Session management shall include automatic timeout and secure token handling.

Acceptance criteria:

• JWT tokens with configurable expiration
• Refresh token rotation
• Sessions can be revoked remotely
• Automatic logout after inactivity (configurable)
• Secure token storage on device

NFR-6.5: Privacy by default¶

Priority: P0

The application shall collect no analytics by default; telemetry is opt-in.

Acceptance criteria:

• No analytics without explicit consent
• Clear privacy policy accessible in-app
• Telemetry settings easily accessible
• No third-party tracking SDKs by default
• Data collection scope clearly explained

7. Reliability¶

NFR-7.1: System uptime¶

Priority: P1

The system shall have 99.5% uptime for self-hosted deployments under normal conditions.

Acceptance criteria:

• Maximum planned downtime: 4 hours/month
• Health check endpoints available
• Graceful degradation during partial outages
• Automatic recovery from transient failures

NFR-7.2: Data integrity¶

Priority: P0

Data corruption shall be prevented through checksums and integrity verification.

Acceptance criteria:

• File checksums verified on upload/download
• Database transactions are atomic
• Corrupted files detected and reported
• No silent data corruption

NFR-7.3: Network resilience¶

Priority: P0

The system shall gracefully handle network interruptions without data loss.

Acceptance criteria:

• Operations are idempotent where possible
• Uploads/downloads resumable
• No data loss on network failure
• Clear error messages for network issues
• Automatic retry with exponential backoff

NFR-7.4: Backup and restore¶

Priority: P1

Automatic backup and restore capabilities shall be available for user data.

Acceptance criteria:

• Export all user data in portable format
• Import/restore from backup
• Scheduled automatic backups (optional)
• Backup integrity verification

8. Extensibility¶

NFR-8.1: Plugin architecture¶

Priority: P3

The architecture shall support modular plugins without compromising core stability.

Acceptance criteria:

• Plugin API documented
• Plugins run in sandboxed environment
• Core functionality unaffected by plugin failures
• Plugin enable/disable without restart
• Version compatibility checking

9. Maintainability¶

NFR-9.1: Code quality¶

Priority: P1

The codebase shall maintain high quality standards.

Acceptance criteria:

• Automated linting (dart analyze)
• Code formatting enforced (dart format)
• Minimum 70% test coverage for core functionality
• No critical security vulnerabilities
• Documentation for public APIs

NFR-9.2: Logging and monitoring¶

Priority: P1

The system shall provide comprehensive logging and monitoring capabilities.

Acceptance criteria:

• Structured logging for all components
• Log levels configurable (debug, info, warning, error)
• No sensitive data in logs
• Log rotation and retention policies
• Error tracking integration (optional)

Requirements summary¶

MVP (p0/p1) requirements count¶

Post-MVP (p2/p3) requirements¶