arkay/bookmarksite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0abee5b794ea8bc7178c729d5ab97a3e57d20e62
bookmarksite/bookmark-manager-requirements.md
Rainer Koschnick 0abee5b794 Add comprehensive database setup and user management system 
- Implement PostgreSQL database schema with users and bookmarks tables
- Add database connection pooling with retry logic and error handling
- Create migration system with automatic schema initialization
- Add database CLI tools for management (init, status, validate, etc.)
- Include comprehensive error handling and diagnostics
- Add development seed data and testing utilities
- Implement health monitoring and connection pool statistics
- Create detailed documentation and troubleshooting guide

Database features:
- Users table with authentication fields and email verification
- Bookmarks table with user association and metadata
- Proper indexes for performance optimization
- Automatic timestamp triggers
- Transaction support with rollback handling
- Connection pooling (20 max connections, 30s idle timeout)
- Graceful shutdown handling

CLI commands available:
- npm run db:init - Initialize database
- npm run db:status - Check database status
- npm run db:validate - Validate schema
- npm run db:test - Run database tests
- npm run db:diagnostics - Full diagnostics
2025-07-19 23:21:50 +02:00

10 KiB
Raw Blame History

Bookmark Manager - Requirements Document

Introduction

The Bookmark Manager is a web-based application designed to help users organize, manage, and maintain their browser bookmarks. The application provides comprehensive bookmark management capabilities including import/export functionality, link validation, duplicate detection, and an intuitive folder-based organization system.

Requirements

Requirement 1: Bookmark Import and Export

User Story: As a user, I want to import and export my bookmarks in standard formats, so that I can migrate bookmarks between browsers and backup my bookmark collection.

Acceptance Criteria

  1. WHEN a user clicks the "Import Bookmarks" button THEN the system SHALL display a file selection modal
  2. WHEN a user selects a Netscape bookmark HTML file THEN the system SHALL parse and import all bookmarks with their folder structure
  3. WHEN importing bookmarks THEN the system SHALL preserve bookmark metadata including titles, URLs, folders, creation dates, and favicons
  4. WHEN importing bookmarks THEN the system SHALL filter out "Bookmarks Toolbar" and "Bookmarks Bar" from folder paths to create cleaner organization
  5. WHEN importing bookmarks THEN the system SHALL offer the user a choice to replace existing bookmarks or merge with current collection
  6. WHEN a user clicks "Export Bookmarks" THEN the system SHALL generate a Netscape-compatible HTML file for download
  7. WHEN exporting bookmarks THEN the system SHALL organize bookmarks by folders and preserve all metadata
  8. WHEN exporting bookmarks THEN the system SHALL use the current date in the filename format "bookmarks_YYYY-MM-DD.html"

Requirement 2: Bookmark Organization and Management

User Story: As a user, I want to organize my bookmarks into folders and manage individual bookmarks, so that I can maintain a structured and accessible bookmark collection.

Acceptance Criteria

  1. WHEN bookmarks are displayed THEN the system SHALL group them by folder in card-based layout
  2. WHEN a folder contains bookmarks THEN the system SHALL display the folder name, bookmark count, and status statistics
  3. WHEN a user adds a new bookmark THEN the system SHALL require title and URL fields and allow optional folder assignment
  4. WHEN the folder field is focused THEN the system SHALL provide a dropdown list of all existing folders for selection
  5. WHEN selecting from folder dropdown THEN the system SHALL allow users to choose an existing folder or type a new folder name
  6. WHEN a user edits a bookmark THEN the system SHALL allow modification of title, URL, and folder assignment with the same folder selection capabilities
  7. WHEN a user deletes a bookmark THEN the system SHALL request confirmation before permanent removal
  8. WHEN bookmarks are displayed THEN the system SHALL show bookmark titles, URLs (on hover), and status indicators
  9. WHEN a user hovers over a bookmark THEN the system SHALL expand to show the full URL and title
  10. WHEN bookmarks exceed the card height limit THEN the system SHALL provide vertical scrolling within the card

Requirement 3: Link Validation and Testing

User Story: As a user, I want to test my bookmarks to identify broken links, so that I can maintain a collection of working bookmarks.

Acceptance Criteria

  1. WHEN a user clicks "Test All Links" THEN the system SHALL test every bookmark URL for accessibility
  2. WHEN testing links THEN the system SHALL display a progress bar showing current progress and bookmark being tested
  3. WHEN testing a link THEN the system SHALL use HTTP HEAD requests with 10-second timeout to minimize bandwidth
  4. WHEN a link test completes THEN the system SHALL mark bookmarks as "valid", "invalid", or "unknown" status
  5. WHEN a user clicks "Test Invalid Links" THEN the system SHALL retest only bookmarks previously marked as invalid
  6. WHEN link testing encounters CORS restrictions THEN the system SHALL handle opaque responses appropriately
  7. WHEN testing completes THEN the system SHALL update bookmark status indicators and statistics
  8. WHEN a user clicks on a bookmark status indicator THEN the system SHALL show a context menu with testing options

Requirement 4: Search and Filtering

User Story: As a user, I want to search and filter my bookmarks, so that I can quickly find specific bookmarks in large collections.

Acceptance Criteria

  1. WHEN a user types in the search box THEN the system SHALL filter bookmarks in real-time based on title, URL, and folder name
  2. WHEN search results are displayed THEN the system SHALL maintain the current filter state (all/valid/invalid/duplicates)
  3. WHEN a user clicks filter buttons THEN the system SHALL show only bookmarks matching the selected status
  4. WHEN "All" filter is active THEN the system SHALL display all bookmarks regardless of status
  5. WHEN "Valid" filter is active THEN the system SHALL display only bookmarks with valid status
  6. WHEN "Invalid" filter is active THEN the system SHALL display only bookmarks with invalid status
  7. WHEN "Duplicates" filter is active THEN the system SHALL display only bookmarks marked as duplicates
  8. WHEN filters are applied THEN the system SHALL update the statistics display to reflect filtered counts

Requirement 5: Duplicate Detection and Management

User Story: As a user, I want to identify duplicate bookmarks in my collection, so that I can clean up redundant entries and maintain an organized bookmark library.

Acceptance Criteria

  1. WHEN a user clicks "Find Duplicates" THEN the system SHALL analyze all bookmarks for duplicate URLs
  2. WHEN detecting duplicates THEN the system SHALL normalize URLs by removing trailing slashes and www prefixes
  3. WHEN duplicates are found THEN the system SHALL mark all instances in duplicate groups with "duplicate" status
  4. WHEN duplicate detection completes THEN the system SHALL display an alert showing the number of duplicates found
  5. WHEN no duplicates exist THEN the system SHALL inform the user that no duplicates were found
  6. WHEN duplicates are marked THEN the system SHALL update the statistics display to show duplicate count
  7. WHEN duplicate detection runs THEN the system SHALL reset any previously marked duplicates before new analysis

Requirement 6: Data Persistence and Storage

User Story: As a user, I want my bookmarks to be saved automatically, so that my work is preserved between browser sessions.

Acceptance Criteria

  1. WHEN bookmarks are imported, added, edited, or deleted THEN the system SHALL automatically save to browser localStorage
  2. WHEN the application loads THEN the system SHALL restore bookmarks from localStorage if available
  3. WHEN bookmark status is updated THEN the system SHALL persist the new status information
  4. WHEN a user clears all bookmarks THEN the system SHALL remove all data from localStorage after confirmation
  5. WHEN localStorage is unavailable THEN the system SHALL handle gracefully without crashing

Requirement 7: User Interface and Experience

User Story: As a user, I want an intuitive and responsive interface, so that I can efficiently manage my bookmarks across different devices.

Acceptance Criteria

  1. WHEN the application loads THEN the system SHALL display a clean, modern interface with clear navigation
  2. WHEN bookmarks are displayed THEN the system SHALL use a responsive grid layout that adapts to screen size
  3. WHEN on mobile devices THEN the system SHALL stack interface elements vertically for better usability
  4. WHEN performing long operations THEN the system SHALL show progress indicators and status messages
  5. WHEN hovering over interactive elements THEN the system SHALL provide visual feedback with hover effects
  6. WHEN displaying status information THEN the system SHALL use color-coded indicators (green=valid, red=invalid, blue=duplicate, gray=unknown)
  7. WHEN modals are displayed THEN the system SHALL allow closing by clicking outside the modal or using close buttons
  8. WHEN errors occur THEN the system SHALL display user-friendly error messages

Requirement 8: Context Menu and Bookmark Actions

User Story: As a user, I want quick access to bookmark actions, so that I can efficiently manage individual bookmarks.

Acceptance Criteria

  1. WHEN a user clicks on a bookmark THEN the system SHALL display a context menu with available actions
  2. WHEN "Visit" is selected THEN the system SHALL open the bookmark URL in a new browser tab
  3. WHEN "Test Link" is selected THEN the system SHALL test the individual bookmark and update its status
  4. WHEN "Edit" is selected THEN the system SHALL open the bookmark editing modal with current values
  5. WHEN "Delete" is selected THEN the system SHALL request confirmation and remove the bookmark if confirmed
  6. WHEN context menu actions complete THEN the system SHALL close the context menu automatically

Requirement 9: Statistics and Monitoring

User Story: As a user, I want to see statistics about my bookmark collection, so that I can understand the health and size of my bookmark library.

Acceptance Criteria

  1. WHEN bookmarks are loaded or updated THEN the system SHALL calculate and display total bookmark count
  2. WHEN link testing occurs THEN the system SHALL update counts for valid and invalid bookmarks
  3. WHEN duplicate detection runs THEN the system SHALL update the duplicate bookmark count
  4. WHEN statistics are displayed THEN the system SHALL show counts as clickable filter buttons
  5. WHEN folder cards are displayed THEN the system SHALL show individual folder statistics including valid/invalid counts
  6. WHEN statistics change THEN the system SHALL update the display in real-time

Requirement 10: Performance and Scalability

User Story: As a user, I want the application to perform well with large bookmark collections, so that I can manage thousands of bookmarks efficiently.

Acceptance Criteria

  1. WHEN importing large bookmark files THEN the system SHALL parse and display bookmarks without blocking the UI
  2. WHEN testing many links THEN the system SHALL process them sequentially to avoid overwhelming servers
  3. WHEN displaying many bookmarks THEN the system SHALL use efficient rendering to maintain responsive performance
  4. WHEN searching large collections THEN the system SHALL provide fast, real-time filtering results
  5. WHEN bookmark cards contain many items THEN the system SHALL limit display height and provide scrolling