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
This commit is contained in:
426
.kiro/specs/bookmark-manager/design.md
Normal file
426
.kiro/specs/bookmark-manager/design.md
Normal file
@ -0,0 +1,426 @@
|
||||
# Bookmark Manager - Design Document
|
||||
|
||||
## Overview
|
||||
|
||||
The Bookmark Manager is a client-side web application built with vanilla JavaScript, HTML5, and CSS3. It provides a comprehensive bookmark management solution with import/export capabilities, link validation, duplicate detection, and an intuitive folder-based organization system. The application uses browser localStorage for data persistence and follows modern web development best practices for responsive design and user experience.
|
||||
|
||||
## Architecture
|
||||
|
||||
### High-Level Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
UI[User Interface Layer]
|
||||
BM[BookmarkManager Class]
|
||||
PARSER[HTML Parser]
|
||||
STORAGE[localStorage API]
|
||||
NETWORK[Fetch API]
|
||||
|
||||
UI --> BM
|
||||
BM --> PARSER
|
||||
BM --> STORAGE
|
||||
BM --> NETWORK
|
||||
|
||||
subgraph "Browser APIs"
|
||||
STORAGE
|
||||
NETWORK
|
||||
DOM[DOM API]
|
||||
FILE[File API]
|
||||
end
|
||||
|
||||
subgraph "Core Components"
|
||||
BM
|
||||
PARSER
|
||||
end
|
||||
```
|
||||
|
||||
### Application Flow
|
||||
|
||||
1. **Initialization**: Application loads, restores data from localStorage, binds events
|
||||
2. **Data Management**: CRUD operations on bookmarks with automatic persistence
|
||||
3. **Import/Export**: File-based operations using HTML parsing and generation
|
||||
4. **Link Testing**: Asynchronous HTTP requests with progress tracking
|
||||
5. **UI Updates**: Real-time rendering based on data changes and user interactions
|
||||
|
||||
## Components and Interfaces
|
||||
|
||||
### 1. BookmarkManager Class
|
||||
|
||||
**Purpose**: Central controller managing all bookmark operations and UI interactions
|
||||
|
||||
**Key Properties**:
|
||||
- `bookmarks: Array<Bookmark>` - Main bookmark collection
|
||||
- `currentEditId: string|null` - ID of bookmark being edited
|
||||
- `currentFilter: string` - Active filter state ('all', 'valid', 'invalid', 'duplicate')
|
||||
- `currentContextBookmark: Bookmark` - Bookmark selected in context menu
|
||||
|
||||
**Key Methods**:
|
||||
- `init()` - Initialize application
|
||||
- `bindEvents()` - Attach event listeners
|
||||
- `renderBookmarks(bookmarks?)` - Render bookmark display
|
||||
- `updateStats()` - Update statistics display
|
||||
|
||||
### 2. Bookmark Data Model
|
||||
|
||||
```typescript
|
||||
interface Bookmark {
|
||||
id: string; // Unique identifier (timestamp + random)
|
||||
title: string; // Display title
|
||||
url: string; // Target URL
|
||||
folder: string; // Folder path (e.g., "Development / Tools")
|
||||
addDate: number; // Creation timestamp
|
||||
lastModified?: number; // Last modification timestamp
|
||||
icon: string; // Favicon URL or data URI
|
||||
status: 'unknown' | 'valid' | 'invalid' | 'testing' | 'duplicate';
|
||||
}
|
||||
```
|
||||
|
||||
### 3. HTML Parser Component
|
||||
|
||||
**Purpose**: Parse Netscape bookmark HTML files and extract bookmark data
|
||||
|
||||
**Key Features**:
|
||||
- Two-pass parsing algorithm for robust folder hierarchy detection
|
||||
- Metadata preservation (dates, icons, attributes)
|
||||
- Folder path normalization (removes "Bookmarks Toolbar")
|
||||
- Error handling for malformed HTML
|
||||
|
||||
**Algorithm**:
|
||||
1. **Pass 1**: Build folder hierarchy map from H3 elements
|
||||
2. **Pass 2**: Process A elements and assign to folders based on DOM relationships
|
||||
|
||||
### 4. Storage Interface
|
||||
|
||||
**Purpose**: Persist bookmark data using browser localStorage
|
||||
|
||||
**Methods**:
|
||||
- `saveBookmarksToStorage()` - Serialize and store bookmark array
|
||||
- `loadBookmarksFromStorage()` - Deserialize and restore bookmarks
|
||||
- `clearStorage()` - Remove all stored data
|
||||
|
||||
**Data Format**: JSON serialization of bookmark array
|
||||
|
||||
### 5. Link Testing Component
|
||||
|
||||
**Purpose**: Validate bookmark URLs using HTTP requests
|
||||
|
||||
**Features**:
|
||||
- Asynchronous testing with progress tracking
|
||||
- Configurable timeout (10 seconds)
|
||||
- CORS handling with opaque response support
|
||||
- Batch processing for "Test All" operations
|
||||
- Selective retesting for invalid links
|
||||
|
||||
**Status Mapping**:
|
||||
- `valid` - HTTP 200-299 or opaque response
|
||||
- `invalid` - Network error, timeout, or HTTP error
|
||||
- `testing` - Currently being tested
|
||||
- `unknown` - Not yet tested
|
||||
|
||||
## Data Models
|
||||
|
||||
### Folder Structure
|
||||
|
||||
Folders are represented as hierarchical paths using " / " separator:
|
||||
- Root level: `""` (empty string)
|
||||
- Single level: `"Development"`
|
||||
- Multi-level: `"Development / Web / JavaScript"`
|
||||
|
||||
### Statistics Model
|
||||
|
||||
```typescript
|
||||
interface Statistics {
|
||||
total: number;
|
||||
valid: number;
|
||||
invalid: number;
|
||||
duplicate: number;
|
||||
unknown: number;
|
||||
}
|
||||
```
|
||||
|
||||
### Filter States
|
||||
|
||||
- `all` - Show all bookmarks
|
||||
- `valid` - Show only valid bookmarks
|
||||
- `invalid` - Show only invalid bookmarks
|
||||
- `duplicate` - Show only duplicate bookmarks
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Import/Export Errors
|
||||
|
||||
- **File Selection**: Alert user if no file selected
|
||||
- **Parse Errors**: Try-catch around HTML parsing with user notification
|
||||
- **Empty Results**: Alert if no bookmarks found in file
|
||||
- **Export Errors**: Handle blob creation and download failures
|
||||
|
||||
### Link Testing Errors
|
||||
|
||||
- **Network Errors**: Catch fetch failures and mark as invalid
|
||||
- **Timeouts**: Use AbortController for request timeouts
|
||||
- **CORS Issues**: Handle opaque responses appropriately
|
||||
- **Invalid URLs**: Validate URL format before testing
|
||||
|
||||
### Storage Errors
|
||||
|
||||
- **localStorage Unavailable**: Graceful degradation without persistence
|
||||
- **Quota Exceeded**: Handle storage limit errors
|
||||
- **Serialization Errors**: Catch JSON stringify/parse failures
|
||||
|
||||
### UI Error States
|
||||
|
||||
- **Empty States**: Show helpful messages when no bookmarks exist
|
||||
- **Loading States**: Display progress indicators during operations
|
||||
- **Validation Errors**: Form validation with user feedback
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Testing Approach
|
||||
|
||||
**Core Functions to Test**:
|
||||
1. `parseNetscapeBookmarks()` - HTML parsing accuracy
|
||||
2. `normalizeUrl()` - URL normalization consistency
|
||||
3. `findDuplicates()` - Duplicate detection algorithm
|
||||
4. `generateNetscapeHTML()` - Export format compliance
|
||||
5. `searchBookmarks()` - Search filtering logic
|
||||
|
||||
**Test Data**:
|
||||
- Sample Netscape HTML files with various structures
|
||||
- Edge cases: empty folders, special characters, malformed URLs
|
||||
- Large datasets for performance testing
|
||||
|
||||
### Integration Testing
|
||||
|
||||
**User Workflows**:
|
||||
1. Import → Organize → Export cycle
|
||||
2. Add → Edit → Delete bookmark operations
|
||||
3. Search → Filter → Clear operations
|
||||
4. Test Links → View Results → Retest workflow
|
||||
|
||||
### Browser Compatibility Testing
|
||||
|
||||
**Target Browsers**:
|
||||
- Chrome 90+
|
||||
- Firefox 88+
|
||||
- Safari 14+
|
||||
- Edge 90+
|
||||
|
||||
**Key Features to Test**:
|
||||
- File API support
|
||||
- Fetch API with CORS
|
||||
- localStorage availability
|
||||
- CSS Grid and Flexbox support
|
||||
|
||||
### Performance Testing
|
||||
|
||||
**Scenarios**:
|
||||
- Import files with 10,000+ bookmarks
|
||||
- Link testing with 1,000+ URLs
|
||||
- Search performance with large datasets
|
||||
- UI responsiveness during operations
|
||||
|
||||
## User Interface Design
|
||||
|
||||
### Layout Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Header (Title + Import/Export/Add) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Toolbar (Search + Actions) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Stats (Total/Valid/Invalid/Dupes) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Progress Bar (when testing) │
|
||||
├─────────────────────────────────────┤
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │Folder 1 │ │Folder 2 │ │Folder 3 │ │
|
||||
│ │ • Link │ │ • Link │ │ • Link │ │
|
||||
│ │ • Link │ │ • Link │ │ • Link │ │
|
||||
│ └─────────┘ └─────────┘ └─────────┘ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Responsive Design
|
||||
|
||||
**Breakpoints**:
|
||||
- Desktop: 1200px+ (3-4 columns)
|
||||
- Tablet: 768px-1199px (2-3 columns)
|
||||
- Mobile: <768px (1 column, stacked layout)
|
||||
|
||||
**Mobile Adaptations**:
|
||||
- Header actions stack vertically
|
||||
- Toolbar becomes full-width column
|
||||
- Stats center-aligned
|
||||
- Touch-friendly button sizes
|
||||
|
||||
### Color Scheme
|
||||
|
||||
**Status Colors**:
|
||||
- Valid: `#28a745` (green)
|
||||
- Invalid: `#dc3545` (red)
|
||||
- Testing: `#ffc107` (yellow)
|
||||
- Duplicate: `#17a2b8` (blue)
|
||||
- Unknown: `#6c757d` (gray)
|
||||
|
||||
**UI Colors**:
|
||||
- Primary: `#3498db` (blue)
|
||||
- Secondary: `#95a5a6` (gray)
|
||||
- Success: `#27ae60` (green)
|
||||
- Warning: `#f39c12` (orange)
|
||||
- Danger: `#e74c3c` (red)
|
||||
|
||||
### Folder Selection Enhancement
|
||||
|
||||
**Design for Enhanced Folder Input**:
|
||||
|
||||
```html
|
||||
<div class="form-group">
|
||||
<label for="bookmarkFolder">Folder:</label>
|
||||
<div class="folder-input-container">
|
||||
<input type="text" id="bookmarkFolder" list="folderList"
|
||||
placeholder="Select existing folder or type new name">
|
||||
<datalist id="folderList">
|
||||
<!-- Dynamically populated with existing folders -->
|
||||
</datalist>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Features**:
|
||||
- HTML5 datalist for native dropdown with type-ahead
|
||||
- Dynamic population from existing folder names
|
||||
- Allows both selection and custom input
|
||||
- Consistent styling with existing form elements
|
||||
|
||||
### Animation and Transitions
|
||||
|
||||
**Hover Effects**:
|
||||
- Card elevation on hover (`transform: translateY(-2px)`)
|
||||
- Bookmark item slide on hover (`transform: translateX(4px)`)
|
||||
- Button lift effect (`transform: translateY(-1px)`)
|
||||
|
||||
**Loading States**:
|
||||
- Progress bar smooth width transitions
|
||||
- Pulse animation for testing status
|
||||
- Fade transitions for modal show/hide
|
||||
|
||||
**Responsive Transitions**:
|
||||
- Smooth grid layout changes on resize
|
||||
- Collapsible elements with height transitions
|
||||
- Mobile menu slide animations
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Content Security Policy
|
||||
|
||||
**Recommended CSP Headers**:
|
||||
```
|
||||
Content-Security-Policy:
|
||||
default-src 'self';
|
||||
script-src 'self' 'unsafe-inline';
|
||||
style-src 'self' 'unsafe-inline';
|
||||
connect-src *;
|
||||
```
|
||||
|
||||
### Data Sanitization
|
||||
|
||||
**HTML Escaping**:
|
||||
- All user input escaped before DOM insertion
|
||||
- `escapeHtml()` function for bookmark titles and URLs
|
||||
- Prevent XSS through innerHTML manipulation
|
||||
|
||||
**URL Validation**:
|
||||
- URL constructor validation before testing
|
||||
- Protocol restrictions (http/https only)
|
||||
- Malformed URL handling
|
||||
|
||||
### Privacy Considerations
|
||||
|
||||
**Local Storage Only**:
|
||||
- No server communication for bookmark data
|
||||
- All processing happens client-side
|
||||
- User maintains full control of data
|
||||
|
||||
**Link Testing Privacy**:
|
||||
- HEAD requests minimize data transfer
|
||||
- No cookies or authentication sent
|
||||
- User-initiated testing only
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### Rendering Optimizations
|
||||
|
||||
**Virtual Scrolling**: For large bookmark collections
|
||||
**Debounced Search**: 300ms delay for search input
|
||||
**Lazy Loading**: Defer non-critical UI elements
|
||||
**Efficient DOM Updates**: Minimize reflows and repaints
|
||||
|
||||
### Memory Management
|
||||
|
||||
**Event Listener Cleanup**: Remove listeners when not needed
|
||||
**Object Pooling**: Reuse DOM elements where possible
|
||||
**Garbage Collection**: Avoid memory leaks in long-running operations
|
||||
|
||||
### Network Optimizations
|
||||
|
||||
**Request Batching**: Sequential link testing to avoid overwhelming servers
|
||||
**Timeout Management**: Reasonable timeouts to prevent hanging requests
|
||||
**Error Recovery**: Retry logic for transient network failures
|
||||
|
||||
## Accessibility Features
|
||||
|
||||
### Keyboard Navigation
|
||||
|
||||
- Tab order through all interactive elements
|
||||
- Enter/Space activation for buttons
|
||||
- Escape key to close modals
|
||||
- Arrow key navigation in lists
|
||||
|
||||
### Screen Reader Support
|
||||
|
||||
- Semantic HTML structure
|
||||
- ARIA labels for complex interactions
|
||||
- Status announcements for dynamic content
|
||||
- Alternative text for icons
|
||||
|
||||
### Visual Accessibility
|
||||
|
||||
- High contrast color ratios (WCAG AA compliance)
|
||||
- Focus indicators for keyboard navigation
|
||||
- Scalable text and UI elements
|
||||
- Color-blind friendly status indicators
|
||||
|
||||
## Browser Storage Strategy
|
||||
|
||||
### localStorage Implementation
|
||||
|
||||
**Data Structure**:
|
||||
```javascript
|
||||
{
|
||||
"bookmarks": [
|
||||
{
|
||||
"id": "1642534567890_0.123",
|
||||
"title": "Example Site",
|
||||
"url": "https://example.com",
|
||||
"folder": "Development / Tools",
|
||||
"addDate": 1642534567890,
|
||||
"icon": "data:image/png;base64,...",
|
||||
"status": "valid"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Storage Limits**:
|
||||
- Typical limit: 5-10MB per origin
|
||||
- Monitoring: Check available space before large operations
|
||||
- Cleanup: Provide clear all functionality
|
||||
|
||||
### Backup and Recovery
|
||||
|
||||
**Export as Backup**: Regular export recommendations
|
||||
**Import Recovery**: Merge vs replace options
|
||||
**Data Validation**: Integrity checks on load
|
||||
|
||||
This design document provides a comprehensive blueprint for implementing and maintaining the Bookmark Manager application, ensuring scalability, maintainability, and excellent user experience.
|
||||
Reference in New Issue
Block a user