Study/docs/V2-COMPARISON.md
Elijah ccdad9728b
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
Add drag reordering, exam deadlines, frozen shared quizzes, batched OCR and semantic search
- Drag-to-reorder for class materials, folders, quiz questions and deck cards. Pointer-based
  so touch works, plus keyboard (arrows/Home/End) with screen-reader announcements.
- Timed exams get a wall-clock deadline. The server refuses late answers, submits overdue
  exams with what was saved, and the countdown keeps running while the page is closed.
- Shared quiz sessions keep a frozen copy of their questions and flag later owner edits.
- Scanned PDFs are read in cached 8-page batches with real page numbers (pdf-lib), removing
  the 30 MB whole-file limit. Compatible providers now receive PDFs as file parts.
- Semantic search: embeddings for OpenAI, Gemini, Ollama and compatible servers, background
  indexing into chunk_vectors (migration 2), hybrid keyword + vector ranking for search, the
  assistant and focused generation, and a Settings -> AI section.

181 tests pass locally and in the Docker test stage on Node 24.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:48:20 -07:00

94 lines
6.6 KiB
Markdown

# V2 versus V1 and the rebuild brief
Source review on 2026-11-11, comparing `main` V1 at 7bd0a9a with local V2.
This distinguishes implementation from verification. Passing mocked AI tests does not
establish real-provider compatibility, and sampled desktop/mobile QA is not exhaustive.
## Original requirements
| Area | Current state |
| --- | --- |
| New architecture and UI | Rebuilt: React/Vite, Hono, built-in SQLite; distinct responsive light/dark design |
| Single administrator and public visitors | Implemented: secure local login, revocable links, isolated visitor progress |
| Classes and organization | Classes/folders, edit/move/search/delete, quiz/deck duplication, drag-to-reorder (mouse, touch, keyboard) for materials, folders, questions and cards |
| Quizzes | MC/SATA, per-option explanations, question rationale, partial credit, practice/exam, shuffle, resume, missed review and history implemented |
| Flashcards | Decks, browse/self-assessment, persistent FSRS, reviews, undo and class/deck scoping implemented |
| Imports/templates/export | Preview/validation/editing, JSON/text bulk input, reusable templates and exports implemented |
| Documents | Required common formats, extraction/chunks/FTS search, optional provider OCR, private storage and AI generation implemented |
| AI providers and models | Five adapters, encrypted keys, discovery/manual models, routing/settings/usage; live provider verification remains |
| Integrated AI actions | Search/read content, weak-area generation, editable drafts, confirmed modifications implemented |
| ChatGPT account | No configured account OAuth. Hosted-client eligibility/approval remains unresolved; conventional API access is available |
| Docker/persistence/backups | Single-container image now builds and passes disposable runtime checks; Unraid proxy/volume validation remains |
| Accessibility and polish | Keyboard shortcuts, focus styles, reduced-motion rules, responsive layouts and state components exist; full keyboard/screen-reader audit remains |
The nursing-specific AI features are prompt-based tools using the same single/multi-choice
question engine. Dedicated interactive case-study/NGN question types and an adaptive NCLEX
exam engine are not implemented; the brief listed additional types as optional.
## V1 features that are not equivalent in V2
- **Named spaced-repetition sets:** V1 could collect selected decks into named sets with
independent schedules and new-card limits. V2 schedules each card once, with a global
daily new-card limit and deck/class/all review scopes. A practical simplification, but
it cannot reproduce separate course/exam review sets or independent per-set schedules.
- **Manual material order:** restored on 2026-11-12. The class page's default "Your order"
sort shows grip handles: drag (mouse or touch) or use arrow keys/Home/End on a handle to
reorder quizzes, decks, documents and notes within their group, and to reorder folders.
Quiz questions and deck cards are reorderable the same way.
- **Migration fidelity:** V2 imports source content, completed attempts and one selected
schedule per card. V1 interrupted StudyProgress sessions, named sets and their independent
schedules are not recreated. Historical reviewSnapshotJson is not consumed: imported
attempts reconstruct questions from current source content rather than preserving every
historical question version. Existing V1 share links are deliberately not reused.
These are not all mandatory requirements in the rebuild brief, but they matter when replacing
a V1 workflow. Extra visual effects should not obscure these functional tradeoffs.
## Issues found and addressed in this pass
- Card entrance utility overrode swipe-away CSS. Entrance and exit classes are now mutually
exclusive, restoring the intended grading transition.
- Added horizontal touch-to-grade after revealing a flashcard, while retaining vertical
scrolling. Browse uses learning/known; FSRS uses Again/Good. Desktop buttons/keys remain.
- Shuffle now rearranges only remaining cards, retaining completed cards and assessments.
Browser check confirmed the session stays at card 2/4 and 25% after shuffling.
- Review now remounts when its query scope changes, avoiding a stale deck queue when selecting
global Review from a scoped review screen.
- Note saves are serialized; navigation/read-mode waits for a successful save, and unsaved
changes trigger the browser's unload protection. Verified editing then immediately
navigating away and reopening retains the latest text.
## Rationale check requested by the owner
Created an isolated three-question quiz with a separate explanation on every option plus
each question's overall rationale. Through the actual internal browser, verified a correct
single-choice answer, an incorrect single-choice answer and partially correct SATA answer.
Practice reveals each option's explanation **under that option**, including unselected
distractors and missed correct options. The overall rationale follows that question's choices.
Results retain the same per-option/per-question grouping. Exam mode intentionally delays
feedback until submission. The stored option explanation field is `why`; a legacy import
with only a question-level rationale cannot invent separate option explanations.
Screenshot: ignored local `.test-data/rationale-check/correct-inline.png`.
## Remaining usability/feature priorities
Done on 2026-11-12: drag-to-reorder; wall-clock exam deadlines enforced by the server
(answers after the deadline plus a 5 s grace are refused and overdue exams are submitted with
what was saved, even if nobody reopens them); frozen shared-quiz sessions (a visitor's session
keeps the questions as they were at the start and notes later edits); batched, cached OCR for
long scanned PDFs; semantic (embedding) search merged with keyword search.
1. Restore selected-deck named review collections if replacing that V1 workflow is important.
2. Better import reporting/preservation for V1 history and interrupted sessions.
3. Scanned PDFs need a vision model that accepts PDFs; vision-only models (e.g. most Ollama
vision models) cannot read scanned PDFs yet because pages are not rendered to images.
4. Semantic search covers document passages; questions, cards and notes are keyword-only.
5. Full offline private studying, rich-text WYSIWYG authoring, study-plan generation and
additional case/question types remain optional future enhancements.
No obvious missing basic flip/streak/quiz-answer feedback remains by source review. Visual
polish still needs targeted long-content/mobile/empty/error-state passes beyond the sampled
screens already checked. Prioritize those user-visible improvements over expanding a test
count for its own sake.