feat: implementation of offline-first sync engine poc (#13)

[rohansaini-02]

Summary

Implementation of a standalone Offline-First Sync Engine Proof of Concept (PoC). This module provides a validated architectural pattern for handling data synchronization in low-connectivity environments without polluting the root repository during the initial project scaffolding phase.

Related Issue

Closes #13

Problem Statement

TAP Buddy users (students in government schools) often operate in areas with intermittent 2G/3G connectivity. Direct API calls frequently fail mid-request, leading to data loss in chat interactions and learning progress tracking. A robust mechanism is needed to persist student data locally and sync it reliably when the connection stabilizes.

Changes Made

• Isolated Module Creation: Developed the poc-sync-engine as a standalone TypeScript package to ensure core logic is independently reviewable.
• SyncQueue Implementation: Created a persistent-ready FIFO queue to manage local mutations in a deterministic order.
• SyncManager Development: Built an orchestrator that monitors network state and triggers queue drainage upon restoration of connectivity.
• Resiliency Logic: Integrated an Exponential Backoff retry mechanism (2s, 4s, 8s) to prevent server hammering during reconnection phases.
• Automated Validation: Integrated a full Jest test suite to simulate real-world network failure scenarios.

Technical Decisions

• FIFO Strategy: Chose a strict First-In-First-Out approach for the queue to prevent out-of-order state updates (critical for chat and progression logic).
• Decoupled Architecture: Designed the SyncManager to be agnostic of the underlying storage, allowing for a seamless transition from in-memory arrays (PoC) to WatermelonDB/SQLite (Production) in the next phase.
• Modular Isolation: Kept the implementation in a sub-directory (poc-sync-engine) to allow reviewers to validate the logic without being blocked by the root-level environment setup.

Testing Performed

• Unit Testing: Verified SyncQueue item addition, retrieval, and removal.
• State Transition Testing: Validated that SyncManager correctly pauses/resumes drainage based on mocked network events.
• Network Simulation: Performed 'Jitter Tests' using Jest timers to ensure the Exponential Backoff executes at the correct mathematical intervals.
• Manual Logic Check: Verified the Mermaid diagrams in the module's README.md match the final code implementation.

Results

A fully functional, testable synchronization engine that ensures zero data loss. The logic is currently decoupled and ready to be ported into the main React Native application services layer.

Known Limitations

• Storage Layer: The current PoC uses in-memory persistence.
  Production integration will require WatermelonDB for native SQLite persistence.

Future Work

• Task Serialization: Support for complex binary payloads
  (e.g., offline content bundles, voice recordings).

Checklist

• Code follows project conventions
• Tests pass
• Documentation updated
• Changes are scoped to one problem

[rohansaini-02]

Hi @manua-glitch

When you have a moment, could you please take a look at this PR?

I've implemented it as a standalone module so you can verify the logic quickly with:
cd poc-sync-engine && npm install && npm test

I’d appreciate any feedback or suggestions.