Skip to content

Commit ec509ce

Browse files
nickmeinholdclaude
andauthored
docs(crdt): mark Phase 5 complete, update roadmap (#41) (#127)
- Mark CRDT sync Phase 5 (sync transport) as complete in architecture doc - Add completed entries for local-first (#40), CRDT sync (#41), narration (#74) in CLAUDE.md - Update Architecture — Next up: remove #40/#41 (done), add Phase 6 Co-authored-by: Claude <noreply@anthropic.com>
1 parent 17a76d2 commit ec509ce

File tree

2 files changed

+14
-8
lines changed

2 files changed

+14
-8
lines changed

CLAUDE.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,9 @@ Current state: App running on macOS. FSRS Phase 1 merged. Knowledge graph animat
111111
-**Curiosity Engine Phase 1** — Gap analysis + prescriptive recommendations (#99): `GapAnalyzer` (4 gap types), `RecommendationService` (Claude-scored gap-filling), `RecommendationEvaluation` (predicted vs actual edges), `KnowledgeGap`/`Recommendation` models, `RecommendationsScreen`, dashboard curiosity card. Parallelized gap evaluation via `Future.wait`. Null-byte delimited edge keys in evaluation to avoid name collisions.
112112
-**Curiosity Engine Phase 2** — One-tap ingest + post-ingest evaluation (#100, #101): `ingestRecommendation()` on `RecommendationNotifier` (fetch→extract→merge→evaluate), `RecommendationIngestStatus`/`RecommendationIngestResult` types, `ingestResults` map on state, `_IngestAction` switch widget (idle/loading/completed/error), `_EvaluationBadge` with color-coded accuracy. `fromJson`/`toJson` on `RecommendationEvaluationResult`. Double-tap guard, `clockProvider` consistency, specific `OutlineApiException`/`ExtractionException` handling.
113113
-**Glow Integration** — See new nodes connect in the graph (#103): `ingestedConceptIds` on `RecommendationIngestResult`, `glowNodeIdsProvider` bridges recommendations→dashboard, `GraphPainter` cyan radial halo (3x radius) + bright ring + blurred edge underlay, 4s `AnimationController` fade on `ForceDirectedGraphWidget` with `onGlowComplete` callback, "View in Graph" button on completed recommendation cards navigates to Dashboard tab with glow.
114+
-**Local-first migration (#40)** — Drift/SQLite schema (#111), `DriftGraphRepository` (#112), `DualWriteGraphRepository` (#113), test migration (#115), dead code removal (#116), UX polish (#117)
115+
-**CRDT sync Phases 1–5 (#41)** — HLC service + node ID (#119), schema v2 with `is_deleted` tombstone + HLC stamping (#121), upsert + orphan tombstoning (#122#123), changeset generation + LWW merge (#124#125), `FirestoreSyncTransport` + `CrdtSyncNotifier` with periodic background sync (#126). Lifecycle wired in `NavigationShell`: immediate sync on init, periodic every 5 min, sync on app resume/pause via `WidgetsBindingObserver`
116+
-**Narration infrastructure (#74)** — Narration models + marker parsing engine (#108), ElevenLabs TTS client + narration script service (#109)
114117

115118
### Curiosity Engine — Next Phases
116119
1. **Evaluation feedback loop** — Feed post-ingest evaluation accuracy back into future recommendation prompts (follows FSRS Phase 4c calibration pattern). Persist evaluation results.
@@ -119,9 +122,8 @@ Current state: App running on macOS. FSRS Phase 1 merged. Knowledge graph animat
119122
4. **Autonomous ingestion** — With user consent, the system finds, fetches, and ingests gap-filling content automatically. The curiosity engine becomes self-feeding.
120123

121124
### Architecture — Next up
122-
1. **#40** — Local-first Drift/SQLite migration (schema should account for FSRS D/S/R fields + curiosity engine state)
123-
2. **#41** — CRDT sync layer (depends on #40; FSRS state needs LWW-Register per field)
124-
3. **#39** — Concept embeddings (#38 done; embedding similarity could predict confusion-based difficulty for FSRS, and improve gap detection by identifying semantically near-miss clusters)
125+
1. **#41 Phase 6** — Firestore optional: personal features work offline with Drift, auth gate becomes optional, sign-in unlocks sync + social
126+
2. **#39** — Concept embeddings (#38 done; embedding similarity could predict confusion-based difficulty for FSRS, and improve gap detection by identifying semantically near-miss clusters)
125127

126128
### Learning Science Features (Issues #74#78)
127129
8. **#74** — Audio/video-synchronized knowledge graph highlighting — nodes light up in sync with narration, connected nodes glow with relationship explanations. Based on Mayer's signaling principle (g=0.38–0.53) and temporal contiguity (d=1.22). Implementation: ElevenLabs TTS with character-level timestamps → concept-to-timerange mapping → `activeConceptsProvider` → existing `glowNodeIdsProvider`. See `docs/FUTURE_DIRECTIONS.md` for full research on AI audio/video tools. Also investigate **Motion Canvas** (https://motioncanvas.io/) for standalone educational video export (3Blue1Brown-style programmatic animation in TypeScript)

docs/CRDT_SYNC_ARCHITECTURE.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -240,11 +240,15 @@ PowerSync provides a complete local-first sync layer for Flutter:
240240
- Row-level LWW (sufficient for single-user multi-device sync; per-field LWW
241241
deferred to social knowledge layer — see `docs/SOCIAL_KNOWLEDGE_PLAN.md`)
242242

243-
### Phase 5: Sync Transport Layer (next)
244-
245-
- Background sync service (push/pull changesets over network)
246-
- Populate `drift_sync_metadata` with per-peer last-synced HLC
247-
- Server-side merge in Firestore (or migrate to Postgres)
243+
### Phase 5: Sync Transport Layer ✅
244+
245+
- `FirestoreSyncTransport`: push/pull changesets via `users/{uid}/sync_log`
246+
- `CrdtSyncNotifier`: orchestrates push → pull → merge cycle with separate
247+
push/pull HLC bookmarks in `drift_sync_metadata`
248+
- `CrdtSyncState` tracks phase, last sync time, row counts
249+
- `startPeriodicSync()` for background sync (default 5 minutes)
250+
- Same-node echo guard (skip own entries on pull)
251+
- `cleanup(beforeHlc:)` for sync_log garbage collection
248252

249253
### Phase 6: Firestore Optional
250254

0 commit comments

Comments
 (0)