All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 33s
- 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>
94 lines
6.6 KiB
Markdown
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.
|