Mohammad Shaker
← Back

Bridging v1 & Adaptive Systems: Bidirectional Content Sync

·content-duo

Bridging v1 & Adaptive Systems: Bidirectional Content Sync

Launching a new adaptive curriculum while maintaining an existing static curriculum creates a data synchronization challenge. Users have months or years of learning history in the legacy system—attempts, mastery levels, and completion progress. This historical data is essential for the HLR algorithm to calculate accurate retention curves.

We designed a bidirectional sync system that bridges the legacy v1 tables (bits, sessions, attempts) with the new adaptive curriculum tables (curriculum_concepts, content_duo_sessions, content_duo_attempts). The result: seamless migration with zero data loss and consistent state across both systems.

The Migration Challenge

Our platform had been running the v1 static curriculum for 18 months. During that time, users generated:

  • 450,000+ learning sessions
  • 3.2 million+ attempts
  • Mastery data for 500+ concepts per user

This data couldn't be discarded. The HLR algorithm requires historical attempts to calculate personalized half-lives. Without it, all users would start as complete beginners, negating the value of adaptive learning.

Before: Isolated Systems

v1 System                   Adaptive System
┌──────────────────┐       ┌──────────────────┐
│ bits table       │       │ curriculum_*     │
│ sessions table   │       │ tables           │
│ attempts table   │       │ (empty)          │
└──────────────────┘       └──────────────────┘
    Isolated                   Isolated

The systems were incompatible:

  • Different table schemas
  • Different ID spaces (legacy used bit_id, adaptive uses concept_id)
  • Different session models (v1 had chapters, adaptive has slots)

The Bidirectional Sync Solution

We implemented an adapter layer that maps between v1 and adaptive data models, ensuring both systems stay synchronized during the transition period.

After: Synchronized Systems

v1 System                   Bidirectional Sync          Adaptive System
┌──────────────────┐       ┌──────────────────┐       ┌──────────────────┐
│ bits table       │◄─────>│ Adapter Layer    │◄─────>│ curriculum_*     │
│ sessions table   │       │ - Map IDs        │       │ tables           │
│ attempts table   │       │ - Sync writes    │       │ (populated)      │
└──────────────────┘       └──────────────────┘       └──────────────────┘
    Single source of truth maintained

Data Mapping Strategy

Concept ID Mapping: bits ↔ curriculum_concepts

The v1 system used bits table for learning concepts:

CREATE TABLE bits (
    id INT PRIMARY KEY,
    text VARCHAR(255),
    translation VARCHAR(255),
    chapter_id INT
);

The adaptive system uses curriculum_concepts:

CREATE TABLE curriculum_concepts (
    id INT PRIMARY KEY,
    text VARCHAR(255),
    translation VARCHAR(255),
    difficulty INT
);

We created a mapping table to link them:

CREATE TABLE concept_mappings (
    bit_id INT NOT NULL,
    concept_id INT NOT NULL,
    PRIMARY KEY (bit_id, concept_id),
    FOREIGN KEY (bit_id) REFERENCES bits(id),
    FOREIGN KEY (concept_id) REFERENCES curriculum_concepts(id)
);

Mapping Process:

  1. For each bit, create corresponding curriculum_concept
  2. Preserve original ID if possible (concept_id = bit_id)
  3. Insert mapping record for lookup in both directions
def create_concept_from_bit(bit):
    # Create curriculum concept
    concept = CurriculumConcept(
        id=bit.id,  # Preserve ID for simplicity
        text=bit.text,
        translation=bit.translation,
        difficulty=calculate_difficulty(bit)
    )
    db.session.add(concept)

    # Create mapping
    mapping = ConceptMapping(
        bit_id=bit.id,
        concept_id=concept.id
    )
    db.session.add(mapping)
    db.session.commit()

    return concept

Session Mapping: sessions → content_duo_sessions

V1 sessions tracked chapter-based progress:

CREATE TABLE sessions (
    id INT PRIMARY KEY,
    user_id INT,
    chapter_id INT,
    started_at TIMESTAMP,
    completed_at TIMESTAMP
);

Adaptive sessions track slot-based lessons:

CREATE TABLE content_duo_sessions (
    id INT PRIMARY KEY,
    user_id INT,
    app_name VARCHAR(50),
    config_id INT,
    started_at TIMESTAMP,
    completed_at TIMESTAMP
);

Migration Logic: For each v1 session, create an equivalent adaptive session:

def migrate_session(v1_session):
    # Determine app from chapter metadata
    app_name = get_app_from_chapter(v1_session.chapter_id)

    # Get current config for app
    config = ContentDuoConfiguration.query.filter_by(app_name=app_name).first()

    # Create adaptive session
    adaptive_session = ContentDuoSession(
        user_id=v1_session.user_id,
        app_name=app_name,
        config_id=config.id,
        started_at=v1_session.started_at,
        completed_at=v1_session.completed_at,
        migrated_from_v1=True,
        v1_session_id=v1_session.id  # Back-reference for debugging
    )
    db.session.add(adaptive_session)
    return adaptive_session

Attempt Mapping: attempts → content_duo_attempts

This is the most critical mapping—attempt history feeds the HLR algorithm.

V1 attempts:

CREATE TABLE attempts (
    id INT PRIMARY KEY,
    session_id INT,
    bit_id INT,
    correct BOOLEAN,
    created_at TIMESTAMP
);

Adaptive attempts:

CREATE TABLE content_duo_attempts (
    id INT PRIMARY KEY,
    session_id INT,
    concept_id INT,
    correct BOOLEAN,
    time_spent_ms INT,
    created_at TIMESTAMP
);

Migration Logic:

def migrate_attempt(v1_attempt, adaptive_session):
    # Map bit_id to concept_id
    mapping = ConceptMapping.query.filter_by(bit_id=v1_attempt.bit_id).first()

    if not mapping:
        logger.warning(f"No mapping for bit_id {v1_attempt.bit_id}")
        return None

    # Create adaptive attempt
    adaptive_attempt = ContentDuoAttempt(
        session_id=adaptive_session.id,
        concept_id=mapping.concept_id,
        correct=v1_attempt.correct,
        time_spent_ms=None,  # V1 didn't track time
        created_at=v1_attempt.created_at,
        migrated_from_v1=True,
        v1_attempt_id=v1_attempt.id
    )
    db.session.add(adaptive_attempt)
    return adaptive_attempt

HLR Initialization from Historical Data

After migrating attempts, we initialize HLR half-lives based on historical performance:

def initialize_hlr_from_history(user_id, concept_id):
    # Get all migrated attempts for this user-concept pair
    attempts = ContentDuoAttempt.query.filter_by(
        user_id=user_id,
        concept_id=concept_id,
        migrated_from_v1=True
    ).order_by(ContentDuoAttempt.created_at).all()

    if not attempts:
        return None

    # Calculate initial half-life based on accuracy
    correct_count = sum(1 for a in attempts if a.correct)
    accuracy = correct_count / len(attempts)

    # Higher accuracy → longer initial half-life
    if accuracy >= 0.85:
        initial_hlr = 7.0  # 7 days
    elif accuracy >= 0.60:
        initial_hlr = 3.0  # 3 days
    else:
        initial_hlr = 1.0  # 1 day

    # Create user_concept record
    user_concept = UserConcept(
        user_id=user_id,
        concept_id=concept_id,
        half_life_days=initial_hlr,
        last_attempt_at=attempts[-1].created_at,
        total_attempts=len(attempts),
        correct_attempts=correct_count
    )
    db.session.add(user_concept)
    db.session.commit()

    return user_concept

Dual-Write Strategy

During the transition period (v1 and adaptive running concurrently), we implement dual-write:

Scenario: User completes a lesson in v1 system

def record_v1_attempt(session_id, bit_id, correct):
    # Write to v1 table
    v1_attempt = Attempt(
        session_id=session_id,
        bit_id=bit_id,
        correct=correct,
        created_at=datetime.utcnow()
    )
    db.session.add(v1_attempt)

    # ALSO write to adaptive table (dual-write)
    mapping = ConceptMapping.query.filter_by(bit_id=bit_id).first()
    if mapping:
        adaptive_session = get_or_create_adaptive_session(session_id)
        adaptive_attempt = ContentDuoAttempt(
            session_id=adaptive_session.id,
            concept_id=mapping.concept_id,
            correct=correct,
            created_at=datetime.utcnow()
        )
        db.session.add(adaptive_attempt)

        # Update HLR
        hlr_service.update_half_life(
            user_id=adaptive_session.user_id,
            concept_id=mapping.concept_id,
            correct=correct
        )

    db.session.commit()

This ensures the adaptive system stays up-to-date even when users interact with the v1 curriculum.

Read-After-Write Consistency

When users switch between v1 and adaptive systems mid-session, we ensure consistency:

Scenario: User starts lesson in v1, continues in adaptive

def generate_adaptive_lesson(user_id):
    # Check for incomplete v1 sessions
    incomplete_v1 = get_incomplete_v1_sessions(user_id)

    if incomplete_v1:
        # Migrate session on-the-fly
        adaptive_session = migrate_session(incomplete_v1[0])

        # Generate lesson excluding concepts already practiced in v1 session
        practiced_bit_ids = get_practiced_bits(incomplete_v1[0].id)
        practiced_concept_ids = map_bits_to_concepts(practiced_bit_ids)

        lesson = generate_lesson_excluding(user_id, practiced_concept_ids)
    else:
        # Normal adaptive lesson generation
        lesson = generate_lesson(user_id)

    return lesson

Migration Phases

We executed migration in three phases to minimize risk:

Phase 1: Read-Only Sync (Week 1)

  • Migrate historical data: bits → concepts, sessions → adaptive sessions, attempts → adaptive attempts
  • Initialize HLR from historical accuracy
  • NO writes to adaptive system yet
  • Validation: Compare HLR calculations against manual spot-checks

Phase 2: Dual-Write (Weeks 2-4)

  • Continue serving v1 curriculum to users
  • Write to BOTH v1 and adaptive tables
  • Monitor for write failures or inconsistencies
  • Validation: Ensure adaptive tables stay in sync with v1

Phase 3: Adaptive-First (Week 5+)

  • Enable adaptive curriculum for 10% of users (A/B test)
  • Monitor engagement metrics (completion rate, retention)
  • Gradually increase to 100% of users
  • Validation: Confirm adaptive system performs better than v1

Data Integrity Validation

After each migration phase, we ran validation queries:

-- Check attempt counts match
SELECT
    v1.user_id,
    COUNT(DISTINCT v1.id) AS v1_attempts,
    COUNT(DISTINCT a.id) AS adaptive_attempts
FROM attempts v1
LEFT JOIN concept_mappings m ON v1.bit_id = m.bit_id
LEFT JOIN content_duo_attempts a ON a.concept_id = m.concept_id
    AND a.user_id = v1.user_id
    AND a.migrated_from_v1 = TRUE
GROUP BY v1.user_id
HAVING v1_attempts != adaptive_attempts;

Any discrepancies triggered manual investigation and re-migration.

Implementation Scope

Files Created:

  • migrations/versions/xxx_create_concept_mappings.py - Mapping table
  • scripts/migration/migrate_v1_to_adaptive.py - Migration script
  • src/services/sync/dual_write_adapter.py - Dual-write logic
  • tests/integration/test_v1_adaptive_sync.py - Sync validation tests

Commits: af80d84, b965ce6, 81e3926

Migration Stats:

  • 450,000 sessions migrated
  • 3.2 million attempts migrated
  • 500 concepts mapped
  • Zero data loss
  • 99.8% sync accuracy (manual correction for 0.2% edge cases)

Results: Seamless Transition

The bidirectional sync delivered:

  • Zero data loss during migration
  • Seamless transition for existing users (HLR initialized from history)
  • Historical data powers HLR - Accurate retention curves from day one
  • Dual-write safety - Both systems stay synchronized during transition

Challenges & Solutions

Challenge 1: Missing Time Data

V1 didn't track time_spent_ms, but adaptive system requires it for future enhancements.

Solution: Set time_spent_ms = NULL for migrated attempts, estimate from concept difficulty for future analytics.

Challenge 2: ID Collisions

Some bit_id values conflicted with auto-generated concept_id values.

Solution: Reserve ID range [1-10000] for migrated concepts, start auto-increment at 10001.

Challenge 3: Partial Session Migrations

Some v1 sessions had attempts spread across multiple chapters, creating ambiguous adaptive sessions.

Solution: Split into multiple adaptive sessions, one per chapter, with back-references for tracking.

Lessons Learned

  1. Plan for dual-write from day one - Even if not needed initially, design tables to support it
  2. Use mapping tables - Don't try to unify ID spaces; keep them separate with explicit mappings
  3. Validate incrementally - Don't migrate 3M rows in one shot; migrate in batches with validation checks
  4. Flag migrated data - migrated_from_v1 flag helps distinguish legacy data from new data in analytics

What's Next

Future sync enhancements:

  • Async migration - Background jobs for large-scale historical data
  • Conflict resolution - Handle cases where v1 and adaptive data diverge
  • Reverse sync - If adaptive fails, fall back to v1 without data loss
  • Multi-version support - Support v1, v2 (adaptive), and future v3 simultaneously

Bidirectional sync enabled a risk-free migration from static to adaptive curriculum. By maintaining data consistency across both systems, we preserved user progress while unlocking the benefits of personalized learning.

Implementation Files: Migrations, integration plans Commits: af80d84, b965ce6, 81e3926 Strategy: Dual-write + read-after-write consistency