System Requirements Document for documindrag

1. Introduction

DocuMindRAG is a calm, distraction-free study workspace for students. It turns any study material — uploaded files or pasted links — into summaries, visual explanations, quizzes, and relaxing brain breaks, so students can study in peace and stay focused. The product intent is explicitly a quiet study desk, not a busy dashboard: low visual noise, generous space, slow soothing motion, and one primary action per screen.

The audience is students who are already overwhelmed by noisy dashboards, notifications, and pressure. They arrive with lecture PDFs, slide decks, scanned pages, YouTube lectures, articles, and social posts, and they need that material converted into readable summaries, best-fit visuals, self-check quizzes, and short restorative breaks — without a productivity cockpit feel.

This document specifies the current, buildable product: the anonymous welcome experience, first-use enrollment and returning verification, and the authenticated study workspace with Library, Summaries, Chat, Quiz, and Mind Games, plus focus mode, the RAG backend, and the calm design system.

2. System Overview

DocuMindRAG is delivered as a first-party web application with a React + Vite (JavaScript) frontend and a Python FastAPI backend over SQLite, using the Groq API for AI generation with the key loaded from .env and never exposed to the frontend. Retrieval is a RAG pipeline: uploaded content is chunked, embedded, and retrieved so answers carry source references.

Current actors: a single accepted human persona, the Student. The Groq API, link-source platforms (YouTube, article sites, blogs, Reddit, X/Twitter, Instagram, LinkedIn, and so on), and the OCR/embedding/extraction services are typed non-persona actors — external providers and system processes, not personas.

Accepted behavior in the current horizon:

• Drag-and-drop upload of PDF, DOCX, PPTX, TXT, MD, and images (with OCR for images/scans), multiple files at once, progress bars, and clear error messages.
• A file library sidebar where the student selects one or many files as the active study context.
• Link ingestion and summarization for YouTube, articles, blogs, Reddit, X/Twitter, Instagram, LinkedIn, and so on, producing a short summary, key points, key terms, and an "explain like I'm new to this" version, with a friendly fallback when a platform blocks extraction, and every summary saved to the library like a normal file.
• Automatic best-fit visuals per summary — concept maps, flowcharts, timelines, comparison tables, and charts for numeric data — each with a plain-language caption and PNG download.
• A quiz engine generating a minimum of 15 questions (default 20) from selected files or links, mixing multiple choice, true/false, fill-in-the-blank, and short answer, with difficulty and question-count selectors, instant feedback with explanations and source passages, a results screen with a score ring, a weak-topic breakdown chart, and a "retry only the ones I missed" button, with no time pressure by default and an optional timer toggle.
• Mind games and brain breaks: guided breathing bubble, memory card match, sliding puzzle, Zen sand-draw or bubble-pop, and a word-scramble using the student's own key terms — each 1 to 3 minutes, no harsh sounds, no leaderboards, no pressure.
• Ask your notes chat with streaming answers, markdown rendering, and source chips.
• One-click focus mode hiding everything except the current task, with an optional Pomodoro timer (25/5) and a gentle chime, and optional ambient sounds (rain, soft piano, white noise) with a volume slider, off by default.

Narrow exclusions carried from the source: no neon, no pure black, no pure white; no fast or flashy motion, nothing that spins fast, flashes, or shakes; no leaderboards, streak counters, or pressure timers; no harsh notification sounds; no cartoon people or mascots; no gradient-blob heroes or glassmorphism; the generic indigo/blue-on-white SaaS template is forbidden. The 3D is decoration only — the study tools (upload, quiz, chat) must always be fast and 2D.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. DocuMindRAG is a first-party web application. The frontend is React + Vite in JavaScript with plain CSS design tokens, Three.js via @react-three/fiber and @react-three/drei for the welcome 3D still-life, Framer Motion for UI transitions, Recharts for charts, and Mermaid for diagrams. The backend is Python FastAPI with SQLite, and the Groq API key is loaded from .env and never exposed to the frontend. The RAG pipeline chunks uploaded content, embeds it, retrieves relevant chunks, and answers with source references. CORS is enabled for the frontend origin; file types and size are validated; errors return clear messages.

Access ownership. The welcome page is anonymous and public — it is the calm entry surface with the 3D hero, three feature cards, and the "Start studying" button. Because the student's uploaded files, generated summaries, quiz results, and study history are durable personal records that must remain bound to the correct participant, the application owns identity: first-use enrollment on Sign Up and returning verification on Login. Both access surfaces are anonymously reachable; the protected study destinations (Library, Summaries, Chat, Quiz, Mind Games) require a verified session. No differentiated permissions, roles, or role-based visibility are established — every authenticated student sees only their own study workspace.

Current vs. future boundary. Everything in Section 3 is current. The optional dark "night study" theme, the optional Pomodoro timer, the optional quiz timer toggle, and the optional ambient sounds are current optional features, off or inactive by default. No future-horizon features are specified by the source; nothing in this document is deferred.

Provider and external boundaries. Link extraction depends on third-party platforms; when a platform blocks extraction, the product shows the friendly fallback and lets the student paste text or a transcript instead. AI generation is provider-owned (Groq) behind the backend; the frontend never holds the key. OCR, chunking, embedding, retrieval, streaming, and quiz evaluation are backend system processes with no separate human-facing surface.

2b. Source Content Inventory

No reference directive with content_source authority was supplied; no source content inventory is included.

2c. Page Content and Component Coverage

Welcome page

• Information and state: Anonymous public entry. Full-viewport warm-cream field (#F4F1EA). A small 14px Manrope label "DOCUMIND RAG" in 0.14em tracking; one Fraunces italic headline "Study in peace." at clamp(40px, 9vw, 88px) with the word "peace" in sage; one 18px muted supporting line; one sage "Start studying" button (16px radius, 20px 32px padding); three feature cards; a lazy-loaded React Three Fiber still-life behind and to the right at 30% opacity.
• Primary action: "Start studying" — enters the study workspace, routing to Sign Up for a first-time visitor or Login for a returning student.
• Supporting actions: Read the three feature cards; hover a card for a subtle 3D tilt (max 3°, 500ms).
• Domain entities: Feature card (title, description, quiet icon or rule), 3D still-life scene (open book, folded paper note, pale wooden cube).
• Component responsibilities: WelcomeHero (typographic column, asymmetric left-of-centre 7 columns), FeatureCards (three cards, 16px radius, hairline rules), HeroScene (R3F canvas, lazy-loaded, 30fps cap, mouse-parallax clamped to ±8px, 0.05 rad/s drift), StaticHeroFallback (2D cream→sand gradient with flat SVG silhouettes of the same three objects).
• States: Loading — hero type renders immediately; the 3D scene lazy-loads behind a static gradient so nothing blocks. Empty — not applicable (static marketing surface). Success — hero, cards, and button render; the still-life drifts slowly. Error — if the 3D scene fails to load or the device is low-power, the static 2D gradient and SVG silhouettes render instead, with no error copy shown to the student. Recovery — reduced-motion or low-power detection swaps to the static version automatically; no student action required.

Sign Up

• Information and state: Anonymous first-use enrollment surface. Calm cream ground, one centred sheet (#FBF9F4, 20px radius, 24–32px padding), Fraunces italic heading, Manrope field labels. Fields: email, password, confirm password. A single sage primary button. A quiet link to Login for students who already have an account.
• Primary action: Create the student's account and establish the session.
• Supporting actions: Navigate to Login; toggle password visibility.
• Domain entities: Student account (email, password credential, created timestamp).
• Component responsibilities: AuthSheet (shared shell for Sign Up and Login), CredentialForm (validation, inline field errors), PasswordField (visibility toggle, screen-reader label).
• States: Loading — button shows an inline progress state; fields disable. Empty — pristine form with placeholder guidance. Success — session established and the student lands in the Library with an empty-state prompt to upload or paste a link. Error — inline field-level messages for invalid email, weak password, mismatched confirmation, or an already-registered email; a form-level message for a network or server failure with a retry affordance. Recovery — the student corrects the field and resubmits; entered values are preserved on failure.

Login

• Information and state: Anonymous returning-verification surface. Same calm sheet treatment as Sign Up. Fields: email, password. A single sage primary button. A quiet link to Sign Up.
• Primary action: Verify the student and restore their session.
• Supporting actions: Navigate to Sign Up; toggle password visibility.
• Domain entities: Student account (email, password credential), session.
• Component responsibilities: AuthSheet, CredentialForm, PasswordField.
• States: Loading — button shows an inline progress state; fields disable. Empty — pristine form. Success — session restored and the student lands in the Library with their previously uploaded files, summaries, and study records intact. Error — a form-level message for incorrect credentials or a network/server failure, with a retry affordance; no field is silently cleared. Recovery — the student retries; on repeated failure the message remains calm and non-punitive, with no lockout or pressure language.

Library

• Information and state: The authenticated study workspace's default tab. A persistent 280px left sidebar holds the file list; the main column holds the Library tab content. The sidebar header reads "N sources in context" in Fraunces italic when files are selected. Each file row is a cream sheet with a 1px bottom rule, a Fraunces italic filename, and a small sage checkbox. The main column shows the drag-and-drop upload zone, per-file progress bars, and the file list with type, size, and upload date.
• Primary action: Upload study material by drag-and-drop or file picker.
• Supporting actions: Select one or many files as the active study context; delete a file; open a file's detail; paste a link (routes to Summaries); enter focus mode.
• Domain entities: File record (id, filename, type, size, upload date, processing status, extracted text, chunks), selection set (active study context), upload job (progress, error).
• Component responsibilities: FileSidebar (multi-select checkboxes, "N sources in context" header, mobile bottom-sheet drawer variant opened by a "Files (3 selected)" bar), UploadDropzone (drag-and-drop, multi-file, accepted types PDF/DOCX/PPTX/TXT/MD/images), UploadProgressList (per-file progress bars, clear error messages), FileList (rows, delete control, empty state), FocusModeToggle.
• States: Loading — skeleton rows in the sidebar and main list while GET /files resolves. Empty — a calm empty state inviting the student to drop files or paste a link, with the accepted types named. Success — files appear with progress bars completing, then settle into the list; selecting files updates the sidebar header to "N sources in context". Error — per-file error messages for unsupported type, oversized file, or failed processing, each with a retry affordance; a list-level message if GET /files fails. Recovery — the student retries the failed file, removes it, or uploads a corrected version; previously uploaded files remain intact.

Summaries

• Information and state: The Summaries tab. A link input at the top; below it, the generated summary for the active source with four sections — short summary, key points, key terms, and "explain like I'm new to this" — and the auto-generated visuals with plain-language captions. A full-bleed photographic still-life opener (warm-lit desk, open book, folded note, cup, small geometric object; no people, no logos) heads the surface.
• Primary action: Paste a link and generate its summary.
• Supporting actions: Paste text or a transcript when a platform blocks extraction; download a visual as PNG; open a source chip to scroll the source panel and briefly underline the passage in sand (#F3E8D2); select the summary in the library as active study context.
• Domain entities: Link record (url, platform, extraction status, extracted text), summary (short summary, key points, key terms, beginner explanation), visual (type — concept map, flowchart, timeline, comparison table, chart — caption, PNG export), source chip (page or timestamp reference, filename).
• Component responsibilities: LinkInput (URL field, submit), ExtractionFallback (the exact message "We couldn't read this link. Paste the text or transcript instead." plus a paste-text area), SummarySections (four labeled blocks), VisualGallery (Mermaid-rendered diagrams in ink-on-paper with sage and mist-blue strokes, Recharts charts for numeric data, comparison tables, each with a caption and a PNG download control), SourceChip (mist-blue #8FB3CC at 12% fill, 1px border, 13px Manrope, e.g. "p. 4 · lecture-03.pdf").
• States: Loading — skeleton blocks for each summary section and placeholder frames for visuals while extraction and generation run. Empty — a calm prompt to paste a link, with the supported platforms named. Success — the four summary sections and the best-fit visuals render with captions; the summary is saved to the library like a normal file and appears in the sidebar. Error — the exact fallback message when a platform blocks extraction, with the paste-text path; a clear message for an invalid or unreachable URL; a retry affordance for generation failure. Recovery — the student pastes text or a transcript and regenerates; the saved summary remains available in the library.

Chat

• Information and state: The Chat tab. A message thread with the student's questions and the streamed answers, markdown-rendered, each answer carrying source chips. A composer at the bottom. The active study context (selected files) is shown so the student knows what the chat is grounded in.
• Primary action: Ask a question about the uploaded material.
• Supporting actions: Open a source chip to scroll the source panel and briefly underline the passage in sand; select or change the active study context; enter focus mode.
• Domain entities: Chat message (role, content, timestamp), streamed answer, source chip (page or timestamp reference, filename), active study context.
• Component responsibilities: ChatThread (markdown rendering, streaming append), ChatComposer (multiline input, send), SourceChipRow (per-answer citations), ContextIndicator (which files ground the answer).
• States: Loading — the answer streams token by token with a quiet inline indicator; the composer stays responsive. Empty — a calm prompt to ask the first question about the selected material. Success — the full answer renders with markdown and source chips. Error — a clear message if the stream fails or no study context is selected, with a retry affordance; partial streamed text is preserved. Recovery — the student resends the question or selects files and retries.

Quiz

• Information and state: The Quiz tab. A configuration panel with a difficulty selector (easy, medium, hard), a question-count selector (15, 20, 30), and an optional timer toggle (off by default). The question view shows one question at a time with its type-appropriate input. The results view shows a 180px score ring drawn with a 6px sage stroke on a #DDD6C8 track with the score in Fraunces italic at 64px inside, a weak-topic breakdown chart, and a "retry only the ones I missed" button.
• Primary action: Generate a quiz from the selected files or links.
• Supporting actions: Answer multiple choice, true/false, fill-in-the-blank, and short answer questions; read instant feedback with the explanation and the source passage; open a source chip; toggle the optional timer; retry only the missed questions; start a fresh quiz.
• Domain entities: Quiz (count, difficulty, type mix, source selection), question (type, prompt, options, correct answer, explanation, source passage), attempt (answers, per-question correctness, score, weak topics).
• Component responsibilities: QuizConfig (difficulty, count, timer toggle), QuestionCard (type-specific input, instant feedback panel with explanation and source passage), ScoreRing (sage stroke, Fraunces italic score), WeakTopicChart (Recharts), RetryMissedButton, SourceChip.
• States: Loading — skeleton question cards while POST /quiz/generate runs. Empty — a calm prompt to select files or links before generating. Success — questions render; feedback appears instantly per answer; the results screen shows the score ring, weak-topic chart, and retry button. Error — a clear message if generation fails or the selection is empty, with a retry affordance; a message if submission fails, with the student's answers preserved. Recovery — the student regenerates, changes the selection, or retries submission without losing answers.

Mind Games

• Information and state: The Mind Games tab. A grid of brain-break cards on soft sand (#F3E8D2) grounds with sage hover, each naming one game and its 1-to-3-minute length. A full-bleed photographic still-life opener heads the surface. Each game opens in place.
• Primary action: Start a brain break.
• Supporting actions: Play the guided breathing bubble (a single mist-blue circle growing from 96px to 220px over 4s inhale / 2s hold / 6s exhale, with the word "inhale" in Fraunces italic inside it); play memory card match; play the sliding puzzle; play Zen sand-draw or bubble-pop; play the word-scramble built from the student's own key terms from their notes; leave a game at any time.
• Domain entities: Game (name, duration, state), key terms (drawn from the student's notes), breathing cycle (inhale, hold, exhale).
• Component responsibilities: BrainBreakGrid (sand-ground cards, sage hover), BreathingBubble, MemoryMatch, SlidingPuzzle, ZenSandDraw or BubblePop, WordScramble (key-term source), GameShell (quiet exit, no score pressure).
• States: Loading — a brief skeleton for the card grid; games initialize instantly. Empty — if no key terms exist yet for the word-scramble, a calm note that the game unlocks once notes or summaries exist, with the other games still available. Success — the game runs for its 1-to-3-minute span and ends gently with no score, no leaderboard, and no harsh sound. Error — a clear message if a game fails to initialize, with a retry affordance. Recovery — the student retries or returns to the grid; no progress is lost elsewhere.

3. Functional Requirements

Each story point carries provenance: explicit (source-stated), basic_default (accepted default), or required_inference (indispensable inferred mechanics).

Identity and access

FR-1 — First-use enrollment (required_inference) As a Student, I should be able to create my account on the Sign Up page so that my uploaded files, summaries, quizzes, and study history are durably mine.

• Trigger/input: the student arrives at Sign Up from the Welcome page's "Start studying" button or the Login page's link, and submits email, password, and password confirmation.
• Observable result: a session is established and the student lands in the Library with an empty-state prompt.
• Access state: anonymous entry; the Sign Up page is reachable without a session.
• Failure/recovery: invalid email, weak password, mismatched confirmation, or an already-registered email produce inline field messages; a network or server failure produces a form-level message with retry; entered values are preserved.
• Continuation: the student proceeds to upload files or paste a link.

FR-2 — Returning verification (required_inference) As a Student, I should be able to verify myself on the Login page so that I regain access to my saved study materials and generated learning records.

• Trigger/input: the student submits email and password on Login.
• Observable result: the session is restored and the Library shows the student's previously uploaded files, summaries, and study records.
• Access state: anonymous entry; the Login page is reachable without a session.
• Failure/recovery: incorrect credentials or a network/server failure produce a calm form-level message with retry; no field is silently cleared and there is no lockout or pressure language.
• Continuation: the student resumes study work where they left off.

FR-3 — Protected study workspace (required_inference) As a Student, I should only reach Library, Summaries, Chat, Quiz, and Mind Games after my identity is verified, so that my study records stay bound to me.

• Trigger/input: navigating to any protected destination without a verified session.
• Observable result: the student is routed to Login (or Sign Up for a first-time visitor) and, after verification, lands on the intended destination.
• Access state: Library, Summaries, Chat, Quiz, and Mind Games require login; Welcome page, Sign Up, and Login are anonymous.
• Failure/recovery: a failed verification keeps the student on the access surface with a clear message and retry.
• Continuation: after verification the student continues into the requested destination.

Upload and library

FR-4 — Drag-and-drop multi-file upload (explicit) As a Student, I should be able to drag and drop PDF, DOCX, PPTX, TXT, MD, and image files — several at once — so that my study material enters the workspace.

• Trigger/input: dropping files onto the upload zone or choosing them with the file picker.
• Observable result: each file appears with its own progress bar and, on completion, settles into the file list and the sidebar.
• Access state: requires login.
• Failure/recovery: unsupported type, oversized file, or failed processing produce a clear per-file error message with a retry affordance; other files in the same batch are unaffected.
• Continuation: the student selects the uploaded files as the active study context.

FR-5 — OCR for images and scans (explicit) As a Student, I should have images and scanned pages read with OCR so that photographed or scanned study material becomes usable text.

• Trigger/input: uploading an image or scanned document.
• Observable result: the extracted text is stored with the file and becomes available to summaries, chat, and quizzes.
• Access state: requires login.
• Failure/recovery: if OCR yields no usable text, a clear message explains it and the student can upload a clearer file.
• Continuation: the file participates in the active study context like any other.

FR-6 — File library sidebar with multi-select context (explicit) As a Student, I should be able to select one or many files in the persistent left sidebar as my active study context, so that summaries, chat, and quizzes are grounded in exactly what I choose.

• Trigger/input: checking one or more file checkboxes in the sidebar.
• Observable result: the sidebar header reads "N sources in context" in Fraunces italic, and the selection drives Summaries, Chat, and Quiz.
• Access state: requires login.
• Failure/recovery: if the file list fails to load, a clear message with retry appears; the selection is preserved across tab switches.
• Continuation: the student moves to Chat, Summaries, or Quiz with the context intact.

FR-7 — Mobile drawer for the file library (explicit) As a Student on a phone, I should reach the file library through a mobile drawer so that the sidebar does not crowd the study surface.

• Trigger/input: tapping the "Files (N selected)" bar.
• Observable result: a bottom-sheet drawer opens with the same file list and multi-select checkboxes.
• Access state: requires login.
• Failure/recovery: if the drawer fails to open, the bar remains tappable and the main column stays usable.
• Continuation: the student selects files and closes the drawer to continue.

FR-8 — Delete a file (explicit) As a Student, I should be able to delete a file so that my library stays clean.

• Trigger/input: the delete control on a file row, confirmed.
• Observable result: the file is removed from the list and sidebar, and it no longer participates in the active study context.
• Access state: requires login.
• Failure/recovery: a failed delete shows a clear message with retry; the file remains visible until the delete succeeds.
• Continuation: the student continues with the remaining files.

FR-9 — Durable file and summary records (required_inference) As a Student, I should have my uploaded files and generated summaries persist as durable records so that my study workspace survives across sessions.

• Trigger/input: any successful upload, link ingestion, or summary generation.
• Observable result: the record is retrievable on a later visit after verification.
• Access state: requires login; records are bound to the verified student.
• Failure/recovery: a persistence failure surfaces a clear message with retry, and the in-memory result remains visible for the session.
• Continuation: the student resumes work on the persisted record.

Link summarizer

FR-10 — Link ingestion and summarization (explicit) As a Student, I should be able to paste any link — YouTube, articles, blogs, Reddit, X/Twitter, Instagram, LinkedIn, and so on — and receive a short summary, key points, key terms, and an "explain like I'm new to this" version, so that outside material becomes study material.

• Trigger/input: pasting a URL into the link input on Summaries and submitting.
• Observable result: the four summary sections render, and the summary is saved to the library like a normal file.
• Access state: requires login.
• Failure/recovery: an invalid or unreachable URL produces a clear message with retry; a generation failure produces a clear message with retry.
• Continuation: the student reads the summary, opens its visuals, or selects it as study context.

FR-11 — YouTube transcript and page-text extraction (explicit) As a Student, I should have YouTube transcripts and page text extracted so that the summary reflects the actual content.

• Trigger/input: submitting a YouTube or article URL.
• Observable result: the extracted text grounds the summary and the source chips.
• Access state: requires login.
• Failure/recovery: if extraction yields nothing usable, the fallback in FR-12 applies.
• Continuation: the student reads the summary or pastes text instead.

FR-12 — Friendly extraction fallback (explicit) As a Student, I should see the message "We couldn't read this link. Paste the text or transcript instead." when a platform blocks extraction, so that I can still get my summary.

• Trigger/input: a platform blocking extraction.
• Observable result: the exact fallback message appears with a paste-text area.
• Access state: requires login.
• Failure/recovery: if the pasted text is empty or unusable, a clear message asks for more text.
• Continuation: the student pastes text or a transcript and generates the summary.

FR-13 — Summaries saved to the library (explicit) As a Student, I should have every summary saved to the library like a normal file so that I can select it as study context later.

• Trigger/input: a completed link summary.
• Observable result: the summary appears in the file list and sidebar and can be checked as active study context.
• Access state: requires login.
• Failure/recovery: a failed save shows a clear message with retry; the summary stays readable in the session.
• Continuation: the student selects the saved summary for chat or quiz.

Visual learning

FR-14 — Automatic best-fit visuals per summary (explicit) As a Student, I should have the best-fit visuals generated automatically for every summary — concept maps, flowcharts, timelines, comparison tables, and charts for any numeric data — so that I can see the structure of the material.

• Trigger/input: a completed summary.
• Observable result: the appropriate visuals render alongside the summary, chosen to fit the content.
• Access state: requires login.
• Failure/recovery: if a visual fails to render, a clear message appears in its place with retry; the summary text remains readable.
• Continuation: the student reads the visuals or downloads them.

FR-15 — Plain-language captions (explicit) As a Student, I should see a plain-language caption on each visual so that I understand what it shows without decoding it.

• Trigger/input: any rendered visual.
• Observable result: a caption in 13px Manrope muted sits with the visual.
• Access state: requires login.
• Failure/recovery: if a caption is missing, the visual is still labeled by its type.
• Continuation: the student reads the caption and continues.

FR-16 — Download visuals as PNG (explicit) As a Student, I should be able to download any visual as a PNG so that I can keep or share it.

• Trigger/input: the download control on a visual.
• Observable result: a PNG file is produced containing the visual.
• Access state: requires login.
• Failure/recovery: a failed export shows a clear message with retry.
• Continuation: the student continues studying or downloads another visual.

Quiz engine

FR-17 — Quiz generation with count, difficulty, and type mix (explicit) As a Student, I should be able to generate a quiz of at least 15 questions (default 20) from my selected files or links, choosing easy/medium/hard difficulty and a count of 15, 20, or 30, with a mix of multiple choice, true/false, fill-in-the-blank, and short answer, so that I can test myself on exactly what I selected.

• Trigger/input: selecting files or links, choosing difficulty and count, and generating.
• Observable result: a quiz renders with the requested count, difficulty, and type mix; the minimum is 15 and the default is 20.
• Access state: requires login.
• Failure/recovery: an empty selection or a generation failure produces a clear message with retry.
• Continuation: the student answers the questions.

FR-18 — Instant feedback with explanations and source passages (explicit) As a Student, I should get instant feedback on each answer with an explanation and the source passage so that I learn from every question.

• Trigger/input: submitting an answer to a question.
• Observable result: correctness, an explanation, and the source passage appear immediately, with a source chip.
• Access state: requires login.
• Failure/recovery: if the source passage cannot be resolved, the explanation still appears with a clear note.
• Continuation: the student moves to the next question.

FR-19 — Results screen with score ring and weak-topic breakdown (explicit) As a Student, I should see a results screen with a score ring and a weak-topic breakdown chart so that I know where I stand and what to revisit.

• Trigger/input: completing the quiz.
• Observable result: a 180px score ring with a 6px sage stroke on a #DDD6C8 track and the score in Fraunces italic at 64px, plus a weak-topic breakdown chart.
• Access state: requires login.
• Failure/recovery: if the breakdown cannot be computed, the score ring still renders with a clear note.
• Continuation: the student retries missed questions or starts a new quiz.

FR-20 — Retry only the missed questions (explicit) As a Student, I should be able to retry only the ones I missed so that I focus my effort where it matters.

• Trigger/input: the "retry only the ones I missed" button on the results screen.
• Observable result: a new attempt contains only the previously missed questions.
• Access state: requires login.
• Failure/recovery: if the retry set cannot be built, a clear message offers a full retry instead.
• Continuation: the student answers the retry set and sees updated results.

FR-21 — No time pressure by default, optional timer toggle (explicit) As a Student, I should take quizzes with no time pressure by default, with an optional timer I can turn on, so that the quiz never pressures me unless I choose it.

• Trigger/input: the timer toggle in the quiz configuration, off by default.
• Observable result: with the toggle off, no timer is shown; with it on, a timer runs for the attempt.
• Access state: requires login.
• Failure/recovery: if the timer fails, the quiz continues untimed with a clear note.
• Continuation: the student finishes the quiz and sees results.

Mind games and brain breaks

FR-22 — Guided breathing bubble (explicit) As a Student, I should have a guided breathing bubble with an inhale/hold/exhale animation so that I can settle between study sessions.

• Trigger/input: opening the breathing game from the Mind Games grid.
• Observable result: a single mist-blue circle grows from 96px to 220px over 4s inhale / 2s hold / 6s exhale, with the word "inhale" in Fraunces italic inside it.
• Access state: requires login.
• Failure/recovery: if the animation fails, a static breathing cue with the same timing text renders.
• Continuation: the student finishes the cycle and returns to the grid.

FR-23 — Memory card match (explicit) As a Student, I should be able to play a memory card match so that I get a short, calm brain break.

• Trigger/input: opening the memory card match from the grid.
• Observable result: a card-matching game runs for 1 to 3 minutes with no score pressure.
• Access state: requires login.
• Failure/recovery: if the game fails to initialize, a clear message with retry appears.
• Continuation: the student finishes or leaves and returns to the grid.

FR-24 — Sliding puzzle (explicit) As a Student, I should be able to play a sliding puzzle so that I get a short, calm brain break.

• Trigger/input: opening the sliding puzzle from the grid.
• Observable result: a sliding puzzle runs for 1 to 3 minutes with no score pressure.
• Access state: requires login.
• Failure/recovery: if the puzzle fails to initialize, a clear message with retry appears.
• Continuation: the student finishes or leaves and returns to the grid.

FR-25 — Zen sand-draw or bubble-pop (explicit) As a Student, I should be able to play a Zen sand-draw or bubble-pop so that I get a short, calm brain break.

• Trigger/input: opening the Zen sand-draw or bubble-pop from the grid.
• Observable result: a free-form, pressure-free interaction runs for 1 to 3 minutes.
• Access state: requires login.
• Failure/recovery: if the interaction fails to initialize, a clear message with retry appears.
• Continuation: the student finishes or leaves and returns to the grid.

FR-26 — Word-scramble from the student's own key terms (explicit) As a Student, I should be able to play a word-scramble built from my own key terms from my notes so that my break still touches my material.

• Trigger/input: opening the word-scramble from the grid.
• Observable result: scrambled versions of the student's own key terms are presented for unscrambling.
• Access state: requires login.
• Failure/recovery: if no key terms exist yet, a calm note explains that the game unlocks once notes or summaries exist, and the other games remain available.
• Continuation: the student finishes or leaves and returns to the grid.

FR-27 — Short, pressure-free games (explicit) As a Student, I should have every game last 1 to 3 minutes with no harsh sounds, no leaderboards, and no pressure so that my break actually rests me.

• Trigger/input: any game session.
• Observable result: the game ends gently within 1 to 3 minutes, with no score ranking, no leaderboard, and no harsh sound.
• Access state: requires login.
• Failure/recovery: if a game overruns or stalls, the student can leave at any time with no penalty.
• Continuation: the student returns to the grid or back to study work.

Ask your notes (chat)

FR-28 — Chat with uploaded material (explicit) As a Student, I should be able to chat with my uploaded material so that I can ask questions about what I am studying.

• Trigger/input: typing a question into the Chat composer with an active study context.
• Observable result: an answer grounded in the selected material appears in the thread.
• Access state: requires login.
• Failure/recovery: if no study context is selected, a clear message asks the student to select files; a failed request shows a clear message with retry.
• Continuation: the student asks a follow-up question.

FR-29 — Streaming answers (explicit) As a Student, I should see answers stream in so that I can start reading immediately.

• Trigger/input: sending a question.
• Observable result: the answer appends token by token with a quiet inline indicator.
• Access state: requires login.
• Failure/recovery: if the stream breaks, the partial answer is preserved and a clear message offers retry.
• Continuation: the student reads the answer or retries.

FR-30 — Markdown rendering (explicit) As a Student, I should have answers rendered as markdown so that structure, lists, and emphasis are readable.

• Trigger/input: any streamed answer.
• Observable result: headings, lists, emphasis, and code render as formatted markdown.
• Access state: requires login.
• Failure/recovery: if rendering fails, the raw text remains readable.
• Continuation: the student continues the conversation.

FR-31 — Source chips on answers (explicit) As a Student, I should see source chips showing where each answer came from so that I can verify and read the original passage.

• Trigger/input: any answer.
• Observable result: mist-blue chips (#8FB3CC at 12% fill, 1px border, 13px Manrope) reading e.g. "p. 4 · lecture-03.pdf"; clicking one scrolls the source panel and briefly underlines the passage in sand (#F3E8D2).
• Access state: requires login.
• Failure/recovery: if a source cannot be resolved, the chip is omitted and the answer still renders.
• Continuation: the student reads the source and returns to the conversation.

Focus mode

FR-32 — One-click focus mode (explicit) As a Student, I should be able to enter focus mode with one click so that everything except my current task is hidden.

• Trigger/input: the focus mode toggle.
• Observable result: a full-bleed slate #2F3E46 takeover with a single cream task card centred at max-width 640px; the chrome dims over 800ms.
• Access state: requires login.
• Failure/recovery: if focus mode fails to engage, the normal workspace remains usable with a clear note.
• Continuation: the student works on the task and exits focus mode to return to the workspace.

FR-33 — Optional Pomodoro timer with a gentle chime (explicit) As a Student, I should be able to turn on an optional Pomodoro timer (25/5) with a gentle chime so that I can pace my session without pressure.

• Trigger/input: enabling the Pomodoro timer inside focus mode.
• Observable result: a 1px cream rule fills left-to-right over 25 minutes with the remaining minutes in Fraunces italic, and a 440Hz sine chime at 20% volume sounds at the end — never a beep.
• Access state: requires login.
• Failure/recovery: if audio is unavailable, the visual timer still runs and the end is marked visually.
• Continuation: the student takes the 5-minute break or continues.

FR-34 — Optional ambient sounds with a volume slider, off by default (explicit) As a Student, I should be able to turn on optional ambient sounds — rain, soft piano, white noise — with a volume slider, off by default, so that my environment matches my mood.

• Trigger/input: enabling an ambient sound and adjusting the volume slider.
• Observable result: the chosen sound plays at the chosen volume; the default state is off.
• Access state: requires login.
• Failure/recovery: if audio is unavailable, a clear note explains it and the rest of focus mode works.
• Continuation: the student adjusts or turns the sound off and continues studying.

Motion, performance, and design system

FR-35 — Welcome 3D still-life (explicit) As a Student, I should see a slow, calm 3D scene of softly floating books, notes, and geometric shapes drifting in a warm-lit space with gentle mouse-parallax depth on the welcome page, so that the entry feels like a quiet study desk.

• Trigger/input: loading the Welcome page.
• Observable result: three softly-lit objects — an open book, a folded paper note, and a pale wooden cube — float at 0.4 units of vertical drift, lit by one warm directional light and a soft cream environment, rendered at a 30fps cap, drifting at 0.05 rad/s with mouse-parallax clamped to ±8px, behind the type at 30% opacity.
• Access state: anonymous.
• Failure/recovery: if the scene fails to load, the static 2D cream→sand gradient with flat SVG silhouettes renders instead.
• Continuation: the student reads the hero and presses "Start studying".

FR-36 — Subtle card tilt and soft page transitions (explicit) As a Student, I should see cards tilt subtly on hover and pages transition with soft depth and fade so that the interface feels calm rather than flashy.

• Trigger/input: hovering a card or navigating between pages.
• Observable result: cards tilt at most 3° over 500ms; page transitions are a 600ms ease-in-out crossfade with a 12px upward drift.
• Access state: applies across the product.
• Failure/recovery: if motion is unavailable, the static state renders with no loss of function.
• Continuation: the student continues interacting.

FR-37 — Slow, soothing motion only (explicit) As a Student, I should experience motion that feels slow and soothing — ease-in-out, 400 to 800 ms — with nothing spinning fast, flashing, or shaking, so that the workspace never agitates me.

• Trigger/input: any animated transition.
• Observable result: all motion uses ease-in-out within 400–800 ms; no fast spin, flash, or shake occurs.
• Access state: applies across the product.
• Failure/recovery: if a transition cannot run, the end state renders immediately.
• Continuation: the student continues.

FR-38 — Respect prefers-reduced-motion (explicit) As a Student who prefers reduced motion, I should have 3D and animations disabled and a static version shown, so that the product respects my system setting.

• Trigger/input: the prefers-reduced-motion media query being active.
• Observable result: the 3D scene is removed entirely and replaced by the static 2D cream-to-sand gradient; all transitions reduce to instant opacity swaps.
• Access state: applies across the product.
• Failure/recovery: not applicable — the static version is the fallback.
• Continuation: the student uses the full product without motion.

FR-39 — Lazy-load, frame-rate cap, and low-power fallback (explicit) As a Student, I should have the 3D scene lazy-loaded with a capped frame rate and a 2D gradient fallback on low-power devices, so that performance stays high.

• Trigger/input: loading the Welcome page on any device.
• Observable result: the 3D scene loads lazily behind a static gradient, runs at a 30fps cap, and is replaced by the 2D gradient on low-power devices.
• Access state: anonymous.
• Failure/recovery: detection failure defaults to the static 2D gradient.
• Continuation: the student proceeds into the workspace.

FR-40 — 3D is decoration only; study tools stay fast and 2D (explicit) As a Student, I should have the study tools — upload, quiz, chat — always fast and 2D, so that decoration never slows my work.

• Trigger/input: using any study tool.
• Observable result: upload, quiz, and chat render and respond in 2D with no 3D dependency.
• Access state: requires login for the study tools.
• Failure/recovery: if the 3D scene is unavailable, the study tools are entirely unaffected.
• Continuation: the student continues studying.

FR-41 — Calm, warm design system with CSS variables (explicit) As a Student, I should experience a calm, warm, focused interface — like a quiet library — with all colors and spacing defined as CSS variables, so that the workspace feels consistent and low-noise.

• Trigger/input: any screen.
• Observable result: warm cream backgrounds (#F4F1EA, #FBF9F4), sage green primary (#7FA99B, hover #5B8C7D), mist blue accent (#8FB3CC), deep slate text (#2F3E46), muted text (#6B7C85), soft sand highlights (#F3E8D2); Fraunces italic for the brand and headings, Manrope for interface text; rounded corners 12–20px; soft slate-tinted shadows; generous spacing; low visual noise; no neon, no pure black, no pure white; all colors and spacing defined as CSS variables.
• Access state: applies across the product.
• Failure/recovery: if a token is missing, the nearest defined token applies rather than a hardcoded value.
• Continuation: the student continues.

FR-42 — Optional dark "night study" theme (explicit) As a Student, I should be able to switch to an optional dark "night study" theme using deep slate and muted sage, never pure black, so that I can study comfortably at night.

• Trigger/input: the theme toggle.
• Observable result: the interface inverts to a deep slate ground (#222E33) with muted sage (#6F9A8D) and paper (#EDE9E0) ink; #000 is never used.
• Access state: applies across the product.
• Failure/recovery: if the theme fails to apply, the light theme remains fully usable.
• Continuation: the student continues studying.

FR-43 — Accessibility (explicit) As a Student, I should have WCAG AA contrast, visible keyboard focus rings, alt text, and screen-reader labels so that I can use the product regardless of ability.

• Trigger/input: keyboard navigation, screen-reader use, or any rendered image.
• Observable result: contrast meets WCAG AA, focus rings are visible, images carry alt text, and controls carry screen-reader labels.
• Access state: applies across the product.
• Failure/recovery: if a label is missing, the control remains operable by keyboard.
• Continuation: the student continues.

FR-44 — Fully responsive across desktop, tablet, and phone (explicit) As a Student, I should have the product work fully on desktop, tablet, and phone so that I can study on any device.

• Trigger/input: any viewport width.
• Observable result: the 12-column grid with a 96px outer margin on desktop collapses to 24px on mobile; the sidebar becomes a bottom-sheet drawer; readable text and needed content stay whole at 375px, 768px, and 1280px.
• Access state: applies across the product.
• Failure/recovery: if a layout cannot fit, content wraps or scales rather than clipping.
• Continuation: the student continues.

Backend and quality

FR-45 — REST API surface (explicit) As a Student, I should have the backend expose POST /upload, GET /files, DELETE /files/{id}, POST /link, POST /summarize, POST /visuals, POST /quiz/generate (with count, difficulty, type mix), POST /quiz/submit, and POST /chat (streaming), so that every frontend capability has a working backend.

• Trigger/input: any frontend action that requires the backend.
• Observable result: the corresponding endpoint responds with the expected data or stream.
• Access state: endpoints serve the verified student's own records.
• Failure/recovery: errors return clear messages the frontend can display.
• Continuation: the student continues their task.

FR-46 — RAG pipeline with source references (explicit) As a Student, I should have my uploaded content chunked, embedded, and retrieved so that answers carry source references.

• Trigger/input: any summarization, chat, or quiz generation request.
• Observable result: relevant chunks are retrieved and the answer cites its sources via source chips.
• Access state: retrieval is scoped to the verified student's own material.
• Failure/recovery: if retrieval returns nothing relevant, a clear message explains it rather than fabricating an answer.
• Continuation: the student refines the question or selects more material.

FR-47 — CORS, validation, and clear errors (explicit) As a Student, I should have the backend enable CORS for the frontend origin, validate file types and size, and handle errors with clear messages, so that failures are understandable.

• Trigger/input: any cross-origin request, upload, or failing operation.
• Observable result: CORS is enabled for the frontend origin; invalid file types and oversized files are rejected with clear messages; other errors return clear messages.
• Access state: applies to all backend endpoints.
• Failure/recovery: the frontend surfaces the message and offers retry where applicable.
• Continuation: the student corrects the input and retries.

FR-48 — No hardcoded secrets; .env.example (explicit) As a Student, I should have the Groq API key loaded from .env and never exposed to the frontend, with no hardcoded secrets and a provided .env.example, so that my use of the product is secure.

• Trigger/input: backend startup and any AI request.
• Observable result: the key is read from .env server-side; the frontend bundle contains no key; .env.example documents the required variables.
• Access state: applies to the whole system.
• Failure/recovery: a missing key produces a clear backend error rather than a silent failure.
• Continuation: the operator configures .env and restarts.

FR-49 — Loading skeletons, empty states, and error states for every screen (explicit) As a Student, I should see loading skeletons, empty states, and error states on every screen so that I always know what is happening.

• Trigger/input: any screen load, empty data condition, or failure.
• Observable result: a skeleton while loading, a calm empty state when there is no data, and a clear error state with recovery on failure.
• Access state: applies across the product.
• Failure/recovery: the error state itself offers retry or a next step.
• Continuation: the student recovers and continues.

FR-50 — Clean, commented, modular code with a clear folder structure (explicit) As a Student, I should have the product built from clean, commented, modular code with a clear folder structure so that it is maintainable and trustworthy.

• Trigger/input: reading or extending the codebase.
• Observable result: a clear folder structure with commented, modular files.
• Access state: applies to the whole system.
• Failure/recovery: not applicable.
• Continuation: development continues.

FR-51 — README with Windows PowerShell setup steps (explicit) As a Student, I should have a README with setup steps for both frontend and backend using Windows PowerShell commands so that I can run the product locally.

• Trigger/input: following the README.
• Observable result: the frontend and backend start successfully using the documented PowerShell commands.
• Access state: applies to the whole system.
• Failure/recovery: the README documents the .env setup and common failure causes.
• Continuation: the student runs the product.

4. User Personas

Student

Product context. The Student is a learner who arrives with study material in many forms — lecture PDFs, slide decks, scanned pages, YouTube lectures, articles, blog posts, Reddit threads, and social posts — and who is already overwhelmed by noisy dashboards, notifications, and pressure. They want a quiet study desk: a place to think, not a productivity cockpit. They study in sessions, often alone, and they move between reading, self-testing, and resting.

Primary goal. To turn any study material into summaries, visual explanations, quizzes, and relaxing brain breaks so that they can study in peace and stay focused.

Distinct accepted responsibilities.

• Bringing material in: dragging and dropping PDF, DOCX, PPTX, TXT, MD, and image files (several at once), and pasting links from YouTube, articles, blogs, Reddit, X/Twitter, Instagram, LinkedIn, and so on.
• Curating context: selecting one or many files in the persistent left sidebar as the active study context, and deleting files they no longer need.
• Reading and seeing: reading the short summary, key points, key terms, and "explain like I'm new to this" version, and reading the auto-generated concept maps, flowcharts, timelines, comparison tables, and charts with their plain-language captions.
• Self-testing: generating quizzes of at least 15 questions (default 20) at easy/medium/hard difficulty with a mix of multiple choice, true/false, fill-in-the-blank, and short answer, reading instant feedback with explanations and source passages, reviewing the score ring and weak-topic breakdown, and retrying only the missed questions.
• Asking: chatting with their uploaded material and following source chips back to the original passage.
• Resting: taking 1-to-3-minute brain breaks — guided breathing, memory card match, sliding puzzle, Zen sand-draw or bubble-pop, and a word-scramble built from their own key terms.
• Focusing: entering one-click focus mode, optionally running a Pomodoro timer (25/5) with a gentle chime, and optionally playing ambient sounds (rain, soft piano, white noise) with a volume slider, off by default.

Relevant inputs and decisions. Which files and links to bring in; which files to select as active context; which link to summarize and whether to paste text when a platform blocks extraction; which difficulty and question count to choose; whether to enable the optional quiz timer; whether to retry only missed questions; which brain break to take; whether to enable the Pomodoro timer and ambient sounds; whether to switch to the dark "night study" theme.

Interactions with other accepted participants. The Student is the only accepted human persona. Their work is mediated by non-persona actors: the Groq API for AI generation, link-source platforms for extraction, and backend system processes for OCR, chunking, embedding, retrieval, streaming, and quiz evaluation. When a platform blocks extraction, the Student is handed the fallback and pastes text or a transcript themselves — the handoff is theirs, not a background step.

Observable success. The Student's material becomes readable summaries and best-fit visuals; their quizzes give instant, sourced feedback and a clear weak-topic picture; their chat answers cite where they came from; their breaks are short and pressure-free; and the whole workspace stays calm, warm, and quiet — with the study tools always fast and 2D.

Source-backed constraints. The Student's experience is bounded by: no neon, no pure black, no pure white; no fast or flashy motion; no leaderboards, streak counters, or pressure timers; no harsh sounds; no cartoon people or mascots; and the 3D being decoration only.

5. Core User Flows

Flow 1 — First visit and enrollment

1. The Student opens DocuMindRAG and lands on the Welcome page (anonymous). The hero renders immediately: the "DOCUMIND RAG" label, the Fraunces italic headline "Study in peace." with "peace" in sage, one muted supporting line, and the sage "Start studying" button. The lazy-loaded 3D still-life drifts behind at 30% opacity with mouse-parallax clamped to ±8px.
2. The Student reads the three feature cards and hovers one; it tilts at most 3° over 500ms.
3. The Student presses "Start studying". Because no session exists, they are routed to Sign Up.
4. On Sign Up, the Student enters email, password, and password confirmation and submits. The button shows an inline progress state and the fields disable.
5. Observable result: the account is created, a session is established, and the Student lands in the Library with an empty-state prompt inviting them to drop files or paste a link.
6. Failure/recovery: if the email is already registered or the password is weak or mismatched, inline field messages appear and the entered values are preserved; the Student corrects the field and resubmits.
7. Continuation: the Student proceeds to Flow 2.

Flow 2 — Uploading study material

1. From the Library, the Student drags several files (a PDF, a DOCX, a PPTX, a TXT, an MD, and a scanned image) onto the upload zone.
2. Each file appears with its own progress bar. The scanned image is processed with OCR so its text becomes usable.
3. Observable result: as each file completes, it settles into the file list and the persistent left sidebar as a cream sheet with a 1px bottom rule, a Fraunces italic filename, and a small sage checkbox.
4. Failure/recovery: if one file has an unsupported type or is oversized, a clear per-file error message appears with a retry affordance, and the other files in the batch are unaffected. The Student retries or removes the failed file.
5. The Student checks three files in the sidebar. The sidebar header reads "3 sources in context" in Fraunces italic.
6. Continuation: the Student moves to Chat, Summaries, or Quiz with that context intact. On a phone, the Student taps the "Files (3 selected)" bar to open the bottom-sheet drawer and selects files there instead.

Flow 3 — Summarizing a link

1. From Summaries, the Student pastes a YouTube lecture URL into the link input and submits.
2. The backend extracts the transcript. Skeleton blocks render for each summary section while generation runs.
3. Observable result: four sections render — a short summary, key points, key terms, and an "explain like I'm new to this" version — and the summary is saved to the library like a normal file, appearing in the sidebar.
4. Failure/recovery (platform blocks extraction): the exact message "We couldn't read this link. Paste the text or transcript instead." appears with a paste-text area. The Student pastes the transcript and regenerates; the summary is produced from the pasted text.
5. Failure/recovery (invalid or unreachable URL): a clear message appears with retry; the Student corrects the URL.
6. Continuation: the Student reads the summary, opens its visuals (Flow 4), or checks the saved summary as active study context.

Flow 4 — Reading and downloading visuals

1. With a summary open on Summaries, the best-fit visuals render automatically: a concept map, a flowchart, a timeline, a comparison table, and a chart for the numeric data in the material. Diagrams render in ink-on-paper with sage and mist-blue strokes; charts use Recharts.
2. Each visual carries a plain-language caption in 13px Manrope muted.
3. Observable result: the Student reads the visuals and understands the structure of the material without decoding it.
4. The Student presses the download control on the chart. A PNG is produced.
5. Failure/recovery: if a visual fails to render, a clear message appears in its place with retry, and the summary text remains readable. If the PNG export fails, a clear message offers retry.
6. Continuation: the Student returns to the summary or moves to Chat or Quiz.

Flow 5 — Asking your notes

1. From Chat, with three files selected as active study context, the Student types a question and sends it.
2. The answer streams in token by token with a quiet inline indicator, rendered as markdown.
3. Observable result: the completed answer carries mist-blue source chips reading e.g. "p. 4 · lecture-03.pdf".
4. The Student clicks a source chip. The source panel scrolls to the passage and briefly underlines it in sand (#F3E8D2).
5. Failure/recovery: if no study context is selected, a clear message asks the Student to select files. If the stream breaks, the partial answer is preserved and a clear message offers retry.
6. Continuation: the Student asks a follow-up question or moves to Quiz.

Flow 6 — Taking a quiz

1. From Quiz, with the three selected files as context, the Student chooses medium difficulty and a count of 20, leaves the optional timer toggle off, and generates.
2. Skeleton question cards render while generation runs. Observable result: a 20-question quiz renders with a mix of multiple choice, true/false, fill-in-the-blank, and short answer. No timer is shown.
3. The Student answers a multiple choice question and submits. Observable result: instant feedback appears — correctness, an explanation, and the source passage with a source chip. The Student continues through the remaining questions.
4. On completion, the results screen renders: a 180px score ring with a 6px sage stroke on a #DDD6C8 track and the score in Fraunces italic at 64px, plus a weak-topic breakdown chart.
5. The Student presses "retry only the ones I missed". Observable result: a new attempt contains only the previously missed questions.
6. Failure/recovery: if generation fails or the selection is empty, a clear message appears with retry. If submission fails, the Student's answers are preserved and they can retry without losing work.
7. Continuation: the Student reviews the updated results or starts a fresh quiz. If they had enabled the optional timer, it would have run for the attempt; with it off, no time pressure applied.

Flow 7 — Taking a brain break

1. From Mind Games, the Student sees the grid of brain-break cards on soft sand (#F3E8D2) grounds with sage hover, each naming one game and its 1-to-3-minute length, under a full-bleed photographic still-life opener.
2. The Student opens the guided breathing bubble. A single mist-blue circle grows from 96px to 220px over 4s inhale / 2s hold / 6s exhale, with the word "inhale" in Fraunces italic inside it.
3. Observable result: after the cycle the game ends gently — no score, no leaderboard, no harsh sound.
4. The Student returns to the grid and opens the word-scramble, which presents scrambled versions of their own key terms from their notes.
5. Failure/recovery: if no key terms exist yet, a calm note explains that the game unlocks once notes or summaries exist, and the other games remain available. If a game fails to initialize, a clear message offers retry.
6. Continuation: the Student returns to study work or takes another break.

Flow 8 — Focus mode with Pomodoro and ambient sound

1. From any study tab, the Student clicks the focus mode toggle. The chrome dims over 800ms.
2. Observable result: a full-bleed slate #2F3E46 takeover with a single cream task card centred at max-width 640px. Everything except the current task is hidden.
3. The Student enables the Pomodoro timer. A 1px cream rule fills left-to-right over 25 minutes with the remaining minutes in Fraunces italic. At the end, a 440Hz sine chime at 20% volume sounds — never a beep.
4. The Student enables ambient sounds and chooses rain, then adjusts the volume slider. The sound plays at the chosen volume. (Ambient sounds are off by default.)
5. Failure/recovery: if audio is unavailable, a clear note explains it; the visual timer still runs and the end is marked visually.
6. Continuation: the Student takes the 5-minute break or continues, then exits focus mode to return to the workspace.

Flow 9 — Returning to saved work

1. The Student returns to DocuMindRAG and lands on the Welcome page.
2. The Student presses "Start studying" and is routed to Login because they already have an account.
3. The Student enters email and password and submits.
4. Observable result: the session is restored and the Student lands in the Library with their previously uploaded files, saved link summaries, and study records intact.
5. Failure/recovery: incorrect credentials or a network failure produce a calm form-level message with retry; no field is silently cleared and there is no lockout or pressure language.
6. Continuation: the Student selects files and resumes studying.

Flow 10 — Reduced-motion and low-power experience

1. A Student whose system has prefers-reduced-motion active opens the Welcome page.
2. Observable result: the 3D scene is removed entirely and replaced by the static 2D cream-to-sand gradient with flat SVG silhouettes of the open book, folded note, and pale wooden cube. All transitions reduce to instant opacity swaps.
3. On a low-power device without reduced motion, the same static 2D gradient renders instead of the 3D scene.
4. Observable result: the Student uses the full product — upload, summaries, chat, quiz, mind games, focus mode — with no loss of function and no motion.
5. Continuation: the Student studies normally.

6. Visuals Colors and Theme

The creative direction is authoritative for this section: Emptiness as a study desk — quiet after Kenya Hara. The headline is Study in peace. The muse is Kenya Hara: vast quiet space, one calm subject, paper-white and unbleached grounds, whispering type, almost no motion. The emotional register is calm, warm, slightly monastic — a desk lamp, a stack of paper, a breath between sessions.

Color tokens (light mode)

Sage is the single functional signal and is used sparingly — one sage element per screen region, never as a large flood except the "Start studying" button and the score ring. Mist blue is reserved for source chips, chat citations, and quiz explanation panels. Soft sand is a whisper only. No neon, no pure black (#000), no pure white (#FFF).

Color tokens (dark "night study" theme)

Never #000.

Typography

• Headings: Fraunces — italic, low-contrast optical size, weight 400–500 (never bold), tracking −0.01em. Sentence case, not uppercase. Section titles are small (24–32px) and sit in lots of air; the scale contrast comes from the hero, not from every heading.
• Body: Manrope.
• Scale (1.333 modular): 64 / 48 / 32 / 24 / 18 / 16 / 14.
• Hero display: clamp(40px, 9vw, 88px) Fraunces italic 400.
• Section heading: clamp(24px, 4vw, 32px).
• Body: 16px / 1.7 Manrope 400.
• UI labels: 14px Manrope 500 with 0.06em tracking.
• Captions: 13px Manrope 400 muted.
• Numbers and scores: Fraunces italic at 2× the label size for editorial weight.
• Wordmark: "DocuMindRAG" in Fraunces italic with "RAG" in sage.

Shape language

Square and softly-rounded rectangles only — 12px on chips and inputs, 16px on cards and quiz panels, 20px on the welcome hero card and modals. No blobs, no capsules, no pill buttons except the single sage "Start studying" button. Hairline 1px rules in #DDD6C8 separate sections instead of shadows wherever possible; when a shadow is needed it is soft, slate-tinted, and low (0 8px 24px rgba(47,62,70,0.06)). Generous internal padding (24–32px) so cards feel like sheets of paper, not tiles.

Spacing rhythm

A 12-column grid with a wide 96px outer margin on desktop, collapsing to 24px on mobile. Spacing tokens follow a 4px base: --space-1: 4px, --space-2: 8px, --space-3: 12px, --space-4: 16px, --space-6: 24px, --space-8: 32px, --space-12: 48px, --space-16: 64px, --space-24: 96px. The welcome page is a single centred column: wordmark, one italic headline, one paragraph, one button, and the 3D still-life floating behind at 30% opacity. The app shell is a persistent 280px left sidebar and a main column holding one tab at a time, switched by a horizontal tab row with a sage underline, not by cards. Every screen shows exactly one primary action.

Imagery style

One photographic still-life per major surface: a warm-lit desk with an open book, a folded note, a cup, and a small geometric object (a wooden cube, a stone) — shot on cream, soft directional light, no people, no props with logos. These are used as full-bleed section openers in Summaries and Mind Games, and as the 3D scene's reference. Elsewhere, imagery is generative and quiet: thin ruled lines, faint grid paper texture at 4% opacity, and Mermaid diagrams rendered in ink-on-paper with sage and mist-blue strokes. No stock photos, no illustrations of people, no gradient blobs.

Accessibility

WCAG AA contrast throughout, visible keyboard focus rings, alt text on images, and screen-reader labels on controls. All colors and spacing are defined as CSS variables.

7. Signature Design Concept

The quiet desk, composed. The Welcome page is a full-viewport warm-cream field (#F4F1EA) with a single centred column of type occupying the left-of-centre 7 columns — asymmetric, typographic, and quiet. Above the headline sits a small 14px Manrope label "DOCUMIND RAG" in 0.14em tracking. The headline is "Study in peace." set in Fraunces italic at clamp(40px, 9vw, 88px), deep slate, two lines maximum, with the word "peace" in sage. Below it, one 18px muted line and one sage "Start studying" button (16px radius, 20px 32px padding).

Behind and to the right, a lazy-loaded React Three Fiber still-life: three softly-lit objects — an open book, a folded paper note, and a pale wooden cube — floating at 0.4 units of vertical drift, lit by one warm directional light and a soft cream environment, rendered at a 30fps cap. It never takes focus, never spins, and mouse-parallax moves it ±8px. On reduced-motion or low-power devices the scene is replaced by a static 2D gradient (cream → sand) with the same three objects as a flat SVG silhouette.

Below the fold, three feature cards sit as sheets of paper — 16px radius, hairline rules, generous padding — each tilting at most 3° on hover over 500ms. There is no blue button, no centred "hero + subtext + gradient blob"; the composition is asymmetric, typographic, and quiet. The concept recomposes only accepted content, states, and controls: the wordmark, the headline, the supporting line, the "Start studying" button, the three feature cards, and the decorative still-life.

8. Interaction Model & Motion Direction

Interaction Model: Static (direction) Motion Tempo: still Hero Dimensionality: flat

The direction's tempo is stillness first. Page transitions are a 600ms ease-in-out crossfade with a 12px upward drift, nothing more. The 3D scene drifts at 0.05 rad/s with mouse-parallax clamped to ±8px; nothing spins, nothing bounces. Cards tilt at most 3° on hover over 500ms. Focus mode dims the chrome over 800ms. prefers-reduced-motion removes the 3D scene entirely (renders the static 2D cream-to-sand gradient) and reduces all transitions to instant opacity swaps. All motion uses ease-in-out within 400–800 ms; nothing spins fast, flashes, or shakes.

Landing Hero Motion Brief

• Focal subject: the three-object still-life — an open book, a folded paper note, and a pale wooden cube — floating in a warm-lit cream space, drawn from the direction's imagery and hero direction.
• Input → transformation → outcome thesis: as the pointer moves across the hero, the still-life's parallax offset shifts by at most ±8px and the objects drift vertically by 0.4 units at 0.05 rad/s; the outcome is a slow, breathing sense of depth behind the type — the desk is alive but never demands attention. No accepted behavior is added; the scene is decoration only.
• Motion vocabulary: slow vertical drift, clamped mouse-parallax, one warm directional light, a soft cream environment, a 30fps cap. Nothing spins, bounces, flashes, or shakes.
• Composed first frame: the warm-cream field fills the viewport; the typographic column sits left-of-centre in the 7 columns; the still-life floats behind and to the right at 30% opacity; the sage "Start studying" button anchors the column's base.
• Reduced-motion state: the 3D scene is removed entirely and replaced by the static 2D cream-to-sand gradient with flat SVG silhouettes of the same three objects; all transitions become instant opacity swaps.

9. Non-Functional Requirements

NFR-1 — Secret handling (explicit) The Groq API key must be loaded from .env and never exposed to the frontend. No hardcoded secrets anywhere in the codebase. A .env.example must be provided. Rationale: explicit hard constraint; protects the student's use of the product and the operator's key.

NFR-2 — 3D is decoration only (explicit) The 3D is decoration only; the study tools (upload, quiz, chat) must always be fast and 2D. Rationale: explicit hard constraint; keeps study work responsive regardless of scene state.

NFR-3 — Reduced motion (explicit) Respect prefers-reduced-motion: disable 3D and animations and show a static version. Rationale: explicit hard constraint; accessibility and comfort.

NFR-4 — 3D performance (explicit) Lazy-load the 3D scene, cap the frame rate (30fps), and fall back to a 2D gradient on low-power devices. Rationale: explicit hard constraint; keeps the welcome page fast on modest hardware.

NFR-5 — Motion character (explicit) Motion must feel slow and soothing (ease-in-out, 400 to 800 ms); nothing spins fast, flashes, or shakes. Rationale: explicit hard constraint; the product promise is calm.

NFR-6 — Palette restrictions (explicit) The palette must avoid neon, pure black, and pure white; the dark "night study" theme must never use pure black. Rationale: explicit hard constraint; protects the warm, paper-and-ink register.

NFR-7 — CSS variables (explicit) All colors and spacing must be defined as CSS variables. Rationale: explicit hard constraint; enables the optional dark theme and consistent spacing.

NFR-8 — Accessibility (explicit) WCAG AA contrast, visible keyboard focus rings, alt text, and screen-reader labels. Rationale: explicit hard constraint; the product must be usable regardless of ability.

NFR-9 — Quiz minimum (explicit) Quiz must generate a minimum of 15 questions per quiz, default 20. Rationale: explicit hard constraint; guarantees a meaningful self-test.

NFR-10 — Brain-break character (explicit) Mind games must be short (1 to 3 minutes), with no harsh sounds, no leaderboards, and no pressure. Rationale: explicit hard constraint; breaks must actually rest the student.

NFR-11 — Ambient sounds default (explicit) Ambient sounds are off by default. Rationale: explicit hard constraint; no unexpected audio.

NFR-12 — Quiz time pressure (explicit) Quizzes have no time pressure by default; the timer is an optional toggle. Rationale: explicit hard constraint; the product must not pressure the student.

NFR-13 — Backend validation and errors (explicit) The backend must validate file types and size and handle errors with clear messages. Rationale: explicit hard constraint; failures must be understandable.

NFR-14 — CORS (explicit) Enable CORS for the frontend origin. Rationale: explicit hard constraint; required for the frontend to reach the backend.

NFR-15 — Responsiveness (explicit) Fully responsive across desktop, tablet, and phone. Rationale: explicit hard constraint; students study on many devices.

NFR-16 — README (explicit) The README must include setup steps for both frontend and backend using Windows PowerShell commands. Rationale: explicit hard constraint; the product must be runnable locally.

NFR-17 — Code quality (explicit) Clean, commented, modular code with a clear folder structure. Rationale: explicit hard constraint; maintainability.

NFR-18 — Screen states (explicit) Loading skeletons, empty states, and error states for every screen. Rationale: explicit hard constraint; the student must always know what is happening.

NFR-19 — Durable records (required_inference) Uploaded files and generated summaries must persist as durable application records bound to the verified student. Rationale: indispensable for the accepted study lifecycle to survive across sessions.

NFR-20 — Backend execution (required_inference) Backend execution is required for file processing, OCR, retrieval, AI generation, streaming chat, quiz evaluation, and durable library operations. Rationale: indispensable for the accepted capabilities; the frontend never holds the AI key.

10. Tech Stack

Frontend (explicit)

• React + Vite (JavaScript)
• Plain CSS with design tokens (CSS variables)
• Three.js via @react-three/fiber and @react-three/drei for the welcome 3D still-life
• Framer Motion for UI transitions
• Recharts for charts
• Mermaid for diagrams

Backend (explicit)

• Python FastAPI
• SQLite
• Groq API for AI, with the key loaded from .env and never exposed to the frontend

Retrieval (explicit)

• RAG pipeline: chunk uploaded content, embed it, retrieve relevant chunks, and answer with source references

Delivery (explicit)

• Fully responsive across desktop, tablet, and phone
• CORS enabled for the frontend origin
• File type and size validation with clear error messages
• .env.example provided; no hardcoded secrets
• README with setup steps for both frontend and backend using Windows PowerShell commands

11. Assumptions and Constraints

Assumptions

• A-1 (required_inference) — The application owns identity because the student's uploaded files, generated summaries, quiz results, and study history are durable personal records that must remain bound to the correct participant. First-use enrollment happens on Sign Up and returning verification on Login; both are anonymously reachable, and the protected study destinations require a verified session.
• A-2 (required_inference) — No differentiated permissions, roles, or role-based visibility are established. Every authenticated student sees only their own study workspace.
• A-3 (basic_default) — The Groq API is the AI provider behind the backend; the frontend never holds the key. If the key is missing, the backend returns a clear error rather than failing silently.
• A-4 (basic_default) — Link extraction depends on third-party platforms and may be blocked; the product's accepted response is the friendly fallback and the paste-text path, not a guarantee of extraction.
• A-5 (basic_default) — OCR, chunking, embedding, retrieval, streaming, and quiz evaluation are backend system processes with no separate human-facing surface.
• A-6 (basic_default) — The optional dark "night study" theme, the optional Pomodoro timer, the optional quiz timer toggle, and the optional ambient sounds are current optional features, off or inactive by default.
• A-7 (basic_default) — The word-scramble draws on the student's own key terms from their notes; if none exist yet, the game is unavailable with a calm explanation while the other games remain available.

Constraints

• C-1 (explicit) — Groq API key must be loaded from .env and never exposed to the frontend; no hardcoded secrets; provide a .env.example.
• C-2 (explicit) — The 3D is decoration only; the study tools (upload, quiz, chat) must always be fast and 2D.
• C-3 (explicit) — Respect prefers-reduced-motion: disable 3D and animations and show a static version.
• C-4 (explicit) — Lazy-load the 3D scene, cap the frame rate, and fall back to a 2D gradient on low-power devices.
• C-5 (explicit) — Motion must feel slow and soothing (ease-in-out, 400 to 800 ms); nothing spins fast, flashes, or shakes.
• C-6 (explicit) — Palette must avoid neon, pure black, and pure white; the dark "night study" theme must never use pure black.
• C-7 (explicit) — All colors and spacing must be defined as CSS variables.
• C-8 (explicit) — Accessibility: WCAG AA contrast, visible keyboard focus rings, alt text, screen-reader labels.
• C-9 (explicit) — Quiz must generate a minimum of 15 questions per quiz, default 20.
• C-10 (explicit) — Mind games must be short (1 to 3 minutes), with no harsh sounds, no leaderboards, and no pressure.
• C-11 (explicit) — Ambient sounds are off by default.
• C-12 (explicit) — Quizzes have no time pressure by default; the timer is an optional toggle.
• C-13 (explicit) — Backend must validate file types and size and handle errors with clear messages.
• C-14 (explicit) — Enable CORS for the frontend origin.
• C-15 (explicit) — Fully responsive across desktop, tablet, and phone.
• C-16 (explicit) — README must include setup steps for both frontend and backend using Windows PowerShell commands.
• C-17 (explicit) — The generic indigo/blue-on-white SaaS template is forbidden for this project.
• C-18 (explicit) — Readable text and needed content stay whole at every viewport: headlines, wordmarks, labels, numbers, item images, cards, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling to fit, with no other element covering any part of them. Crops, bleeds, and off-edge placement are for decoration only. Moving and scrollable content may cross the viewport or container edge by design, judged by whether it actually moves or scrolls and whether every item becomes fully readable as it passes; with prefers-reduced-motion it stops and shows whole items, wrapping into rows or sitting in a horizontally scrollable row whose further items are reached by scrolling.

12. Glossary

• Active study context — The set of one or many files or saved summaries the student has checked in the sidebar; it grounds Summaries, Chat, and Quiz.
• Brain break — A short (1 to 3 minute), pressure-free mind game or breathing exercise taken between study sessions.
• Concept map — A best-fit visual showing relationships between ideas in a summary.
• DocuMindRAG — The product; the wordmark is set in Fraunces italic with "RAG" in sage.
• Focus mode — A one-click full-bleed slate takeover that hides everything except the current task, optionally with a Pomodoro timer and ambient sounds.
• Groq API — The AI provider behind the backend; its key is loaded from .env and never exposed to the frontend.
• Key terms — The important vocabulary extracted from a summary; also the source for the word-scramble game.
• Mind Games — The tab holding the guided breathing bubble, memory card match, sliding puzzle, Zen sand-draw or bubble-pop, and word-scramble.
• Night study theme — The optional dark theme using deep slate and muted sage, never pure black.
• OCR — Optical character recognition; turns images and scans into usable text.
• Pomodoro timer — The optional 25/5 focus timer with a gentle 440Hz sine chime at 20% volume, never a beep.
• RAG pipeline — Retrieval-augmented generation: chunk uploaded content, embed it, retrieve relevant chunks, and answer with source references.
• Score ring — The 180px results ring drawn with a 6px sage stroke on a #DDD6C8 track, with the score in Fraunces italic at 64px.
• Source chip — A mist-blue marginalia chip (#8FB3CC at 12% fill, 1px border, 13px Manrope) reading e.g. "p. 4 · lecture-03.pdf"; clicking it scrolls the source panel and briefly underlines the passage in sand.
• Still-life — The photographic or 3D composition of a warm-lit desk with an open book, a folded note, a cup, and a small geometric object; no people, no logos.
• Weak-topic breakdown — The results chart showing which topics the student answered poorly, used to guide retry and review.