2026-03-16 Session Log

lingua-rag

Marathon build day — built the entire vocabulary page, rewrote it twice, organized 9 sessions of uncommitted work into 7 clean commits, and consolidated the project roadmap.

What got done

Vocabulary page — built, polished, then rewritten

The biggest chunk of today was building a standalone /vocabulary page from scratch and iterating on it three times:

1. Initial build — notebook-style table with cream background, red margin line, stone palette. Language grouping with section headers, search/filter/sort controls, Google network TTS per entry via shared pickBestVoice. Backend list_all_for_user query with PDF name JOIN.

2. Feature-rich polish — server-persisted check_count (0→3 sequential clicks with optimistic UI + rollback), delete with confirmation modal (removes both vocab entry and PDF highlight), inline meaning editing, per-language independent pagination (each language table has its own 10/20/50 selector stored in localStorage), smart page adjustment when deleting empties the last page.

3. Code review fixes — centered the loading spinner (absolute inset-0 instead of h-full), fixed stale closures in handleDelete using refs (pagesRef, pageSizesRef, groupedByLangRef), added voiceschanged event listener cleanup, made search/filter reset page number only (not pageSize).

4. Server-side pagination rewrite — after all the client-side work, manually rewrote to use fetchVocabularyPage with offset/limit params, debounced search (300ms), and a single flat table with showLangColumn prop. Backend endpoint still needs to be built.

NoteSlidePanel redesign

Converted the notes panel from a plain list to sticky-note cards (yellow #fef9c3 background with shadows), page-based grouping with p.N separators, 2-column vocab table (Word / Definition), icon-based hover actions (pencil/trash), and auto-resize textarea for editing.

PageViewer → floating modal

Transformed from a full-screen overlay into a draggable floating modal with bottom-right resize handle. Users can now see the PDF while writing notes (“textbook + notebook” workflow). Added an edit guard system — all close paths go through requestClosePageViewer() with a confirm dialog when content is being edited. Ref-based drag/resize for zero React re-renders during interaction.

41 backend integration tests

Built test infrastructure from scratch with conftest.py shared fixtures: mock_pool (dual-patch for app.db.connection + app.db.repositories), auth_override, and TestClient factories. Five test files covering:

• test_build_messages_multimodal.py (8 tests) — page images, text context
• test_conversations_router.py (10 tests) — CRUD, auth, 403/401
• test_pdfs_router.py (13 tests) — rename, language, bookmark, delete
• test_tree_router.py (7 tests) — sidebar tree GET/PUT, validation
• test_health.py (3 tests) — healthy, degraded DB, version

ShellLayout decomposition (1405 → 684 LOC)

Extracted ShellModals.tsx (7 modal components, 462 LOC) and SidebarPdfItem.tsx (315 LOC). Each modal manages its own draft state internally.

Prompt English unification

Rewrote all prompts in prompts.py from Korean to English for optimal Claude performance. Output language is now controlled via learner_language parameter ("Respond in {learner_language}"). Added PROMPT_VERSION = "2.0" tracking.

Cross-page PDF fixes (from previous session, committed today)

Fixed drag highlights not rendering across pages (added selectionPage state tracking), note/vocab page number accuracy (popup.page field), empty area drag popup prevention, and removed the entire pin/sticky annotation system (~280 LOC) that was fully replaced by highlight notes.

Guest → login stability (from previous session, committed today)

Fixed chat history loss with a 5-layer defense: prevIsGuestRef skip premature fetch, always fire chatResetKey, cache: no-store, processMessage guard, and backend retry. Fixed index status stuck at yellow by removing user_id filter from _set_status(). Parallelized claim API with asyncio.gather, deferred storage move to background tasks.

Persistent vocab highlights on PDF (from previous session, committed today)

Added red highlights for saved vocabulary words on PDF pages. Unified highlight rendering for notes (yellow) and vocab (red). Built a hover tooltip system — icon appears above highlight on hover, click shows popover with content. Debounced group transitions prevent flicker.

Infrastructure & DX

• Enabled reactStrictMode: true in Next.js, fixed InputBar setTimeout cleanup
• Added Sonner toast notifications for 5 user-facing action failures
• Custom 404/500 error pages
• Removed duplicate pdfjs-dist (direct dep conflicted with react-pdf’s bundled version)
• Sidebar tree backend persistence (sidebar_tree table, server sync on login)

Project management

Organized 36 modified/new files across 9 sessions into 7 logical commits by topic. Consolidated the mid-project evaluation plan into docs/todo.md as the single source of truth — collapsed completed Phase 1-7 into expandable sections, added Quality Phase 1-4 roadmap with checkbox tracking.

Key decisions

• check_count integer over boolean array — 0-3 integer in DB simplifies sequential click logic
• Server-side pagination for vocabulary — client-side grouping won’t scale; offset/limit API is the right call
• Floating modal over full-screen replacement — enables “textbook + notebook” side-by-side workflow
• Patch where it’s used, not where it’s defined — conftest.py must dual-patch get_pool at both import sites
• PdfViewer decomposition deferred — 3530 LOC with 30+ useState hooks; too high-risk for mechanical extraction in one session
• docs/todo.md as canonical tracker — plan file kept for reference only

What’s next

• Build backend endpoint for paginated vocabulary (offset/limit/search/language/sort_by)
• Implement fetchVocabularyPage + VocabPageParams in frontend
• Frontend API proxy route for paginated vocabulary
• Phase 3A: Onboarding — first-visit guided flow, sample PDF, feature discovery tooltips
• Phase 3B remaining: Anki CSV export, context sentence capture
• PdfViewer decomposition (dedicated session needed)