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.
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:
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.
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.
No reference directive with content_source authority was supplied; no source content inventory is included.
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).AuthSheet (shared shell for Sign Up and Login), CredentialForm (validation, inline field errors), PasswordField (visibility toggle, screen-reader label).AuthSheet, CredentialForm, PasswordField.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.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.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").ChatThread (markdown rendering, streaming append), ChatComposer (multiline input, send), SourceChipRow (per-answer citations), ContextIndicator (which files ground the answer).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.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.BrainBreakGrid (sand-ground cards, sage hover), BreathingBubble, MemoryMatch, SlidingPuzzle, ZenSandDraw or BubblePop, WordScramble (key-term source), GameShell (quiet exit, no score pressure).Each story point carries provenance: explicit (source-stated), basic_default (accepted default), or required_inference (indispensable inferred mechanics).
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.
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.
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.
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.
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.
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.
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.
FR-8 — Delete a file (explicit) As a Student, I should be able to delete a file so that my library stays clean.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
FR-29 — Streaming answers (explicit) As a Student, I should see answers stream in so that I can start reading immediately.
FR-30 — Markdown rendering (explicit) As a Student, I should have answers rendered as markdown so that structure, lists, and emphasis are readable.
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.
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.
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.
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.
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.
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.
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.
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.
prefers-reduced-motion media query being active.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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
.env server-side; the frontend bundle contains no key; .env.example documents the required variables..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.
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.
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.
.env setup and common failure causes.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.
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.
prefers-reduced-motion active opens the Welcome page.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.
| Role | Token | Value |
|---|---|---|
| Page ground (60%) | --color-bg | #F4F1EA |
| Sheet — cards, sidebar, modals, quiz panels (25%) | --color-surface | #FBF9F4 |
| Body and heading ink | --color-text | #2F3E46 |
| Captions, metadata, timestamps, empty-state copy | --color-muted | #6B7C85 |
| Primary signal — buttons, active tab underline, score ring, progress fill | --color-primary | #7FA99B |
| Primary hover | --color-primary-hover | #5B8C7D |
| Secondary signal — source chips, chat citations, quiz explanation panels | --color-accent | #8FB3CC |
| Whisper — sidebar row hover wash, quiz option hover, brain-break card tint | --color-sand | #F3E8D2 |
| Hairline rules | --color-rule | #DDD6C8 |
| Soft shadow | --shadow-soft | 0 8px 24px rgba(47,62,70,0.06) |
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).
| Role | Token | Value |
|---|---|---|
| Page ground | --color-bg | #222E33 |
| Sheet | --color-surface | #2A373D |
| Ink | --color-text | #EDE9E0 |
| Muted | --color-muted | #9AA8AE |
| Primary | --color-primary | #6F9A8D |
| Accent | --color-accent | #8FB3CC |
| Sand | --color-sand | #3A3A32 |
| Rule | --color-rule | #3C4A50 |
Never #000.
clamp(40px, 9vw, 88px) Fraunces italic 400.clamp(24px, 4vw, 32px).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.
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.
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.
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.
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.
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.
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.
Frontend (explicit)
@react-three/fiber and @react-three/drei for the welcome 3D still-lifeBackend (explicit)
.env and never exposed to the frontendRetrieval (explicit)
Delivery (explicit)
.env.example provided; no hardcoded secretsAssumptions
Constraints
.env and never exposed to the frontend; no hardcoded secrets; provide a .env.example.prefers-reduced-motion: disable 3D and animations and show a static version.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..env and never exposed to the frontend.No completed page designs yet.
Completed design pages will appear here when they are ready to preview.
No completed page designs yet.
Completed design pages will appear here when they are ready to preview.
No comments yet. Be the first!