System Requirements Document for studysprint-students

1. Introduction

studysprint-students is a mobile-first web application for high-school students in the Philippines that turns one uploaded PDF — class notes, a textbook chapter, or lecture material — into three study tools automatically: an easy-to-understand study guide, a set of flashcards for active recall, and a quiz to test understanding after reviewing. The product is delivered under the working name DocFlash.

The problem this product addresses is that students spend hours reading PDFs, textbooks, and lecture notes but often struggle to remember the information, and creating flashcards and practice quizzes manually takes even more time. The product's intent is to remove that manual preparation work so a student can move directly from raw course material to active study.

The audience is high-school students, initially in the Philippines, studying on mobile-first web browsers. The business model is free initially. The first release is deliberately narrow: it proves that students can upload their materials and use the generated learning tools to prepare more effectively for real exams, rather than attempting to be a full AI tutor or an elaborate learning-management system.

2. System Overview

DocFlash is a responsive web application with an application-owned student identity, private document storage, and a server-side generation pipeline. A student creates an account, uploads a PDF, and the system extracts the document's text (applying OCR when the PDF is scanned), then generates a study guide, flashcards, and a quiz that are grounded in that document. The student reads the guide, reviews the flashcards — revealing answers and marking concepts they find difficult — takes the quiz, and lands on a results page showing the score and the topics to review.

The single active human actor is the Student. The AI generation service, the PDF text-extraction/OCR component, the private file store, and the persistent database are non-persona system and provider actors that support the student's work; they do not act on their own behalf.

Current scope is the five must-have capabilities — PDF upload, AI study guide, flashcards, quiz generator, and results page — plus the identity and persistence needed to make that workflow usable and resumable. Explicitly deferred to a next version are saved study sets for revisiting previous materials and spaced repetition that schedules reviews based on recall performance. Explicitly out of scope for the first release are a full AI tutor, an elaborate learning-management system, social feeds, followers and leaderboards, video lessons or a full online classroom, an elaborate AI chatbot, complex calendars and school-management systems, and paid subscriptions before demand is validated.

2a. Product Interpretation and Delivery Boundary

DocFlash is delivered as a first-party, mobile-friendly responsive web application. There is no separate Android or iOS application; the mobile-first web app is the delivery surface, which lets the team test the idea without paying to build separate native apps.

Access is application-owned. Because the product stores a student's uploaded documents and generated study materials privately and lets them return to continue a study workflow, the student establishes their own identity on first use and verifies it on return. The public entry surface and the two identity surfaces are reachable without being signed in; the upload, study guide, flashcards, quiz, and results surfaces require a signed-in student, because each one reads or writes state that belongs to that specific student's private document.

The generation pipeline is server-side and provider-backed: text extraction (with OCR for scanned PDFs) and AI generation with structured output run behind the application, not in the browser. The uploaded file itself is held in private cloud storage and is never publicly addressable.

Current versus future boundary: everything described in this document is current MVP scope. Saved study sets and spaced repetition are next-version features and are not built, surfaced, or accepted in this release. The product is free initially; no paid subscription, entitlement, or billing behavior exists in this release.

2b. Source Content Inventory

The authoritative sources for this project are product plans and an interface demonstration, not a populated content collection. The only concrete content facts supplied are the demonstration study set used to illustrate the flashcard and quiz experience:

• Demo study set title: Biology — Photosynthesis
• Demo study set label: Demo study set · Not extracted from an uploaded PDF
• Demo flashcard, Card 1 of 3 (33% reviewed): QUESTION — "What is the main function of chlorophyll?" with a Reveal answer control and Previous / Next card navigation.

This demonstration content is sample biology content only. It is not extracted from an uploaded PDF, and it is not seeded product data. No other verified factual entities, collections, fields, values, dates, contacts, links, or media references were supplied.

2c. Page Content and Component Coverage

Landing

• Information and state: Anonymous public entry. Explains what DocFlash is and the workflow it performs — one PDF becomes a study guide, flashcards, and a quiz. Presents the product as a desk with a stack of cards on it rather than a marketing hero.
• Primary action: Choose a PDF (routes an unauthenticated visitor into identity establishment, then to Upload).
• Supporting actions: Navigate to Sign Up; navigate to Login.
• Domain entities: Product description, workflow steps (Upload · Review · Quiz), pixel document pictogram, fanned preview cards (a flashcard question, a quiz option row, a filled progress grid).
• Component responsibilities: Compact pine header bar with the Silkscreen wordmark and the three-square step row; a single large drop card offset left containing the 96px pixel document pictogram, the headline "Turn one PDF into a study guide, flashcards, and a quiz.", a muted subline naming the workflow, and one pine pill button with a small orange arrow chip; three smaller white cards fanned behind and to the right, cropped by the right viewport edge on mobile and fully visible at 1280px.
• States: Loading — not applicable (static entry). Empty — not applicable. Success — the entry renders and both identity routes are reachable. Error — not applicable. Recovery — not applicable.

Sign Up

• Information and state: Anonymous first-use enrollment surface for a student who has no account yet. Explains that an account is what keeps uploaded documents and generated study materials private and available on return.
• Primary action: Create the student's account and enter the signed-in application.
• Supporting actions: Navigate to Login if the student already has an account; return to Landing.
• Domain entities: Student identity (credential and profile fields as required for enrollment), enrollment confirmation state.
• Component responsibilities: Enrollment form with 2px ink borders and 4px radii; inline field-level validation messages; one pine pill primary submit button; a link to Login.
• States: Loading — submit in progress with the primary button in a pending state. Empty — the form renders with empty fields. Success — the account is created and the student is placed into the signed-in application. Error — invalid or already-used credentials, or a failed enrollment request, shown inline with the form preserved so the student can correct and resubmit. Recovery — the student corrects the flagged field and resubmits, or switches to Login.

Login

• Information and state: Anonymous returning-verification surface for a student who already has an account and needs to reach their own uploaded documents and generated study materials.
• Primary action: Verify the student's identity and enter the signed-in application.
• Supporting actions: Navigate to Sign Up if the student has no account; return to Landing.
• Domain entities: Student credentials, verification result.
• Component responsibilities: Credential form with 2px ink borders and 4px radii; inline error messaging; one pine pill primary submit button; a link to Sign Up.
• States: Loading — verification in progress with the primary button in a pending state. Empty — the form renders with empty fields. Success — the student is verified and returned to the protected work they were attempting. Error — unrecognized or incorrect credentials, shown inline without disclosing which field was wrong. Recovery — the student retries, or switches to Sign Up.

Upload

• Information and state: The signed-in student's working desk for a single document. Shows the selected file, its processing state, and the outcome of extraction. This is the entry point of the Upload → Study Guide → Flashcards → Quiz → Results workflow.
• Primary action: Choose a PDF and start processing it.
• Supporting actions: Replace the selected file before processing; retry a failed extraction; continue to the Study Guide once generation completes.
• Domain entities: Uploaded PDF (file name, page count, thumbnail of the document's first page as a small 1px-border artefact in the study-set rail), extraction status, OCR-applied indicator, processing error, generated study set (study guide, flashcards, quiz).
• Component responsibilities: Drop/choose card with the pixel document pictogram; file summary row; processing indicator drawn as the discrete square grid rather than a smooth bar; error panel with a plain-language explanation and a retry control; the "not enough information" state rendered with the shrugging pixel figure when the document cannot support generated questions.
• States: Loading — extraction and generation in progress, with the step row showing Upload complete and Review pending. Empty — no file selected yet, showing the empty card slot and the Choose a PDF control. Success — text extracted (OCR applied if the PDF was scanned) and the study guide, flashcards, and quiz are ready, with a control to continue to the Study Guide. Error — the file is not a PDF, the file cannot be read, extraction fails, or the document yields too little text; each is shown as a specific, plain-language message with a retry path. Recovery — the student replaces the file or retries extraction without losing their place in the workflow.

Study Guide

• Information and state: The generated, organized explanation of the uploaded document: summaries, key terms, definitions, and topic sections, written in clear language. Presented as a reading column that is never wider than 62 characters.
• Primary action: Read the guide and continue to Flashcards.
• Supporting actions: Move between topic sections; return to Upload to process a different document.
• Domain entities: Study guide sections, key terms, definitions, topic headings, source document reference.
• Component responsibilities: Reading column at 17px/1.65 with a 62-character measure; section headings in IBM Plex Sans (never Silkscreen for prose); the study-set rail on wider viewports showing document name, page count, and the vertical square card index; a continue control to Flashcards.
• States: Loading — generation in progress, with the step row showing Upload complete and Review active. Empty — not reachable without a processed document; a student arriving without one is returned to Upload. Success — the guide renders in full with all topic sections readable. Error — generation failed or the document did not contain enough information to build a guide; the app says so plainly and offers a retry or a different document. Recovery — retry generation, or return to Upload and choose another PDF.

Flashcards

• Information and state: The active-recall surface. Shows one generated question-and-answer card at a time, the card's position in the set (for example "Card 1 of 3"), and the review progress as a row of discrete squares.
• Primary action: Reveal the answer to the current card.
• Supporting actions: Move to the previous card; move to the next card; mark the current concept as difficult; continue to the Quiz when the set is finished.
• Domain entities: Flashcard (question, answer, explanation), card index, review progress, difficult-concept marks.
• Component responsibilities: The flashcard as a physical object — true-white surface, 2px ink border, 8px radius, question in 700-weight Plex at clamp(20px, 5.2vw, 28px); a pine Reveal answer button; Previous and Next card controls; the card-index chip carrying the single orange accent; the progress square row; the pixel student spot mark beside the encouragement line.
• States: Loading — cards are being generated, with the step row showing Review active. Empty — the document did not yield enough information to build cards; the shrugging pixel figure and a plain statement are shown with a path back to Upload. Success — the student reveals answers, advances through the set, and marks difficult concepts, with progress squares filling one at a time. Error — generation failed or a card could not be produced; the app states this and offers a retry. Recovery — retry generation, or return to Upload with a different document.

Quiz

• Information and state: The assessment surface. Presents document-grounded questions one per screen, mixing multiple-choice and short-answer, and shows the student's position in the quiz.
• Primary action: Answer the current question and advance.
• Supporting actions: Select one of four full-width answer rows for a multiple-choice question; type a short answer; move to the next question; finish the quiz and go to the Results page.
• Domain entities: Quiz question (multiple-choice or short-answer), answer options, student response, per-question explanation, insufficient-source-information notice.
• Component responsibilities: One question per screen; four full-width answer rows at 48px minimum height, thumb-reachable; a short-answer input with 2px ink border and 4px radius; the question-mark-in-square pixel pictogram and an orange "not enough info" badge when the uploaded PDF does not contain enough information to answer a question; the progress square row showing quiz length.
• States: Loading — questions are being generated, with the step row showing Review active. Empty — the document did not yield enough information to build a quiz; the app says so plainly and offers a path back to Upload. Success — every question is answered and the student is taken to the Results page. Error — generation failed, or a question cannot be answered from the source document and is explicitly flagged as such rather than answered speculatively. Recovery — retry generation, or return to Upload with a different document.

Results page

• Information and state: The completion surface. Shows the quiz score and the topics to review, derived from the student's performance on the generated quiz.
• Primary action: Review the weak topics and decide what to revisit.
• Supporting actions: Return to the Study Guide or Flashcards for the same document; return to Upload to process another PDF.
• Domain entities: Quiz score, per-question outcomes, weak-topic list with miss rates, source document reference.
• Component responsibilities: Score block with the score counting up in whole numbers; a wrapping horizontal array of weak-topic chips, each carrying a small orange fill bar whose width is the topic's miss rate — the only place the orange accent appears at scale; the study-set rail gaining the topics-to-review list at 1280px.
• States: Loading — the score is being computed. Empty — no quiz has been completed for this document; the student is directed back to the Quiz. Success — the score and the weak-topic chips render, and the chips wrap rather than scrolling away. Error — the score could not be computed; the app states this and offers a retry. Recovery — retry, or return to the Quiz or Upload.

3. Functional Requirements

FR-1 — PDF upload and text extraction (explicit) As a Student, I should upload a PDF containing class notes, textbook chapters, or lecture materials so that the app can extract its text and turn it into study tools.

• Trigger/input: The student selects a PDF file on the Upload page.
• Observable result: The file is accepted, its text is extracted, and the student sees the processing state resolve into a ready study set.
• Access state: Requires a signed-in student.
• Failure/recovery: If the file is not a PDF, cannot be read, or extraction fails, the app shows a specific plain-language processing error and offers a retry or a different file.
• Continuation: The student continues to the Study Guide.

FR-2 — Scanned-PDF handling with OCR (explicit) As a Student, I should have scanned PDFs handled with OCR when needed so that a photographed or scanned chapter still produces usable study tools.

• Trigger/input: The student uploads a PDF whose text is not directly extractable.
• Observable result: OCR is applied and the extracted text is used for generation; the student can tell that OCR was applied.
• Access state: Requires a signed-in student.
• Failure/recovery: If OCR cannot recover usable text, the app reports the processing error plainly and offers a retry or a different file.
• Continuation: The student continues to the Study Guide, or replaces the document.

FR-3 — AI study guide generation (explicit) As a Student, I should receive an easy-to-understand study guide that summarizes key concepts, definitions, and explanations from my uploaded PDF so that I can read an organized version of my material instead of the raw document.

• Trigger/input: A successfully extracted document.
• Observable result: The Study Guide page presents summaries, key terms, definitions, and topic sections in clear, organized language.
• Access state: Requires a signed-in student.
• Failure/recovery: If generation fails or the document does not contain enough information, the app says so plainly and offers a retry or a different document.
• Continuation: The student continues to Flashcards.

FR-4 — Flashcard generation (explicit) As a Student, I should receive question-and-answer flashcards generated from my uploaded PDF so that I can practice active recall on the material.

• Trigger/input: A successfully extracted document.
• Observable result: The Flashcards page presents a set of question-and-answer cards with the card's position in the set and the review progress.
• Access state: Requires a signed-in student.
• Failure/recovery: If the document yields too little information to build cards, the app states this and offers a path back to Upload.
• Continuation: The student reviews the set and continues to the Quiz.

FR-5 — Flashcard review: reveal, navigate, and mark difficult concepts (explicit) As a Student, I should answer each flashcard, reveal its explanation, and mark the concepts I find difficult so that I know which material needs more attention.

• Trigger/input: The student opens a card and uses Reveal answer, Previous, Next card, and the difficult-concept mark.
• Observable result: The answer is revealed, the student advances through the set, difficult concepts are marked, and the progress squares fill one at a time.
• Access state: Requires a signed-in student.
• Failure/recovery: If a card cannot be produced from the document, the app states this rather than presenting an unsupported card.
• Continuation: The student finishes the set and continues to the Quiz.

FR-6 — Quiz generation with multiple-choice and short-answer questions (explicit) As a Student, I should receive a quiz generated from my uploaded PDF containing multiple-choice and short-answer questions so that I can test my understanding after reviewing.

• Trigger/input: A successfully extracted document.
• Observable result: The Quiz page presents document-grounded questions one per screen, with four full-width answer rows for multiple-choice questions and a text input for short-answer questions.
• Access state: Requires a signed-in student.
• Failure/recovery: If the document yields too little information to build a quiz, the app states this and offers a path back to Upload.
• Continuation: The student answers the questions and finishes the quiz.

FR-7 — Grounding in the uploaded document and insufficient-information indication (explicit) As a Student, I should have every generated question and answer grounded in my uploaded document, and I should be told when the PDF does not contain enough information to answer a question, so that I can trust the material and know its limits.

• Trigger/input: Generation of study guide content, flashcards, and quiz questions from the extracted document text.
• Observable result: Generated questions and answers correspond to the uploaded document; where the document lacks enough information, the app explicitly indicates this instead of producing an unsupported answer.
• Access state: Requires a signed-in student.
• Failure/recovery: The insufficient-information indication is itself the recovery path — the student knows the material is not covered and can return to Upload with a different document.
• Continuation: The student continues with the questions the document does support, or uploads a different PDF.

FR-8 — Quiz completion with score and explanations (explicit) As a Student, I should take the generated quiz and receive a score with explanations so that I understand what I got right and why.

• Trigger/input: The student answers the quiz questions and finishes the quiz.
• Observable result: The student's responses are scored, and explanations accompany the questions.
• Access state: Requires a signed-in student.
• Failure/recovery: If the score cannot be computed, the app states this and offers a retry.
• Continuation: The student is taken to the Results page.

FR-9 — Results page with score and topics to review (explicit) As a Student, I should see my quiz score and the topics I need to review so that I know exactly what to revisit before an exam.

• Trigger/input: Completion of a generated quiz.
• Observable result: The Results page shows the quiz score and a wrapping array of weak-topic chips, each with a fill bar whose width is that topic's miss rate.
• Access state: Requires a signed-in student.
• Failure/recovery: If no quiz has been completed for the document, the student is directed back to the Quiz; if the score cannot be computed, the app states this and offers a retry.
• Continuation: The student returns to the Study Guide or Flashcards for the same document, or uploads another PDF.

FR-10 — Student self-service enrollment (required_inference) As a Student, I should be able to create my own account on first use so that my uploaded documents and generated study materials are private to me and available when I return.

• Trigger/input: The student chooses to start on the Landing page and has no account.
• Observable result: The account is created and the student enters the signed-in application.
• Access state: The Sign Up page is reachable without being signed in; the protected pages are not.
• Failure/recovery: Invalid or already-used credentials, or a failed enrollment request, are shown inline with the form preserved so the student can correct and resubmit, or switch to Login.
• Continuation: The student proceeds to Upload.

FR-11 — Returning verification (required_inference) As a Student, I should be able to verify my identity on return so that I can continue with my own uploaded documents and generated study materials.

• Trigger/input: A returning student opens the application and needs protected work.
• Observable result: The student is verified and returned to the protected work they were attempting.
• Access state: The Login page is reachable without being signed in; the protected pages are not.
• Failure/recovery: Unrecognized or incorrect credentials are shown inline without disclosing which field was wrong; the student retries or switches to Sign Up.
• Continuation: The student resumes at Upload or at the study material they were working on.

FR-12 — Persistent storage of uploaded-document state and study workflow continuity (required_inference) As a Student, I should have my uploaded document and its generated study materials persist so that I can leave and come back without losing my work.

• Trigger/input: A successful upload and generation.
• Observable result: The document's extracted text, generated study guide, flashcards, quiz, and the student's quiz outcome are retained against that student's account.
• Access state: Requires a signed-in student; the stored state is private to that student.
• Failure/recovery: If a write fails, the app surfaces the failure rather than silently discarding the student's work.
• Continuation: The student returns later and continues from the material they had generated.

FR-13 — Private file storage for uploaded PDFs (explicit) As a Student, I should have my uploaded PDF held in private cloud storage so that my course material is not publicly accessible.

• Trigger/input: A successful upload.
• Observable result: The file is stored privately and is never publicly addressable.
• Access state: Requires a signed-in student; access to the stored file is scoped to that student.
• Failure/recovery: If storage fails, the upload is reported as failed with a retry path.
• Continuation: The student retries the upload or continues with an already-processed document.

4. User Personas

Student

Product context. A high-school student in the Philippines preparing for real exams from class notes, textbook chapters, and lecture materials that arrive as PDFs. They study on a mobile-first web browser, often on a modest Android device, and they are not looking for another notes app or a complicated AI tutor — they are looking for the fastest path from a document they already have to material they can actually be tested on.

Primary goal. Turn one uploaded PDF into a study guide, flashcards, and a quiz, work through them, and finish knowing which topics still need attention before the exam.

Distinct accepted responsibilities. The Student is the only active human actor in this product, and their work is a single continuous study workflow with several distinct responsibilities: choosing and uploading a PDF; reading the generated study guide; reviewing flashcards by answering each card, revealing its explanation, and marking the concepts they find difficult; taking the generated quiz, which mixes multiple-choice and short-answer questions; and reading their score and the topics to review on the results page. They also own their own access — creating their account on first use and verifying it on return — because the uploaded documents and generated materials are private to them and must still be there when they come back.

Relevant inputs and decisions. The Student supplies the PDF itself and decides which document to study. During flashcard review they decide which concepts are difficult. During the quiz they decide on each answer, and on the results page they decide what to revisit. They also decide, when the app tells them a PDF does not contain enough information to answer a question, whether to continue with what the document does support or to upload a different document.

Interactions with other accepted participants. The Student is the sole human participant. Their work is carried out with the AI generation service, the PDF text-extraction and OCR component, the private file store, and the persistent database — all of which act only in support of the Student's requests and produce no outcomes on their own behalf.

Observable success. The Student completes the full workflow — upload → study guide → flashcards → quiz → weak topics — and finishes knowing what to revisit. The product's proposed validation targets for this behavior are that 70%+ successfully upload a PDF, 60%+ review generated flashcards, 50%+ finish a quiz, 30%+ return within 7 days, and 70%+ find the study guide useful. These are proposed targets, not proven benchmarks.

5. Core User Flows

Flow 1 — First-time student creates an account and uploads a PDF

1. The Student opens DocFlash and lands on the Landing page, which explains that one PDF becomes a study guide, flashcards, and a quiz, and shows the three-step row (Upload · Review · Quiz).
2. The Student selects Choose a PDF. Because they are not signed in, the app routes them into identity establishment.
3. On the Sign Up page the Student creates their account. If a field is invalid or the credentials are already in use, the error appears inline, the form is preserved, and the Student corrects and resubmits.
4. On success the Student is placed into the signed-in application and continues to the Upload page.
5. The Student selects a PDF of class notes, a textbook chapter, or lecture material. The file summary appears with the document's first page as a small bordered thumbnail in the study-set rail.
6. The app extracts the text. If the PDF is scanned, OCR is applied and the Student can tell that it was. The processing indicator is drawn as the discrete square grid, not a smooth bar.
7. If the file is not a PDF, cannot be read, or extraction fails, the app shows a specific plain-language processing error with a retry control; the Student replaces the file or retries without losing their place.
8. On success the study guide, flashcards, and quiz are generated and the Student continues to the Study Guide.

Flow 2 — Returning student verifies identity and resumes

1. The Student returns to DocFlash and needs their own uploaded documents and generated study materials.
2. On the Login page the Student enters their credentials. If they are not recognized, the error appears inline without disclosing which field was wrong, and the Student retries or switches to Sign Up.
3. On success the Student is returned to the protected work they were attempting — the Upload page, or the study material they had already generated for their document.

Flow 3 — Student reads the generated study guide

1. From the Upload page, with generation complete, the Student continues to the Study Guide.
2. The guide renders as a reading column no wider than 62 characters, presenting summaries, key terms, definitions, and topic sections in clear, organized language.
3. The Student moves between topic sections and reads the material. On wider viewports the study-set rail shows the document name, page count, and the vertical square card index.
4. If generation failed or the document did not contain enough information to build a guide, the app says so plainly and offers a retry or a different document; the Student retries or returns to Upload.
5. The Student continues to Flashcards.

Flow 4 — Student reviews flashcards and marks difficult concepts

1. On the Flashcards page the Student sees one generated question-and-answer card at a time, the card's position in the set (for example "Card 1 of 3"), and the review progress as a row of discrete squares.
2. The Student selects Reveal answer. The card repaints from the question frame to the answer frame with a brief border flash — it visibly becomes a different card rather than rotating in 3D.
3. The Student marks the concept as difficult if it did not stick, then uses Next card to advance; the new card slides in from the right while the old one fades, and the progress squares fill one at a time.
4. The Student can use Previous to go back to an earlier card.
5. If the document did not yield enough information to build cards, the app shows the shrugging pixel figure and a plain statement, with a path back to Upload; the Student uploads a different document or continues with what exists.
6. When the set is finished, the Student continues to the Quiz.

Flow 5 — Student takes the generated quiz

1. On the Quiz page the Student sees one question per screen, drawn from their uploaded PDF, mixing multiple-choice and short-answer questions, with the progress square row showing the quiz length.
2. For a multiple-choice question the Student selects one of four full-width answer rows, each at least 48px tall and thumb-reachable. For a short-answer question the Student types their answer.
3. The Student advances to the next question and repeats until the quiz is finished.
4. If the uploaded PDF does not contain enough information to answer a question, the app shows the question-mark-in-square pictogram and the orange "not enough info" badge rather than presenting an unsupported answer; the Student knows the material is not covered.
5. If generation failed or the document yielded too little information to build a quiz, the app says so plainly and offers a path back to Upload.
6. On finishing, the Student's responses are scored and they are taken to the Results page. If the score cannot be computed, the app states this and offers a retry.

Flow 6 — Student reviews the score and weak topics

1. The Results page shows the quiz score, counting up in whole numbers, and a wrapping array of weak-topic chips, each with a small orange fill bar whose width is that topic's miss rate.
2. The Student reads which topics to revisit. The chips wrap rather than scrolling away, so the whole set stays visible.
3. If no quiz has been completed for this document, the Student is directed back to the Quiz.
4. The Student returns to the Study Guide or Flashcards for the same document to revisit the weak topics, or returns to Upload to process another PDF.

6. Visuals, Colors and Theme

Muse and headline. Susan Kare — Charming clarity, one pixel at a time. DocFlash is fundamentally a card system (upload → guide → flashcards → quiz → weak topics), and Kare's craft of the legible, personality-filled card on a small grid gives the product an identity no SaaS template owns while keeping a study tool from feeling like homework-adjacent bureaucracy. The register is "a friendly coach that hands you one small card at a time" — warm, slightly playful, system-like, and honest about what it can and cannot do with a scanned PDF.

Color tokens (light mode).

No blue anywhere. Color proportion is roughly 70% paper/white, 20% pine, 10% orange, and the orange never appears twice in one viewport at the same weight.

Typography. Headings: Silkscreen at 700 for the wordmark, screen titles, and card counters — used at genuinely small sizes (16–28px) so it reads as a system glyph rather than a poster, and never for a string over 30 characters. Body: IBM Plex Sans at 400/600/700 — 700 for card questions and quiz prompts, 400 for study-guide body at 17px/1.65 with a 62-character measure, 600 for buttons and labels. Silkscreen is never set for a paragraph, study-guide prose, or quiz answer text.

Type scale. 1.25 modular: 12 / 14 / 16 / 17 / 20 / 24 / 28 / 40. Screen title clamp(24px, 6vw, 40px); card question clamp(20px, 5.2vw, 28px); study-guide body fixed at 17px; labels and counters 12–14px with 0.08em tracking. Line-height 1.65 for guide prose, 1.25 for card questions.

Shape language. Chunky 2px ink borders on every card, button, and input — a drawn outline, not a shadow. Radii stay at 4px (a nod to the grid, not a squircle) except the flashcard itself, which gets 8px so it reads as a physical object you could pick up. Buttons are pill-shaped only for the single primary action per screen; everything else is a rounded rect. Progress is drawn as a row of small squares — filled, half, empty — never a smooth bar. Icons are 24px and 32px pixel pictograms drawn on a visible 8px grid: a document with a folded corner for PDF, a stack of cards, a checkmark square, a clock face, and a question-mark-in-square for "not enough info". No drop shadows, no glass, no gradients.

Spacing rhythm. A 4px base unit with 8px grid alignment for pictograms and progress squares; 16px gutters on mobile; card padding in multiples of 8px.

Layout. Mobile-first single column at 375px: a compact pine header bar with the DocFlash wordmark in Silkscreen and a 3-step progress row (Upload · Review · Quiz) drawn as three small squares; below it one card occupies the full width with 16px gutters and never scrolls horizontally. At 768px the layout becomes a two-column split: a 200px left rail holding the study-set meta (document name, page count, card index as a vertical square grid) and the card column at a 560px max width. At 1280px the same two-column structure centres inside a 1040px frame with the card column at 620px and the rail gaining a "topics to review" list. The study guide is a reading column, never wider than 62 characters. The quiz is one question per screen with four full-width answer rows (48px min height, thumb-reachable), and the results screen is a score block plus a horizontal array of weak-topic chips that wrap — never a scroll-away.

Imagery style. The imagery is the interface itself. Pixel pictograms on the 8px grid carry every concept: a folded-corner document, a stack of cards, a magnifier over a page for the study guide, a clock for the focus timer, a checkmark square, and a small shrugging figure for "this PDF doesn't contain enough information". One recurring character — a 32px pixel student with a backpack — appears only as a static spot mark beside encouragement lines ("One card at a time. You've got this.") and never animates as a mascot loop. No photography, no gradients, no 3D blobs, no stock students. The uploaded PDF's own first page can appear as a small 1px-border thumbnail in the study-set rail, treated as a document artefact rather than a hero image.

7. Signature Design Concept

The upload desk. The first screen is not a marketing hero — it is the upload desk. A full-bleed warm paper ground (#F4F1E8) carries a compact pine header bar across the top with the Silkscreen wordmark "DocFlash" and the three-square step row. Directly beneath, offset left rather than centred, sits a single large drop card: a true-white panel with a 2px ink border and 8px radius, roughly 70% of the viewport width on mobile and 560px on desktop, containing a 96px pixel document pictogram on the 8px grid, a 700-weight Plex line at clamp(24px, 6vw, 40px) reading "Turn one PDF into a study guide, flashcards, and a quiz.", a 17px muted subline naming the workflow, and one pine pill button "Choose a PDF" with a small orange arrow chip pinned to its right edge. Behind and to the right of that card, three smaller white cards fan out at slight offsets like a stack mid-deal — one showing a flashcard question, one a quiz option row, one a filled progress grid — cropped by the right viewport edge on mobile and fully visible at 1280px. There is no centred headline, no gradient blob, and no floating dashboard mockup: the composition is a desk with a stack of cards on it. The concept recomposes only accepted content and controls — the entry explanation, the workflow steps, the Choose a PDF action, and the identity routes — and introduces no new behavior or destination.

8. Interaction Model & Motion Direction

Interaction Model: Static Motion Tempo: restrained Hero Dimensionality: flat

Landing Hero Motion Brief. The focal subject is the stack of cards on the desk: the large drop card with its pixel document pictogram, and the three smaller cards fanned behind it. The input→transformation→outcome thesis is that a student's raw PDF becomes three study tools — the fanned cards settle into their offsets as the drop card takes focus, expressing "one document in, three tools out" using only the accepted workflow. The motion vocabulary is restrained and frame-based, like an old screen repainting: 120ms steps with linear easing, no bounce and no springs. The composed first frame shows the pine header bar with the three-square step row, the drop card offset left with its pictogram, headline, subline, and pine pill button with the orange arrow chip, and the three fanned cards already in place at their offsets. Under prefers-reduced-motion the hero is a static arrangement: the cards appear at their final offsets with no translation and no stagger, and every readable element — wordmark, headline, subline, button label, and card text — stays whole inside its container at 375px, 768px, and 1280px.

Motion rules across the product. Card flip on Reveal answer is a two-frame swap (question frame → answer frame) with a 60ms ink-flash on the border, not a 3D rotation. Advancing cards slides the new card in from the right by 24px while the old one fades at 100ms. Progress squares fill one at a time with a 40ms stagger. The quiz score counts up in whole numbers, 8 steps of 60ms, then stops. Under prefers-reduced-motion all of this collapses to instant state changes with no translation and no stagger; the progress squares simply appear filled.

9. Non-Functional Requirements

NFR-1 — Mobile-first responsive web delivery (explicit) The product is a mobile-friendly responsive web app. There is no separate Android or iOS application. Layout must hold at 375px, 768px, and 1280px, and the card column must never scroll horizontally at 375px — the card fits whole, with readable text and controls fully inside the container. Rationale: the source explicitly chose a mobile-friendly web app so the idea could be tested without paying to build separate native apps.

NFR-2 — Grounding and honesty of generated content (explicit) Generated questions and answers must be grounded in the uploaded document, and the app must indicate when the PDF does not contain enough information to answer a question. Rationale: this is a stated critical requirement; a study tool that invents answers is worse than no tool.

NFR-3 — Private file storage (explicit) Uploaded PDFs are held in private cloud storage and are never publicly addressable. Rationale: explicit constraint; the documents are the student's own course material.

NFR-4 — Persistent storage and workflow continuity (required_inference) Uploaded-document state and the generated study materials must persist against the student's account so the workflow can be resumed. Rationale: the accepted workflow spans multiple sessions and the source explicitly calls for persistent student accounts and persistent data.

NFR-5 — Structured AI output (explicit) Study guide and quiz generation use an AI API with structured output. Rationale: explicit technology choice; structured output is what makes the guide sections, flashcards, and quiz items reliably renderable.

NFR-6 — Scanned-document handling (explicit) Scanned PDFs must be handled with OCR if needed, and processing errors must be shown. Rationale: explicit roadmap requirement for the upload-and-extract phase.

NFR-7 — Legibility on modest mobile screens (explicit, from the creative direction) Body text is set at 17px/1.65 with a 62-character measure; quiz answer rows are at least 48px tall and thumb-reachable; readable text and controls stay entirely inside the viewport and their container at every breakpoint. Rationale: the audience studies on cheap Android screens, and the direction requires that headlines, wordmarks, labels, numbers, and card text and controls stay whole.

NFR-8 — Reduced-motion support (explicit, from the creative direction) Under prefers-reduced-motion, all motion collapses to instant state changes with no translation and no stagger, and the hero presents a usable static arrangement. Rationale: accessibility requirement carried by the direction.

NFR-9 — No blue or indigo, no generic SaaS template (explicit, from the creative direction) No blue or indigo anywhere, including #2563EB, #4F46E5, #6366F1, or any blue-to-indigo gradient. Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, and system-ui are not used for any text role. No gradient-blob heroes, frosted glass, or soft drop shadows. Rationale: the generic indigo/blue-on-white SaaS template is explicitly forbidden for this project.

NFR-10 — Free initially (explicit) The product is free initially; no paid subscription is built before demand is validated. Rationale: explicit business-model constraint.

10. Tech Stack

Source-specified choices are preserved exactly:

• Frontend: Next.js or React.
• Mobile-friendly design: Responsive web app.
• PDF text extraction: PDF.js or a server-side PDF parser.
• Study guide and quiz generation: An AI API with structured output.
• Database and login: Supabase.
• File storage: Private cloud storage.
• Deployment: Vercel or a similar hosting service.

Supporting implementation notes:

• Backend: A single shared backend service hosts the upload, extraction/OCR, and generation endpoints, reusing one process, port, and deployment rather than introducing separate services for each capability.
• OCR: Applied within the extraction step when a PDF's text is not directly extractable.
• Containerization: Docker / docker-compose for local development of the backend and its dependencies. Kubernetes is not required at this scale.

11. Assumptions and Constraints

Constraints (binding).

1. Generated questions and answers must be grounded in the uploaded document, and the app must indicate when the PDF lacks enough information to answer a question. (explicit)
2. Do not start by building a full AI tutor or an elaborate learning-management system. (explicit)
3. Save study sets and spaced repetition are next-version features, not part of the MVP. (explicit)
4. File storage must be private cloud storage. (explicit)
5. Mobile-friendly responsive web app; no separate Android/iOS apps. (explicit)
6. The product is free initially; no paid subscriptions before demand is validated. (explicit)
7. Out of scope for the first version: social feeds, followers, and leaderboards; video lessons or a full online classroom; an elaborate AI chatbot; complex calendars and school-management systems. (explicit)
8. No blue or indigo anywhere; no Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for any text role; no gradient-blob heroes, frosted glass, or soft drop shadows; Silkscreen is never set for paragraphs, study-guide prose, or quiz answer text; no smooth percentage progress bar or circular timer ring; no photography of students, stock classroom imagery, or 3D mascot loops; no more than one orange accent element competing in a single viewport; no horizontal scroll on the card column at 375px. (explicit, from the creative direction)

Assumptions (narrow, labeled).

1. [Assumption — required_inference] A student must be signed in to upload a PDF and to view the study guide, flashcards, quiz, and results, because those surfaces read and write state that is private to that student. The Landing, Sign Up, and Login pages are reachable without being signed in.
2. [Assumption — required_inference] Identity is application-owned and self-service: a student creates their own account on first use and verifies it on return. No invitation, provisioning, or deployment bootstrap is described in the source.
3. [Assumption — required_inference] One uploaded PDF produces one study set (study guide, flashcards, quiz) at a time. The source describes "one uploaded PDF" becoming three study tools; it does not describe managing multiple concurrent sets, and saved study sets are explicitly next-version.
4. [Assumption — required_inference] The quiz is scored per attempt and the results page reflects the most recent completed quiz for the current document, since saved study history and spaced repetition are next-version features.
5. [Assumption — not specified by user] Exact file-size limits, page-count limits, and the specific AI provider are not specified in the source and are left to implementation.
6. [Assumption — not specified by user] The specific private cloud storage provider and the specific hosting provider are not named beyond "private cloud storage" and "Vercel or a similar hosting service".

Validation targets (proposed, not proven benchmarks). 70%+ of students successfully upload a PDF; 60%+ review generated flashcards; 50%+ finish a quiz; 30%+ return within 7 days; 70%+ find the study guide useful. Student testing is planned with 20–30 students, and students are asked after a week: did the app help you start studying when you didn't feel like it; did it help you remember what you studied; what made you stop using it, if anything.

Two-week roadmap. Days 1–3: upload and extract — accept PDFs, extract text, handle scanned PDFs with OCR if needed, and show processing errors. Days 4–6: study guide — generate summaries, key terms, definitions, and topic sections. Days 7–9: flashcards and quizzes — generate question-answer pairs and multiple-choice quizzes with explanations. Days 10–12: results and storage — save study sets, track quiz results, and identify weak topics. Days 13–14: student testing — test with 20–30 students, fix confusing features, and measure whether students finish their study sessions.

12. Glossary

• DocFlash — The working product name for studysprint-students, the PDF-to-study-guide, flashcard, and quiz generator.
• Study set — The three study tools generated from one uploaded PDF: the study guide, the flashcards, and the quiz.
• Study guide — The generated, organized explanation of the uploaded document: summaries, key terms, definitions, and topic sections in clear language.
• Flashcard — A generated question-and-answer card used for active recall, with a revealable answer and an explanation.
• Active recall — Studying by attempting to answer a question before seeing the answer, rather than rereading notes.
• Quiz — The generated assessment drawn from the uploaded document, mixing multiple-choice and short-answer questions.
• Weak topic — A topic the student missed on the quiz, surfaced on the results page with a fill bar whose width is that topic's miss rate.
• Grounding — The requirement that generated questions and answers correspond to the uploaded document rather than to outside knowledge.
• Insufficient information — The state in which the uploaded PDF does not contain enough information to answer a question; the app indicates this explicitly instead of producing an unsupported answer.
• OCR — Optical character recognition, applied when a scanned PDF's text is not directly extractable.
• Study-set rail — The left rail on wider viewports holding the document name, page count, card index as a vertical square grid, and the topics-to-review list at 1280px.
• Progress squares — The discrete square grid used for all progress display (daily goal, card index, quiz length), never a smooth percentage bar.
• Next version — Features explicitly deferred beyond the MVP: saved study sets for revisiting previous materials, and spaced repetition that schedules reviews based on recall performance.