# Recall — Medical MCQ Trainer

This reusable app runs locally, without an account or runtime dependencies. Question banks and progress are separate IndexedDB stores. Demo items are generated software-testing examples, not extracted exams or predictions. The v4 generation engine and past-exam sources were not used to generate this demo.

## Windows: first start

1. Extract the ZIP into a permanent folder.
2. Install Node.js LTS if it is not already installed.
3. Double-click START-WINDOWS.cmd. Keep its window open during initial setup.
4. Open http://localhost:8765 in Chrome or Edge. Always use this exact address and the same browser profile. Other ports, addresses, browsers and profiles have separate databases.
5. Open Banks & backups and load the demonstration bank, or import JSON files.
6. Wait for “Offline shell ready.” Reload once to verify the installed service worker controls the page. The cached shell can subsequently load without the server; keep the launcher for reliable startup. You can use the browser's install shortcut when offered.

Do not open index.html directly with file://. No npm install is needed. Optional source checks: `npm test`.

## Android

The same app needs a secure origin on Android. A Windows localhost address is not your phone's localhost. This server deliberately binds only to the Windows loopback interface; it does not expose study files to the network.

Option 1: place the static app files (index.html, JS, CSS, manifest, icon, demo JSON and README) on an HTTPS static host you control. Open that HTTPS address in Android Chrome, wait for offline readiness, reload, then choose Add to home screen / Install if available. Initial hosting/deployment is not included. No server database or account is needed for studying, but the host can receive normal page requests.

Option 2: use a trusted Android local web-server app to serve the extracted folder at a fixed localhost URL. Open that address in Chrome. The server must serve JS with the correct MIME type. Installation prompts vary by browser. Cache support does not guarantee an installation prompt.

Once initially loaded and cached, questions and progress stay on that device and studying works offline. To transfer devices: download complete backup, transfer the JSON, open Banks & backups on the target, and restore. Export a backup on each device before merging. Android installation and device restart are not verified on physical hardware in this package.

## Practice and review

Choose filters and Start new session. Every submission is saved before advancing. Navigation, option order, completed answers and session position are saved. Resume selects the latest unfinished session; Dashboard lists saved sessions. Revisiting a submitted item reveals its saved answer; start a new session to retry. Flags are independent of attempts. Incorrect means the latest answer was wrong; Previously correct means at least one correct attempt; Incorrect 2+ times counts lifetime errors. No spaced-repetition scheduler is implemented.

## Bank contract

See question-bank.schema.json and demo-bank.json. Import accepts a bank object or an array of banks; multiple files work too. Version 1 banks require a positive revision. Stable identity is the pair (bankId, question.id), encoded as a JSON array string internally. Same item ID in different banks is allowed. Duplicate IDs inside one bank are rejected. Never change IDs for wording-only revisions. Never reuse an ID for a different concept.

Revise existing content by increasing bank revision. Changed banks with an equal/lower revision are rejected. An update needs confirmation. Omitted questions are deliberately retained to protect progress and unfinished sessions; there is no destructive delete UI. Export includes retained questions. Reimporting an exported bank may require incrementing its revision if its retained content differs from the originally imported bank. All selected files validate before any writes. Database writes for each import are atomic. Keep only one trainer tab open while importing or restoring to avoid competing content updates.

sourceType: generated, authentic, recalled, reconstructed, disputed. Non-generated items require source.reference. examYear must be null unless a non-generated item's year is verified, yearVerified:true, with a source reference. This validates metadata shape, not the historical truth of a claim. Difficulty A/B/C is provided by the bank author. Use the project's v4 engine for future generation, supply stable IDs and this schema, and generate JSON only. Do not invent sources or exam years.

## Backup and integrity

Export all banks produces an importable array. Export progress includes attempts, flags and sessions but no bank definitions; import the banks separately on the target device. Complete backup includes all five stores. Restore is an atomic merge, never a wipe. Identical attempts deduplicate by ID. A conflicting attempt ID aborts the whole restore. Newer timestamps win for flags and sessions; equal timestamps keep local data. Existing question and bank records remain local during restore. Use explicit higher-revision bank imports to resolve content differences. New records are merged. Device clocks should be accurate. Attempts contain original question snapshots, answer indexes and correctness so question updates do not rewrite earlier grades. Historical correctness is retained, including if an old answer key is later corrected.

Use complete backups regularly and before device/browser changes. IndexedDB is persistent browser storage, not guaranteed permanent storage: private mode, clearing site data, profile loss or eviction may delete it. Request persistent storage improves eviction protection when granted, but does not protect against manual deletion. Failed transactions show an error; they do not report success. The app does not silently fall back to temporary memory.

Statistics distinguish attempt accuracy from latest-answer accuracy across unique attempted questions. Dashboard activity is grouped by UTC day; recent history uses local display time. Daily accuracy is descriptive; different question difficulty can affect it. No claim of measured learning gain is made.

## Optional future synchronization

No cloud backend, login, synchronization queue or automatic cross-device sync is implemented. The database is organized into banks, questions, immutable attempts, timestamped flags and sessions. A future provider can synchronize these stores, deduplicate attempts by UUID and use explicit revision conflicts for content; it must add authenticated access controls and a durable outbox. Manual backup merge is implemented now.

## Maintenance

App shell files are cached under recall-shell-v1. For a future release, change the cache version in sw.js. Do not rename the IndexedDB database or change the origin when upgrading. Browser database schema migrations must use indexedDB version upgrades. There are no external fonts, trackers, scripts or CDN requirements. Imported strings render as text, never HTML. Large banks are supported functionally, but summaries currently scan in memory; very large histories may slow the dashboard. Test performance before using tens of thousands of items. Keep backup JSON private because it includes your full study history.

## Release 1.1.0: safer startup and updates

Use START-WINDOWS.cmd. It checks the /health endpoint before opening the browser, reuses a healthy running Recall server, and reports an unresponsive/occupied port without stopping unrelated processes. DIAGNOSE-WINDOWS.cmd prints connection checks without changing settings. This does not guarantee that Windows loopback restrictions are fixed.

Always keep http://localhost:8765 and the same browser profile. If you previously studied at http://127.0.0.1:8765, export your complete backup there and restore it at localhost. The two addresses have separate storage.

For future Windows releases: export a complete backup, close every Recall tab and server, then double-click UPDATE-WINDOWS.cmd. Type UPDATE and paste the downloaded release ZIP path. It validates the release identity, required files and JavaScript syntax before replacing application files, saves old files in a rollback folder, and attempts to restore them if copying fails. It does not modify IndexedDB. Keep a backup anyway. This is a local ZIP updater, not an automatic internet download service. Only use trusted release ZIPs: syntax validation does not establish publisher authenticity. Do not interrupt the updater or shut down during file copying. Old 1.0 ZIPs do not contain the required updater files and will be rejected.

Android and hosted Windows use: a stable HTTPS deployment is still required for convenient installation and remote updates. This package does not deploy a host or configure cloud synchronization. After a hosted release is published, the service worker can download its new offline shell. Close ALL app tabs/windows and reopen to activate the waiting version; updates do not force reload during an answer. Offline devices keep their cached version until connected. Publish complete releases together and change the cache version each release. Never change the hosting origin if you want existing storage to remain accessible.

Questions are already filterable by Subject and Lecture. Import separate banks with consistent subject names, e.g. Physiology, Anatomy, Histology, Pharmacology, Pathology, Microbiology, Parasitology.