thechart/docs/EXPORT_SYSTEM.md

TheChart Export System Documentation

Overview

The TheChart application now includes a comprehensive data export system that allows users to export their medication tracking data and visualizations to multiple formats:

• JSON - Structured data format with metadata
• XML - Hierarchical data format
• PDF - Formatted report with optional graph visualization

Features

Export Formats

JSON Export

• Exports all CSV data to structured JSON format
• Includes metadata about the export (date, total entries, date range)
• Lists all pathologies and medicines being tracked
• Data is exported as an array of entry objects

XML Export

• Exports data to hierarchical XML format
• Includes comprehensive metadata section
• All entries are properly structured with XML tags
• Column names are sanitized for valid XML element names

PDF Export

• Creates a formatted report document
• Includes export metadata and summary information
• Optional graph visualization inclusion
• Data table with all entries
• Proper pagination and styling
• Notes are truncated for better table formatting

User Interface

The export functionality is accessible through:

1. File Menu - "Export Data..." option in the main menu bar
2. Export Window - Modal dialog with export options
3. Format Selection - Radio buttons for JSON, XML, or PDF
4. Graph Option - Checkbox to include graph in PDF exports
5. File Dialog - Standard save dialog for choosing export location

Export Manager Architecture

The export system consists of three main components:

ExportManager Class (src/export_manager.py)

• Core export functionality
• Handles data transformation and file generation
• Integrates with existing data and graph managers
• Supports all three export formats

ExportWindow Class (src/export_window.py)

• GUI interface for export operations
• Modal dialog with export options
• File save dialog integration
• Progress feedback and error handling

Integration in MedTrackerApp (src/main.py)

• Export manager initialization
• Menu integration
• Seamless integration with existing managers

Technical Implementation

Dependencies Added

• reportlab - PDF generation library
• lxml - XML processing (added for future enhancements)
• charset-normalizer - Character encoding support

Data Flow

1. User selects export format and options
2. ExportManager loads data from DataManager
3. Data is transformed according to selected format
4. Graph image is optionally generated for PDF
5. Output file is created and saved
6. User receives success/failure feedback

Error Handling

• Graceful handling of missing data
• File system error management
• User-friendly error messages
• Logging of export operations

Usage Examples

Basic Export Process

1. Open TheChart application
2. Go to File → Export Data...
3. Select desired format (JSON/XML/PDF)
4. For PDF: choose whether to include graph
5. Click "Export..." button
6. Choose save location and filename
7. Confirm successful export

Export File Examples

JSON Structure

{
  "metadata": {
    "export_date": "2025-08-02T09:03:22.580489",
    "total_entries": 32,
    "date_range": {
      "start": "07/02/2025",
      "end": "08/02/2025"
    },
    "pathologies": ["depression", "anxiety", "sleep", "appetite"],
    "medicines": ["bupropion", "hydroxyzine", "gabapentin", "propranolol", "quetiapine"]
  },
  "entries": [
    {
      "date": "07/02/2025",
      "depression": 8,
      "anxiety": 5,
      "sleep": 3,
      "appetite": 1,
      "bupropion": 0,
      "bupropion_doses": "",
      "note": "Starting medication tracking"
    }
  ]
}

XML Structure

<?xml version="1.0" encoding="UTF-8"?>
<thechart_data>
  <metadata>
    <export_date>2025-08-02T09:03:22.613013</export_date>
    <total_entries>32</total_entries>
    <date_range>
      <start>07/02/2025</start>
      <end>08/02/2025</end>
    </date_range>
  </metadata>
  <entries>
    <entry>
      <date>07/02/2025</date>
      <depression>8</depression>
      <anxiety>5</anxiety>
      <note>Starting medication tracking</note>
    </entry>
  </entries>
</thechart_data>

Testing

Automated Tests

• Export functionality is tested through simple_export_test.py
• Creates sample exports in all three formats
• Validates file creation and basic content structure

Manual Testing

• GUI testing available through test_export_gui.py
• Opens export window for interactive testing
• Allows testing of all user interface components

Test Files Location

Exported test files are created in the test_exports/ directory:

• export.json - JSON format export
• export.xml - XML format export
• export.csv - CSV format copy
• test_export.pdf - PDF format with graph

File Locations

Source Files

• src/export_manager.py - Core export functionality
• src/export_window.py - GUI export interface

Test Files

• simple_export_test.py - Basic export functionality test
• test_export_gui.py - GUI testing interface
• scripts/test_export_functionality.py - Comprehensive export tests

Dependencies

• Added to requirements.txt and managed by uv
• PDF generation requires reportlab
• XML processing enhanced with lxml

Future Enhancements

Potential improvements for the export system:

1. Additional Formats - Excel, CSV with formatting
2. Export Filtering - Date range selection, specific pathologies/medicines
3. Batch Exports - Multiple formats at once
4. Email Integration - Direct email export
5. Cloud Storage - Export to cloud services
6. Export Scheduling - Automated periodic exports
7. Advanced PDF Styling - Charts, graphs, custom layouts

Troubleshooting

Common Issues

1. No Data to Export - Ensure CSV file has entries before exporting
2. PDF Generation Fails - Check ReportLab installation and permissions
3. File Save Errors - Verify write permissions to selected directory
4. Large File Exports - PDF exports may take longer for large datasets

Debugging

• Check application logs for detailed error messages
• Export operations are logged with DEBUG level information
• File system errors are captured and reported to user

Integration Notes

The export system integrates seamlessly with existing TheChart functionality:

• Uses same data validation and loading mechanisms
• Respects existing pathology and medicine configurations
• Maintains data integrity and formatting consistency
• Follows existing logging and error handling patterns