# Recall — MCAT Study Studio

Product and engineering blueprint · October 27, 2026

## 1. Product requirements

Recall combines a guided preparation loop with a creative workspace: assess → learn → practice → reflect → retrieve → adjust. The initial commercial audience is individual pre-med students. The first deep content slice is amino acid chemistry; all four MCAT sections have navigation and an original baseline sampler. This prototype is private and is not a paid, launch-ready service.

### Learning principles and product rules

- Retrieval before reveal: ask students to attempt recall before displaying a card answer.
- Feedback explains reasoning, the correct choice, and each distractor. Students label their own errors as content, misreading, or timing.
- Spacing schedules another encounter instead of equating one correct answer with mastery.
- Interleave concepts after initial comprehension. Use multiple question contexts; repeated exposure to one item is not independent evidence of mastery.
- Agency matters: students choose workload, tutoring style, or Sandbox mode. No lost-streak threats, competitive pressure, or inflated readiness claims.
- CARS feedback cites the passage and reasoning skill. A passage about Kant must not require memorized Kant scholarship unless the passage itself supplies it.

### Core requirements and acceptance criteria

| Capability | Expected product behavior | Prototype state |
|---|---|---|
| Baseline | Balanced section coverage, explicit limits, save attempts | Four original items, one per section; workflow sampler only |
| Plan | Test date, weekly capacity, weak-topic priorities, student overrides | Date/countdown and section time allocation; no calendar-level scheduling |
| Tutor | Direct, Socratic, recap; retrieve evidence; cite sources; abstain | Source explorer works; server AI route prepared but not connected |
| Practice | Passages/discretes, explanations, timing, error reflection | Two short passages, two discretes; optional 90-second soft timer |
| Flashcards | Generate/edit/save/review; cloze; spaced intervals | Source-based drafts, manual cards, cloze, SM-2-style schedule |
| Analytics | Section/topic/type accuracy, time, errors, trends | Actual local attempts, including labeled game results; no scaled score |
| Studio | Reusable templates with AI co-creation | Matching game and card workshop; fixed matching content |
| Community | Publish, fork, rate, report, moderate | Private library only; public sharing is deferred |
| Accessibility | Keyboard use, labels, dialogs, readable text | Skip link, labels, dialog focus handling, text/contrast preferences |
| Offline | Cards remain reviewable without a connection | Offline read-only card page after a successful online visit |

Performance targets for beta: interactive navigation under 200 ms on a representative midrange phone; initial compressed application payload below 300 KB excluding optional assets; model response p95 under 20 seconds with cancel/retry states. These are targets, not measured claims.

## 2. System architecture

### Implemented prototype

React with a Next-compatible Vinext server runs on Sites/Cloudflare Workers. Local browser storage holds cards, review states, preferences, and attempts. A service worker falls back to a minimal offline card viewer. The fixed game is ordinary application code; it does not execute generated code. The server route checks identity and request origin, retrieves from four source records, validates generated source IDs, and refuses to operate without server-side AI configuration. Its live provider path is not exercised or approved for production.

### Proposed commercial architecture

```mermaid
flowchart TD
    A[Responsive React application] --> B[Authenticated application API]
    B --> C[Postgres and pgvector]
    B --> D[AI orchestration service]
    D --> C
    D --> E[Model provider]
    B --> F[Private object storage]
    B --> G[Job queue]
    G --> H[Document ingestion and review]
    H --> C
    B --> I[Billing and entitlement service]
```

Use a modular monolith initially: TypeScript API, Postgres with pgvector, private object storage, and a queue. Avoid a separate vector database until volume justifies it. The Sites prototype uses a different deployment runtime; the production Postgres implementation is proposed, not deployed. HTTP-accessible database connections would be required if retaining Workers.

Authentication derives owner identity from a verified session. Every read/write authorizes ownership server-side. Postgres RLS provides a second boundary. Billing webhooks are signed, idempotent, and authoritative for entitlements; frontend success screens never grant access. Public AI must have account quotas, per-user rate limits, request cancellation, budget ceilings, and abuse monitoring before activation.

### Retrieval and evidence pipeline

1. Approve a source, edition, use rights, topic tags, stable locator, and review owner. Public availability does not imply redistribution or commercial embedding rights.
2. Extract text and diagrams; quarantine uploads, check file type and limits, scan for malicious content, and process outside the web request.
3. Chunk by concept; preserve page/section locators and version IDs. Embed approved chunks and index text for hybrid retrieval.
4. Retrieve with section/topic filters and rerank. If coverage is weak or contradictory, ask for clarification or abstain.
5. Generate a structured draft from retrieved records. Treat notes and retrieved documents as data, not instructions. Disallow invented citations and official-content reproduction claims.
6. Validate schema, cited record existence, claim support, chemistry units/charges where applicable, and question answer uniqueness. An LLM verifier is an additional signal, not proof.
7. Show source coverage and review status: “source-supported,” “limited evidence,” or “needs review.” Never present the model’s self-reported percentage as calibrated confidence.
8. Store model/prompt/source versions for reproducibility. Retire or re-review affected outputs when a source changes.

### Data model

The repository includes `docs/schema.sql`, a proposed PostgreSQL schema. It is not applied to the prototype.

| Entity group | Main records and relationships |
|---|---|
| Identity and commercial access | users → study_profiles; users → entitlements |
| Knowledge | topics → parent topics; sources → chunks with vectors and locators |
| Content | content_versions → citations → chunks; questions → content_versions and topics |
| Learning | users → attempts; decks → cards → content_versions; review_states keyed by user/card; immutable review_events |
| Planning | users → plan_versions with inputs, allocation, rationale |
| Studio/community | creations → versioned content; forked_from ancestry; ratings unique by user/creation; reports and moderation resolutions |
| Reliability | generation_jobs with model/source versions; audit_events; client event IDs prevent duplicate attempt/review writes |

Content versioning matters: historical attempts retain the version students actually saw. Publication attaches to a reviewed immutable version; editing makes a new draft. Forks keep attribution, license, and provenance.

### Planning and scheduling

Prototype section weight = 1 + 2 × observed error rate; an unassessed section has weight 2. Divide weekly minutes by normalized weights, distribute rounding remainders, and keep total capacity exact. This is a transparent heuristic, not a validated adaptive model. Production should use recency, uncertainty, topic prerequisites, repeated-item suppression, and student overrides. Reserve retrieval time, mixed practice, explanation review, rest days, and a capped catch-up buffer. Missed tasks should roll forward without exceeding available hours.

Flashcard ratings map Again/Hard/Good/Easy to quality 1/3/4/5. Successful intervals start at 1 day and 6 days, then multiply by prior ease; ease has a 1.3 floor. A lapse resets repetitions and schedules the next day. This is SM-2-style, not a complete implementation of every SuperMemo daily-repetition rule. Production can later adopt FSRS after enough review history exists and validation compares retention/workload outcomes.

### Security, privacy, and execution

No secrets enter client code. Do not log full prompts, notes, or credentials. Explain external AI processing before first use. Private uploads use short-lived signed access; user files do not enter a shared knowledge base automatically. Define retention and deletion jobs, including backups, and provide export. No advertising trackers in the initial beta.

Prefer declarative tool specifications (template + validated content) over executable AI code. A future generated module runs on a separate origin in an iframe with only `allow-scripts`, restrictive CSP (`connect-src 'none'` by default), no same-origin privilege, no top navigation, and no parent secrets. A narrow postMessage protocol validates origin/channel, schema, payload size, and allowed events. Server execution, if introduced, requires isolated ephemeral processes with CPU/memory/time limits, no network by default, and no credential mounts. CSP alone does not prevent resource exhaustion.

## 3. User flows

### Guided mode

Set exam date and weekly hours → take a balanced diagnostic → inspect uncertainty and weak areas → accept/edit plan → complete focused learning and mixed practice → read explanations → label errors → create/review cards → inspect progress and changed priorities. A student can switch to Sandbox and return without losing the current study context. Production should preserve incomplete sessions; the prototype preserves saved activity only.

### Sandbox mode

Choose a template → paste notes or describe a tool → retrieve approved facts → inspect editable draft with citations → preview/play → save privately → optionally add to review plan. Later, publish a version → automated screening → subject review where needed → searchable community listing. Remix creates a new attributed child; a flagged source error can suspend dependent versions and notify affected users.

Empty/error paths: no source coverage means abstention; no AI configuration means a visible unavailable state; malformed generation is discarded; no cards means a creation action; no history means no metrics; a full local store prompts export. No error silently substitutes fabricated AI output.

## 4. Eight-week MVP and later phases

Assumption: one full-stack engineer, part-time designer and subject reviewers. This plan targets a reviewed limited beta; a broad paid public launch depends on the gates below.

| Week | Engineering and content outcome | Exit criterion |
|---|---|---|
| 1 | Product scope, source licensing, topic taxonomy, wireframes, reviewer rubric | Approved amino acid source set and acceptance criteria |
| 2 | Auth, tenant data model, migrations, audit trail, export/delete foundation | Cross-user access tests pass; restore drill succeeds |
| 3 | Original reviewed question bank and diagnostic session | At least 80 reviewed items across four sections; explicit limited coverage |
| 4 | Weekly planner and explainable adaptations | Capacity invariants and override behavior tested |
| 5 | Retrieval tutor, citations, styles, abstention, quotas | Grounded-answer evaluation meets release threshold |
| 6 | Card drafting/editing, spacing, offline review/sync | No duplicate reviews or cross-device loss in conflict tests |
| 7 | Matching template and analytics | Keyboard/mobile usability and event integrity pass |
| 8 | Security/accessibility review, billing test mode, limited beta | Accuracy, reliability, privacy, and paid-access gates signed off |

Later: deeper topic coverage, full-length timed experiences, PDF/image and diagram processing, mnemonics and image cards, pathway builders, mind maps, trivia and boss battles, richer prompt-to-tool generation, then moderated public publishing/remixing. Introduce calibrated score trends only after collecting adequate held-out outcomes and assessing subgroup error. Do not convert raw accuracy linearly into MCAT scaled scores.

Commercial decisions still to settle before launch: pricing, free allowance, refund/support policy, target countries, source rights, independent reviewer budget, provider/data retention choices, and exact billing implementation. None is silently committed by this prototype.

## 5. Wireframes

`public/wireframes.html` contains six responsive low-fidelity screen wireframes: dashboard/plan, practice, tutor, review, creative studio, and community library. They document information hierarchy separately from the polished prototype. Desktop uses persistent navigation and a content canvas; phone layouts stack panels and keep navigation horizontally scrollable. Primary actions use explicit verbs, sources sit beside explanations, and review status remains visible.

## 6. Prototype inventory and limits

Working: dashboard, Guided/Sandbox switching, adaptive section allocations, four-section practice sampler, full distractor explanations, self-labeled errors, source explorer, editable source-based card drafts, manual/cloze cards, SM-2-style review, local export/delete, matching game, personal library, and activity analytics. Offline fallback offers read-only local cards; it does not claim offline AI.

Not connected/deployed: model credentials, live tutoring/generation, Postgres/vector retrieval, cloud study sync, payment processing, community moderation, arbitrary generated modules, PDFs/images, or calibrated score projection. The AI route is scaffolding, not evidence of a working live AI tutor. The knowledge records are source-linked and checked during development but have not been independently reviewed by an MCAT subject expert.

## 7. Testing and accuracy review

### Completed checks

Five automated tests cover schedule progression/lapses, ease floors/invalid grades, exact time allocation and weak-section priority, retrieval abstention/ranking, and question answer/explanation structure. TypeScript and production build results are recorded in the handoff. Browser QA covers the source explorer, drafting/saving cards, full matching game, and practice/review interactions. A passing structural test does not establish scientific accuracy.

### Required before a paid launch

| Test family | Cases and release threshold |
|---|---|
| Subject accuracy | Two independent reviewers assess every seed question and an evaluation set of at least 200 generated outputs; no known critical scientific errors at release; disagreements adjudicated |
| Grounding | At least 98% of factual claims supported by cited approved locators in the held-out evaluation; all source IDs valid; unsupported claims must be removed or flagged |
| Questions | Exactly one defensible answer, plausible distractors, original passages, unit consistency, no dependence on hidden assumptions |
| Coverage/abstention | Unanswerable, contradictory, prompt-injected, and out-of-topic requests; target at least 95% appropriate abstention on a curated adversarial set |
| Scientific edge cases | pH-dependent histidine charge, cysteine versus methionine, peptide versus disulfide bonds, glycine chirality, protein context, and misleading absolutes |
| CARS | Passage-based evidence, author stance and inference, no outside-fact prerequisite, ambiguity reviewed by a humanities reviewer |
| Security | Tenant authorization, CSRF/origin controls, XSS through generated content, file validation, signed URLs, public generation quotas, secret leakage, billing replay |
| Scheduling/data | Clock/timezone changes, midnight/DST, lapse behavior, due dates, duplicate sync events, offline conflicts, export/delete/restore |
| Accessibility | Automated scan plus keyboard and VoiceOver/NVDA review; WCAG 2.2 AA contrast and focus checks; 320px phone and 200% zoom |
| Reliability | Provider timeout/429, malformed JSON, missing citations, partial jobs, retry idempotency, concurrent sessions, rate limits and cost caps |

Accuracy flags must retain the exact content version, source version, reported claim, severity, reviewer resolution, and affected dependents. Critical errors unpublish affected versions and trigger re-review. Track correction rate and source coverage, not just satisfaction. Evaluate learning through delayed recall and novel transfer items rather than usage streaks alone.

## Reference sources

Sources were accessed October 27, 2026. Review exact licensing/edition terms before commercial reuse.

- AAMC, What's on the MCAT Exam: https://students-residents.aamc.org/prepare-mcat-exam/whats-mcat-exam-pdf-outline
- OpenStax Biology 2e §3.4, protein/amino acid concepts: https://openstax.org/books/biology-2e/pages/3-4-proteins
- OpenStax Organic Chemistry §26.1, side-chain ionization: https://openstax.org/books/organic-chemistry/pages/26-1-structures-of-amino-acids
- OpenStax Psychology 2e §6.3, reinforcement schedules: https://openstax.org/books/psychology-2e/pages/6-3-operant-conditioning
- SuperMemo algorithm history and SM-2 description: https://www-beta.supermemo.com/en/articles/history
- Anki scheduling documentation (distinguishes variants from SM-2): https://faqs.ankiweb.net/what-spaced-repetition-algorithm.html


## Prototype update — daily planning and card management

The prototype now includes a seven-day planning preview with selectable study days, study blocks capped at 25 minutes, a pre-exam cutoff, proportional capacity for a partial week, and local completion checkmarks. Planning checkmarks do not count as measured study time. The plan recalculates as the current day, capacity, or section priorities change; it is not a persistent calendar or a full carry-forward scheduler. The content sampler is still too small to fill all planned blocks.

Flashcards now support search, editing, and deletion. Edits preserve source links but reset review progress. A validated JSON backup can restore cards, scheduling, practice attempts, weekly hours, and exam date after confirmation. Study-day selections and planner checkmarks remain browser-local and are not included in the legacy export format. Imports reject malformed data, duplicate card IDs, unsafe source URL schemes, invalid dates, and excessive file sizes.

Question accuracy and adaptive allocations exclude game events. Game sessions remain visible as a separate count in Insights. Retrieval filters generic query words to reduce irrelevant source matches. Ten automated tests cover the original logic plus scheduling capacity, available weekdays, exam cutoffs, game separation, and backup validation. These checks do not substitute for subject review or full accessibility testing.


## Feature priorities and retention update

The latest implementation follows the requested order: core retrieval loop → planning and honest analytics → AI differentiation → moderated collaboration. Engagement rewards must reflect demonstrated retrieval and varied practice; time, clicks, and unbroken streaks are not evidence of learning.

| Requested feature | Status | Current boundary and next step |
|---|---|---|
| Spaced repetition | Working | SM-2-style scheduling; retrieval performance changes intervals. FSRS remains a later option. |
| Active recall cards | Working | Cloze, typed self-explanations, and optional raster image attachments with alt text. Self-rated rather than AI-graded. |
| Practice with explanations | Working, limited bank | Nine original items; reasoning and every distractor explained. Four-item baseline sampler is not a diagnostic score. |
| Interleaving | Working | Mixes available sections and topics within a finite practice set; more reviewed content is needed. |
| Confidence ratings | Working | Required before answer reveal; confident errors and recall lapses are surfaced for reflection. |
| AI tutor / Socratic mode | Connection required | Source explorer works without AI. Live explanation, adaptive tutoring, and Socratic generation are disconnected. |
| Auto-generated material | Partial | Editable drafts from a small source collection; live generation, PDFs, and lecture transcription are not connected. |
| Goals and deadlines | Partial | Seven-day plan with selected days, exam cutoff, and personal checkmarks; persistent calendar goals remain planned. |
| Focus timer | Working | Study/break intervals, pause, quiet view, completed or partial session logs. Cannot block other apps. |
| Reminders and streaks | Planned | Opt-in reminders with quiet hours and forgiving weekly consistency; no guilt, lost-streak penalties, or automatic notification permissions. |
| Adaptive plan | Partial | Section weights respond to practice errors. Persistent missed-session carry-forward and prerequisite sequencing remain planned. |
| Workload forecast | Partial | Current saved-deck estimate with explicit assumptions; cannot forecast full syllabus completion yet. |
| Searchable capture | Partial | Searchable cards and small manual images; tagged notes, full-text files, and upload processing remain planned. |
| Syllabus / topic tree | Planned | Four sections and topic labels exist; curated blueprint coverage and prerequisite tree still need content review. |
| Knowledge graph | Planned | Reviewed concept links and related-concept review, with accessible text equivalents. |
| Offline and sync | Partial | Offline read-only cards after an online visit, plus export/import. Cross-device cloud sync is not connected. |
| Mastery dashboard | Partial | Recent topic evidence deduplicates known repeated items; limited evidence labels, trends, and accuracy. No certified mastery. |
| Session history | Working | Question attempts, timed focus sessions, and self-rated flashcard reviews; overlapping time is not added together. |
| Error diagnosis | Partial | Self-labeled content gap, misreading, careless error, or timing. Automated diagnosis is not connected. |
| Predictive readiness | Research gate | No fabricated MCAT score. Requires adequate reviewed item coverage, longitudinal data, calibration, held-out validation, and uncertainty bounds. |
| Accessibility and platforms | Partial | Responsive web, keyboard labels, text/contrast preferences, image descriptions; full screen-reader and mobile audit still required. |
| Shared decks / community | Planned | Personal library works. Public publishing, ratings, provenance-preserving forks, and accuracy flags require moderation first. |
| Groups / accountability | Planned | Opt-in shared goals and chosen progress visibility; private by default with revocable sharing. |
| Creative Studio | Partial | Card workshop and fixed matching game work. User-authored games, diagrams, pathways, and AI prompt-to-tool remain planned. |

Confidence is recorded before feedback at 40%, 70%, or 90%; it is the learner’s judgment, not a probability generated by the model. The dashboard flags incorrect practice responses rated at least 80% confident and high-confidence recall lapses. Topic evidence uses each known question’s latest response over 30 days and labels fewer than five distinct items as insufficient evidence. Legacy attempts without an item ID are treated as separate records, so their distinct-item counts are approximate. More items and independent subject review are needed before meaningful mastery thresholds can be validated.

Manual cards accept PNG/JPEG/WebP attachments up to 150 KB, require a description, and retain images in local export/import. Typed answers are temporary and self-assessed; exact wording is not graded. Source citations remain visible after reveal. Cloze answers are hidden in the review prompt and card-list preview. Offline review supports the same cloze masking and manual images, but is read-only.

Focus logs measure elapsed timer activity, excluding pauses and rest breaks; they do not prove attention or learning. Leaving the Focus page resets an unfinished timer; save a partial session before navigating. Focus, practice, and recall history can overlap, so the dashboard keeps their time separate. Backups now preserve focus/recall history and pre-answer confidence. The app preserves unreadable local data instead of overwriting it with defaults.

The workload forecast simulates successful future recalls using the current schedule and an estimated review duration; it excludes new cards, lapses, question practice, new content learning, and the rest of the syllabus. It therefore describes the current deck only and cannot certify whether the learner is ready to test.

Validation: 16 automated tests cover scheduling, planner limits, import safety, confidence flags, interleaving, cloze masking, item deduplication, and forecast boundaries. Browser testing and production build validation are reported at handoff. Scientific content remains source-linked development content pending independent review.