GOAL.md

Journal Domain Migration Strategy from Isar to cbl_flutter with References and Action Plan

Problem Statement: The journal domain currently uses Isar for local data persistence, querying, and syncing with a remote server. The goal is to migrate this local storage to Couchbase Lite (cbl_flutter) while maintaining app functionality, data integrity, and syncing capabilities.

References:

1. Data Models and Persistence:

   • lib/infrastructure/database/isar_collections/journal_entry.dart: Isar schema defining JournalEntry and embedded objects.
   • lib/infrastructure/repositories/journal_entry_repository.dart: Repository managing Isar JournalEntry CRUD operations.
   • lib/infrastructure/repositories/journal_entry_repository_helpers.dart: Conversion helpers between Isar JournalEntry and domain JournalEntryEntity.

2. Redux and Sync:

   • lib/domain/redux/journal/journal_sync/journal_sync_saga.dart: Saga handling journal syncing with API and repository.
   • lib/domain/redux/journal/journal_sync/journal_sync_actions.dart: Redux actions for syncing.
   • lib/domain/redux/journal/journal_editor/journal_editor_saga.dart: Sagas for journal editing and media management.
   • lib/domain/redux/journal/list/journal_list_saga.dart: Saga for fetching journal lists.
   • lib/domain/redux/journal/journal_logs/journal_logs_saga.dart: Saga for journal logs.

3. Configuration:

   • lib/config/shared_config.dart: Isar collections registered in openIsar() function, including JournalEntrySchema.

4. API Helper:

   • JournalEntryApiService used in sync saga for server communication.

Action Plan:

1. Data Model Migration:

   • Redefine journal data models as Couchbase Lite documents, preserving nested structure.
   • Rewrite conversion helpers to map between domain entities and Couchbase Lite documents.

2. Repository Refactoring:

   • Replace Isar initialization and queries with cbl_flutter database setup.
   • Refactor repository methods for CRUD operations using Couchbase Lite APIs.
   • Implement transaction and error handling as per Couchbase Lite.

3. Redux and Saga Updates:

   • Update redux sagas to use new repository methods for Couchbase Lite.
   • Maintain existing redux actions and state management.
   • Ensure sagas handle async operations and errors correctly with new database.

4. Configuration and Registration:

   • Replace Isar.open() and collection schema registration with Couchbase Lite database initialization and configuration.
   • Ensure the new database instance is passed to redux store and other dependencies.

5. Data Migration:

   • Develop migration logic to export data from Isar JournalEntry collection and import into Couchbase Lite documents.
   • Ensure data integrity and consistency during migration.
   • Provide fallback or rollback mechanisms.

6. Testing and Validation:

   • Write unit and integration tests for new repository and sagas.
   • Validate data migration correctness.
   • Test end-to-end app functionality and syncing.

7. Deployment and Monitoring:

   • Release updated app with migration.
   • Monitor for sync issues or data inconsistencies.
   • Provide support for migration-related problems.

This strategy focuses on the journal domain as the first step, ensuring a smooth transition from Isar to cbl_flutter while preserving app behavior and data integrity.

Recommended Divide-and-Conquer Strategy for Migrating Journal Domain from Isar to cbl_flutter

Priority List and Breakdown:

1. Setup and Configuration

   • Initialize Couchbase Lite database and configure collections/documents.
   • Ensure database instance is accessible to redux store and repositories.
   • Priority: High (foundation for migration)

2. Data Model and Conversion Helpers

   • Redefine journal data models as Couchbase Lite documents preserving nested structure.
   • Rewrite conversion helpers (fromEntity, toEntity) for Couchbase Lite.
   • Priority: High (enables repository and data migration)

3. Repository Refactoring

   • Refactor JournalEntryRepository to use Couchbase Lite APIs for CRUD.
   • Implement transaction and error handling as per Couchbase Lite.
   • Priority: High (core data access layer)

4. Data Migration Implementation

   • Develop migration logic to export data from Isar and import into Couchbase Lite.
   • Ensure data integrity and consistency.
   • Implement fallback or rollback mechanisms.
   • Priority: Medium (critical but can be done after repo refactor)

5. Redux Saga and State Updates

   • Update redux sagas to use new repository methods.
   • Maintain existing redux actions and state management.
   • Test async operations and error handling.
   • Priority: Medium (dependent on repository readiness)

6. Testing and Validation

   • Write unit and integration tests for new repository and sagas.
   • Validate data migration correctness.
   • Test end-to-end app functionality and syncing.
   • Priority: Medium (ongoing through migration phases)

7. Incremental Rollout and Monitoring

   • Deploy migration in phases if possible.
   • Monitor for sync issues or data inconsistencies.
   • Provide support and hotfixes.
   • Priority: Low (post-migration)

Summary: Start with foundational setup and data model conversion to enable repository refactoring. Then implement data migration followed by redux saga updates. Testing should be continuous. This approach minimizes risk by isolating changes and enabling incremental progress.