Skip to main content

Pull Request: B4M Notebook Export/Import System

Optional Screenshot/Video​

Screenshots will be added after implementation showing:

  • Export dialog with download options (single notebook vs. all notebooks)
  • Import modal with drag-and-drop interface
  • Success/error states during import process
  • Imported notebooks appearing in the sidebar

Description​

This PR implements a comprehensive Notebook Export/Import System for Bike4Mind, allowing users to:

Export Capabilities​

  • Single Notebook Export: Download individual notebooks as JSON files with full conversation history, metadata, and attachments
  • Bulk Export: Download all user notebooks as a single JSON file or ZIP archive
  • Selective Export: Choose specific notebooks from a list for batch export

Import Capabilities​

  • Single Notebook Import: Upload and restore individual .json notebook files
  • Bulk Import: Import multiple notebooks from JSON files or ZIP archives
  • Smart Conflict Resolution: Handle naming conflicts and duplicate detection
  • Data Validation: Ensure imported notebooks meet current schema requirements

Key Features​

  • Drag & Drop Interface: Modern file upload experience similar to existing import-history modal
  • Progress Tracking: Real-time feedback during import/export operations
  • Error Handling: Comprehensive validation with user-friendly error messages
  • Metadata Preservation: Maintains original creation dates, tags, summaries, and relationships
  • Cross-User Safety: Prevents unauthorized access to other users' data during import

Changes​

Backend API Endpoints​

  • Enhanced /api/sessions/download: Extended to support single notebook export and format options
  • New /api/sessions/import/upload: Generates signed URLs for notebook file uploads
  • New /api/sessions/import/process: Processes uploaded notebook files and creates sessions
  • New /api/sessions/export/bulk: Handles multi-notebook export with compression options

Frontend Components​

  • NotebookExportModal.tsx: Modal for selecting export options and format
  • NotebookImportModal.tsx: Drag-and-drop import interface with progress tracking
  • Enhanced OwnNotebooks.tsx: Added export/import buttons to notebook sidebar
  • NotebookImportProgress.tsx: Real-time import progress and error reporting

Core Services​

  • notebookExportService/: Handles export logic, compression, and format conversion
  • notebookImportService/: Manages import validation, conflict resolution, and session creation
  • Enhanced sessionService/: Extended with import-specific session creation methods

Database & Schema​

  • Import tracking: New fields to track imported notebook origins
  • Validation schemas: Ensure backward/forward compatibility of exported data
  • Relationship mapping: Maintain knowledge, agent, and artifact associations

UI/UX Enhancements​

  • Export button in individual notebook context menus (3-dot menu)
  • Bulk export option in notebook sidebar header
  • Import button prominently placed in sidebar for easy access
  • Toast notifications for all export/import operations
  • Loading states and progress indicators throughout the flow

Guide for Testers​

Testing Export Functionality​

  1. Single Notebook Export:

    • Navigate to any notebook
    • Click the 3-dot menu next to the notebook name
    • Select "Export Notebook"
    • Choose JSON format and download
    • Verify the downloaded file contains complete conversation history

  2. Bulk Export:

    • Go to notebook sidebar
    • Click "Export All Notebooks" button
    • Select format (JSON or ZIP)
    • Download and verify all notebooks are included

Testing Import Functionality​

  1. Single Notebook Import:

    • Click "Import Notebook" in sidebar
    • Drag and drop a previously exported .json file
    • Verify notebook appears in sidebar with correct name and data
    • Open imported notebook and check conversation history

  2. Bulk Import:

    • Export multiple notebooks to create test data
    • Use import modal to upload the bulk export file
    • Verify all notebooks are imported correctly
    • Check for proper handling of naming conflicts

  3. Error Scenarios:

    • Try importing invalid JSON files
    • Import files with missing required fields
    • Test file size limits and format validation
    • Verify error messages are clear and actionable

Cross-Browser Testing​

  • Test drag-and-drop functionality in Chrome, Firefox, Safari
  • Verify file upload progress indicators work correctly
  • Check modal responsiveness on mobile devices

Data Integrity Testing​

  • Export a notebook with knowledge files, agents, and artifacts attached
  • Import the notebook and verify all relationships are preserved
  • Check that imported notebooks maintain original timestamps
  • Ensure user permissions are respected (can't import others' data)

Additional Information​

Technical Implementation Notes​

  • File Format: Uses JSON for maximum compatibility and human readability
  • Compression: ZIP support for bulk exports to reduce file sizes
  • Security: Server-side validation prevents malicious file uploads
  • Performance: Streaming uploads for large notebook collections
  • Backward Compatibility: Import validates and migrates older export formats

Error Handling Strategy​

  • Client-side validation: File type, size, and format checks before upload
  • Server-side sanitization: Clean and validate all imported data
  • Graceful degradation: Partial imports succeed even if some notebooks fail
  • Detailed logging: Track import/export operations for debugging

Future Enhancements (Not in this PR)​

  • Scheduled exports: Automatic backup functionality
  • Cloud storage integration: Direct export to Google Drive, Dropbox
  • Notebook sharing: Export with sharing permissions intact
  • Template creation: Export notebooks as reusable templates

Migration Strategy​

  • Existing exports: Current /api/sessions/download endpoint remains functional
  • Gradual rollout: New import functionality can be feature-flagged
  • Data safety: All imports create new notebooks (no overwrites by default)

Checklist​

  • I have added the new AdminSettings to Staging, prod and the hydration script (if applicable)
  • I have made the UI/UX feel good (toasters, size, responsive, etc)
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation (if applicable)
  • My changes generate no new warnings
  • I have added comprehensive error handling for file uploads
  • I have implemented proper data validation and sanitization
  • I have tested the feature with various file sizes and formats
  • I have verified that imported notebooks maintain data integrity
  • I have ensured the feature works across different browsers and devices

Security Considerations​

  • All file uploads use signed URLs with expiration
  • Server-side validation prevents code injection via JSON
  • User isolation ensures no cross-user data access
  • File size limits prevent DoS attacks via large uploads
  • MIME type validation ensures only JSON/ZIP files are processed

Performance Optimizations​

  • Chunked uploads for large files
  • Background processing for bulk imports
  • Progress streaming for real-time user feedback
  • Efficient JSON parsing with memory management
  • Database transactions ensure data consistency