System Requirements Document for learning-platform-pdf

1. Introduction

learning-platform-pdf is a solo college project: an AI-Based Personalized Learning Platform. A student uploads any PDF — class notes, a textbook chapter, a lab manual, anything — and the application turns it into easy visual learning material. It is deliberately not limited to one subject: the pipeline is content-agnostic and works on whatever text and images the PDF contains.

The product exists for a single audience: a student who wants a fast, visual, self-checking study sheet generated from material they already have. The intended user is the author's own peer group — a GTU Computer Engineering diploma student (Semester 3) and their classmates — so the app is designed to be legible, tactile, and explainable in a viva rather than to look like an enterprise product.

The core transformation the product performs is:

PDF → extracted text and images → chunked LLM analysis → structured JSON (summary, key points, Mermaid diagram, chart data, 10 MCQs) → animated study page → quiz → per-topic personalization → dashboard.

The project is built in seven gated stages, and each stage is delivered as complete, working, commented code with the file name above it, plus instructions for how to run and test it.

2. System Overview

The platform is a Python/Flask web application backed by SQLite, with server-rendered HTML templates enhanced by HTML/CSS/JS, Mermaid.js, Chart.js, and AOS animations. PDF text and embedded images are extracted with PyMuPDF. Structured learning content is produced by an LLM API (Gemini free tier), whose API key is kept in a .env file. Development and running happen on Windows + VS Code.

The single in-product human actor is the Student Learner. The student registers, logs in, uploads PDFs, waits for extraction and LLM processing, studies the generated visual material, takes the generated MCQ quiz, reviews per-topic accuracy and weak-topic recommendations, and tracks progress on the dashboard.

Durable, per-user state is central to the product: documents, generated content, questions, and attempts are all stored against the owning student, so a returning student sees their own library, their own study material, and their own quiz history. Access to the dashboard, upload, study page, quiz page, and personalization view therefore requires a logged-in student; the landing page, login, and sign-up are reachable without an account.

Narrow exclusions. This document does not add capabilities the source did not request. There is no multi-teacher or classroom administration, no social or sharing features, no payment, no mobile app, no subject-specific content packs, and no account-management surface beyond register/login. The LLM provider is an external dependency owned by the provider; the application owns the prompt, the chunking, the JSON parsing, and the safe handling of bad output.

2a. Product Interpretation and Delivery Boundary

Delivery ownership. The product is a first-party Flask application. All student-facing surfaces — landing, login, sign-up, dashboard, upload, study page, quiz page, and personalization — are custom pages owned by the application. The LLM is an external provider: the application sends chunked text to it and receives structured JSON back, but the provider owns the model, its availability, and its rate limits. The application owns everything around that call: prompt design, chunking of large PDFs, JSON parsing, validation, and safe failure when the output is malformed.

Identity and access. The application owns student identity. A student creates their own account through self-service sign-up, and a returning student verifies themselves at login. Flask sessions carry the logged-in state. Passwords are stored hashed. Because documents, generated content, questions, and attempts are durable and private to one student, the dashboard, upload, study page, quiz page, and personalization view are protected and require login. The landing page, login, and sign-up are anonymous entry surfaces; the login and sign-up pages cannot themselves require login.

Current vs. future boundary. Everything described in this document is current. The seven-stage build order is a delivery sequence, not a roadmap of future features: Stage 1 (folder structure + DB setup), Stage 2 (register/login), Stage 3 (PDF upload + text/image extraction), Stage 4 (LLM integration), Stage 5 (study page), Stage 6 (quiz + personalization), and Stage 7 (dashboard + UI polish) are all in scope now. The build pauses after each stage until the student says "next". No feature is deferred to a future horizon by the source.

What the product is not. It is not a general document-management system, not a course platform, and not a chat interface. Its only transformation is PDF → visual study material → quiz → per-topic feedback.

2c. Page Content and Component Coverage

Landing

• Information/state: Anonymous first impression. States what the platform does — turn any PDF into a personal visual study sheet — and who it is for (students, any subject). Presents the pipeline as a visual sequence: PDF → pages → diagram + quiz → progress.
• Primary action: Navigate to Sign Up to create an account.
• Supporting actions: Navigate to Login for a returning student.
• Domain entities: None persisted; describes the PDF → study-material transformation.
• Component responsibilities: Hero band with the headline and a single primary call to action; a pipeline illustration composed of pixel icons connected by dashed arrows; a link to Login for returning students.
• States: Loading (static content, no data fetch); Empty (not applicable — static entry); Success (page renders with both entry actions available); Error (not applicable); Recovery (not applicable).

Login

• Information/state: Anonymous returning-student verification surface. Collects credentials and reports verification failure without revealing which field was wrong.
• Primary action: Submit credentials to start a Flask session.
• Supporting actions: Navigate to Sign Up if the student has no account.
• Domain entities: User (email/username and hashed password).
• Component responsibilities: Credential form; submit control; inline error region for failed verification; link to Sign Up.
• States: Loading (submit disabled while verifying); Empty (blank form); Success (session established, redirect to Dashboard); Error (invalid credentials message, form retained); Recovery (student can retry or go to Sign Up).

Sign Up

• Information/state: Anonymous self-service enrollment surface. Collects the details needed to create a student account and establishes the student's private workspace.
• Primary action: Create the account and establish the session.
• Supporting actions: Navigate to Login if the student already has an account.
• Domain entities: User (credentials, hashed password).
• Component responsibilities: Registration form; password hashing on the server; submit control; validation error region; link to Login.
• States: Loading (submit disabled while creating); Empty (blank form); Success (account created, session established, redirect to Dashboard); Error (validation failure such as duplicate account or mismatched input, form retained); Recovery (student corrects input and resubmits, or goes to Login).

Dashboard

• Information/state: The student's home after login. Shows all uploaded documents, a progress chart, weak topics, and quiz history. Each document row exposes its filename and upload date and routes into that document's study work.
• Primary action: Open a document to continue studying it.
• Supporting actions: Navigate to Upload to add a new PDF; open the Quiz page for a document; open Personalization for topic-level detail.
• Domain entities: Document (id, user_id, filename, upload_date); Attempt (id, user_id, question_id, correct, date); Question (topic, difficulty); Content (summary, points_json, diagram_code, chart_json).
• Component responsibilities: Document list with per-document entry points; progress chart rendered with Chart.js; weak-topic list with under-60% flags; quiz history list; navigation to Upload.
• States: Loading (fetching the student's documents and attempt history); Empty (no documents yet — prompt to upload the first PDF); Success (documents, progress chart, weak topics, and quiz history all populated); Error (data fetch failed — retry control, no partial silent failure); Recovery (retry reloads the dashboard; a document whose processing failed is shown with its failure state rather than as ready).

Upload

• Information/state: Focused workflow for adding a PDF to the student's library. Shows the selected file, validation feedback, and processing progress.
• Primary action: Select and submit a PDF for validation, saving, extraction, and LLM processing.
• Supporting actions: Cancel/replace the selected file before submitting; return to Dashboard.
• Domain entities: Document (id, user_id, filename, upload_date); Content (summary, points_json, diagram_code, chart_json); Question (topic, question, option_a–d, answer, difficulty).
• Component responsibilities: File picker restricted to PDF; type and size validation with clear rejection messages; per-user save location; extraction of text page by page and embedded images via PyMuPDF; chunked dispatch to the LLM; JSON parsing and validation; progress/status region; navigation back to Dashboard.
• States: Loading (extraction and LLM processing in progress, with visible status); Empty (no file selected); Success (document saved, content and questions generated, route to Study page); Error (wrong type, oversized file, extraction failure, or bad LLM output — each reported distinctly and safely, with no partial corrupt record); Recovery (student can retry the upload or return to the Dashboard; a failed document is not presented as ready to study).

Study page

• Information/state: The generated study sheet for one document, presented as discrete numbered panels: Summary, Key Points, Diagram, Chart, Image Gallery.
• Primary action: Study the generated material for the document.
• Supporting actions: Move to the Quiz page for this document; return to Dashboard.
• Domain entities: Content (summary, points_json, diagram_code, chart_json); Document (filename, upload_date); extracted PDF images.
• Component responsibilities: Summary panel; key-points panel whose points animate in one by one (AOS or CSS); Mermaid.js diagram renderer for the flowchart or mind map; Chart.js chart renderer for the chart data; image gallery of the PDF's extracted embedded images.
• States: Loading (content being fetched/rendered); Empty (a document with no chart data, or no embedded images, shows that panel's empty state rather than a broken panel); Success (all applicable panels rendered); Error (Mermaid or Chart rendering failure, or missing content, is contained to its panel with a readable message); Recovery (student can reload the page or return to the Dashboard; other panels remain usable).

Quiz page

• Information/state: The generated MCQs for one document, presented one at a time or as a set, with topic tags and difficulty visible.
• Primary action: Answer each MCQ.
• Supporting actions: Move to Personalization after finishing; return to Study page or Dashboard.
• Domain entities: Question (id, document_id, topic, question, option_a–d, answer, difficulty); Attempt (id, user_id, question_id, correct, date).
• Component responsibilities: Question presentation with options A–D; topic tag and difficulty display; answer submission that saves every answer to attempts; correct/incorrect feedback; navigation onward.
• States: Loading (questions being fetched); Empty (no questions available for the document — message plus route back to Upload/Study); Success (answers recorded, feedback shown); Error (submission failed — the answer is not silently lost, and the student is told to retry); Recovery (retry submission; already-recorded attempts are not duplicated).

Personalization

• Information/state: Per-topic performance for the student. Shows accuracy per topic, marks topics under 60% as weak, recommends re-reading the weak topic's section, and offers to generate easier questions for that topic.
• Primary action: Review weak topics and act on the recommendation.
• Supporting actions: Accept the offer to generate easier questions for a weak topic; navigate back to the Study page for the recommended section; return to Dashboard.
• Domain entities: Attempt (id, user_id, question_id, correct, date); Question (topic, difficulty); Content (points_json, diagram_code) for locating the recommended section.
• Component responsibilities: Per-topic accuracy display; weak-topic flags at the under-60% threshold; re-reading recommendation naming the weak topic's section; easier-question offer control; navigation to Study page and Dashboard.
• States: Loading (computing accuracy from attempts); Empty (no attempts yet — explain that accuracy appears after a quiz); Success (accuracy, weak topics, recommendations, and offers shown); Error (computation or easier-question generation failed — reported without losing existing attempt data); Recovery (retry; the student can still return to the Study page and Dashboard).

3. Functional Requirements

Each requirement is a distinct story point with provenance, lifecycle facts, and observable acceptance.

FR-1 — Account registration As a Student Learner, I should be able to register an account with a password so that I have my own private learning workspace.

• Provenance: explicit (Feature 1)
• Trigger/input: Student submits registration details including a password.
• Observable result: A user record is created with a hashed password (never stored in plain text), and a Flask session is established.
• Access state: Anonymous — the sign-up surface must be reachable without login.
• Failure/recovery: Invalid or duplicate input is rejected with a readable message and the form is retained for correction.
• Continuation: The student lands on the Dashboard with an empty library.

FR-2 — Login and session As a Student Learner, I should be able to log in so that I can reach my own documents, study material, quizzes, and progress.

• Provenance: explicit (Feature 1)
• Trigger/input: Student submits credentials.
• Observable result: Credentials are verified against the stored hash and a Flask session is established.
• Access state: Anonymous entry; successful verification grants access to protected pages.
• Failure/recovery: Failed verification shows an error without revealing which field was wrong; the student may retry or go to Sign Up.
• Continuation: The student reaches the Dashboard.

FR-3 — Protected access to personal state As a Student Learner, I should only reach my own documents, generated content, questions, and attempts after logging in.

• Provenance: required_inference (per-user durable storage)
• Trigger/input: Any request to Dashboard, Upload, Study page, Quiz page, or Personalization.
• Observable result: Requests without a valid session are redirected to Login; with a session, only the logged-in student's rows are returned.
• Access state: Login required for all five protected pages.
• Failure/recovery: Expired or missing session routes to Login; after logging in the student returns to the intended work.
• Continuation: Normal navigation resumes.

FR-4 — PDF upload with validation As a Student Learner, I should be able to upload a PDF so that the app can turn it into study material.

• Provenance: explicit (Feature 2)
• Trigger/input: Student selects a file on the Upload page.
• Observable result: The file's type is validated (must be a PDF) and its size is validated; a valid file is saved per user and a documents row is created with id, user_id, filename, upload_date.
• Access state: Login required.
• Failure/recovery: Wrong type or oversized file is rejected with a specific message and nothing is saved; the student can pick another file.
• Continuation: The saved document proceeds to extraction.

FR-5 — Page-by-page text and embedded image extraction As a Student Learner, I should have the text and images of my PDF extracted so that they can be analyzed and displayed.

• Provenance: explicit (Feature 3)
• Trigger/input: A successfully saved PDF.
• Observable result: Text is extracted page by page and embedded images are extracted, using PyMuPDF.
• Access state: Login required (runs within the student's upload workflow).
• Failure/recovery: A corrupt or unreadable PDF fails safely with a reported error; no partial content is presented as complete.
• Continuation: Extracted text is chunked for the LLM; extracted images are retained for the gallery.

FR-6 — Chunked LLM processing As a Student Learner, I should have large PDFs handled by chunking so that long documents still produce study material.

• Provenance: explicit (Rules: "Handle large PDFs by chunking")
• Trigger/input: Extracted text from a document.
• Observable result: Text is split into chunks and sent to the Gemini free-tier LLM API (key read from .env), and the responses are combined into one set of content for the document.
• Access state: Login required.
• Failure/recovery: A failed chunk is handled safely — the failure is reported and does not corrupt the document's stored content.
• Continuation: Combined output proceeds to JSON parsing.

FR-7 — Structured JSON output As a Student Learner, I should receive structured learning content so that the study page has summary, points, diagram, chart, and questions.

• Provenance: explicit (Feature 4)
• Trigger/input: Chunked text sent to the LLM.
• Observable result: The LLM returns structured JSON containing: a summary; key points as short bullets; a Mermaid diagram (flowchart or mind map) of the concepts; chart data when the PDF has numbers or comparisons; and 10 MCQs with topic tags and difficulty.
• Access state: Login required.
• Failure/recovery: Bad LLM output is handled safely — malformed JSON is detected and rejected rather than stored as broken content.
• Continuation: Valid content is persisted to content and questions.

FR-8 — Persisted generated content As a Student Learner, I should have my generated content saved so that I can revisit it without regenerating.

• Provenance: explicit (Database tables)
• Trigger/input: Validated LLM JSON.
• Observable result: A content row is written with id, document_id, summary, points_json, diagram_code, chart_json; questions rows are written with id, document_id, topic, question, option_a–option_d, answer, difficulty.
• Access state: Login required.
• Failure/recovery: A write failure is reported; the document is not shown as ready to study.
• Continuation: The Study page can render the document.

FR-9 — Animated key points As a Student Learner, I should see key points animate in one by one so that I can absorb them in sequence.

• Provenance: explicit (Feature 5)
• Trigger/input: Opening the Study page for a document with key points.
• Observable result: Key points appear one by one using AOS or CSS animation.
• Access state: Login required.
• Failure/recovery: If animation is unavailable, the points remain fully readable.
• Continuation: The student continues to the diagram, chart, and gallery panels.

FR-10 — Mermaid diagram rendering As a Student Learner, I should see the concept diagram rendered so that I can understand the structure of the topic.

• Provenance: explicit (Feature 5)
• Trigger/input: A document whose content.diagram_code holds a Mermaid flowchart or mind map.
• Observable result: The diagram renders with Mermaid.js on the Study page.
• Access state: Login required.
• Failure/recovery: Invalid diagram code is contained to the Diagram panel with a readable message; other panels stay usable.
• Continuation: The student continues to the chart and gallery.

FR-11 — Chart rendering As a Student Learner, I should see a chart of the PDF's numbers or comparisons so that quantitative content is visual.

• Provenance: explicit (Feature 5)
• Trigger/input: A document whose content.chart_json holds chart data.
• Observable result: The chart renders with Chart.js on the Study page.
• Access state: Login required.
• Failure/recovery: Missing or invalid chart data shows the Chart panel's empty/error state instead of a broken panel.
• Continuation: The student continues to the gallery.

FR-12 — Extracted image gallery As a Student Learner, I should see the PDF's embedded images in a gallery so that figures from the source are available while studying.

• Provenance: explicit (Feature 5)
• Trigger/input: A document with extracted embedded images.
• Observable result: The extracted images are displayed in a gallery on the Study page.
• Access state: Login required.
• Failure/recovery: A document with no embedded images shows an empty gallery state; a broken image does not break the page.
• Continuation: The student moves to the Quiz page.

FR-13 — Quiz from generated MCQs As a Student Learner, I should take a quiz built from the generated MCQs so that I can test myself on the document.

• Provenance: explicit (Feature 6)
• Trigger/input: Opening the Quiz page for a document with generated questions.
• Observable result: The 10 MCQs are presented with their options, topic tags, and difficulty.
• Access state: Login required.
• Failure/recovery: A document with no questions shows an empty state with a route back to Upload/Study.
• Continuation: The student answers the questions.

FR-14 — Every answer saved to attempts As a Student Learner, I should have every answer I give saved so that my progress and weak topics are accurate.

• Provenance: explicit (Feature 6)
• Trigger/input: The student answers an MCQ.
• Observable result: An attempts row is written with id, user_id, question_id, correct, date for every answer.
• Access state: Login required.
• Failure/recovery: A failed write is reported and the answer is not silently lost; retry does not duplicate an already-recorded attempt.
• Continuation: The student continues to the next question and then to Personalization.

FR-15 — Accuracy per topic As a Student Learner, I should see my accuracy per topic so that I know where I stand.

• Provenance: explicit (Feature 7)
• Trigger/input: Recorded attempts joined to their questions' topic tags.
• Observable result: Accuracy is computed and displayed per topic.
• Access state: Login required.
• Failure/recovery: With no attempts, the page explains that accuracy appears after a quiz rather than showing a misleading zero.
• Continuation: The student reviews weak topics.

FR-16 — Weak-topic threshold and re-reading recommendation As a Student Learner, I should have topics under 60% flagged as weak with a re-reading recommendation so that I know what to revisit.

• Provenance: explicit (Feature 7)
• Trigger/input: A topic whose accuracy is under 60%.
• Observable result: The topic is marked weak, and the app recommends re-reading that weak topic's section.
• Access state: Login required.
• Failure/recovery: If the recommended section cannot be located in the document's content, the recommendation still names the weak topic and the student can open the Study page.
• Continuation: The student re-reads the section or accepts the easier-question offer.

FR-17 — Easier-question offer for a weak topic As a Student Learner, I should be offered easier questions for a weak topic so that I can practise at a level I can handle.

• Provenance: explicit (Feature 7)
• Trigger/input: A topic flagged weak (under 60%).
• Observable result: The app offers to generate easier questions for that topic, and on acceptance generates them for the student to attempt.
• Access state: Login required.
• Failure/recovery: If generation fails, the failure is reported and the student's existing attempts and accuracy are unaffected.
• Continuation: The student attempts the easier questions, and the new attempts feed back into accuracy per topic.

FR-18 — Dashboard document library As a Student Learner, I should see all my uploaded documents on the dashboard so that I can pick up any of them.

• Provenance: explicit (Feature 8)
• Trigger/input: Opening the Dashboard.
• Observable result: All uploaded documents for the logged-in student are listed with their filename and upload date, each routing into its study work.
• Access state: Login required.
• Failure/recovery: A fetch failure shows a retry control rather than an empty-looking library.
• Continuation: The student opens a document or uploads a new one.

FR-19 — Dashboard progress chart As a Student Learner, I should see a progress chart on the dashboard so that I can see my improvement over time.

• Provenance: explicit (Feature 8)
• Trigger/input: The student's attempt history.
• Observable result: A progress chart is rendered on the Dashboard.
• Access state: Login required.
• Failure/recovery: With no attempts, the chart shows an empty state explaining that progress appears after a quiz.
• Continuation: The student reviews weak topics and quiz history.

FR-20 — Dashboard weak topics As a Student Learner, I should see my weak topics on the dashboard so that I can act on them immediately.

• Provenance: explicit (Feature 8)
• Trigger/input: Per-topic accuracy under 60%.
• Observable result: Weak topics are listed on the Dashboard.
• Access state: Login required.
• Failure/recovery: With no weak topics, the section states that clearly instead of appearing broken.
• Continuation: The student opens Personalization or the Study page for the weak topic.

FR-21 — Dashboard quiz history As a Student Learner, I should see my quiz history on the dashboard so that I can review what I have attempted.

• Provenance: explicit (Feature 8)
• Trigger/input: The student's recorded attempts.
• Observable result: Quiz history is listed on the Dashboard.
• Access state: Login required.
• Failure/recovery: With no attempts, the section shows an empty state.
• Continuation: The student continues studying or takes another quiz.

FR-22 — Stage-gated delivery As the project author, I should receive the build in seven stages that pause until I say "next" so that I can follow and explain each part.

• Provenance: explicit (Rules)
• Trigger/input: The author says "next".
• Observable result: The next stage is delivered: Stage 1 folder structure + DB setup; Stage 2 register/login; Stage 3 PDF upload + text/image extraction; Stage 4 LLM integration (prompt design, JSON parsing, error handling); Stage 5 study page (animated points, Mermaid, Chart.js, images); Stage 6 quiz + personalization; Stage 7 dashboard + UI polish.
• Access state: Not applicable (authoring workflow).
• Failure/recovery: Not applicable.
• Continuation: The following stage begins only after the next "next".

FR-23 — Per-file delivery with run/test instructions As the project author, I should get complete, working, commented code per file with the file name above it and run/test instructions after each stage so that I can run and defend it in a viva.

• Provenance: explicit (Rules)
• Trigger/input: Each stage delivery.
• Observable result: Each file is presented with its file name above it, the code is complete and working, comments explain it simply, and instructions for how to run and test the stage are included.
• Access state: Not applicable (authoring workflow).
• Failure/recovery: Not applicable.
• Continuation: The author runs and tests the stage before saying "next".

4. User Personas

Student Learner

Product context. A student — the author's own peer group, a GTU Computer Engineering diploma student (Semester 3) and their classmates — who already has study material as PDFs: class notes, textbook chapters, lab manuals. They are not looking for a course platform; they want their existing material turned into something easier to revise from. They work on a Windows machine in VS Code, and they are comfortable with a browser-based tool but not with configuring infrastructure.

Primary goal. Turn any PDF into a personal, visual study sheet — summary, key points, a concept diagram, a chart where the material has numbers, and the source's own figures — then test themselves and find out exactly which topics need more work.

Distinct accepted responsibilities.

• Register an account and log in, so their documents, generated content, questions, and attempts stay private and durable.
• Upload any PDF, with type and size validated, saved per user.
• Wait for extraction (text page by page plus embedded images via PyMuPDF) and chunked LLM processing to complete or fail safely.
• Study the generated material: key points that animate in one by one, the Mermaid diagram, the Chart.js chart, and the extracted image gallery.
• Take the quiz built from the generated MCQs, with every answer saved to attempts.
• Review accuracy per topic, see topics under 60% flagged as weak, read the re-reading recommendation for the weak topic's section, and accept the offer to generate easier questions for it.
• Use the dashboard to see all uploaded documents, the progress chart, weak topics, and quiz history.

Relevant inputs and decisions. Which PDF to upload; whether to proceed once processing finishes or fails; which document to study next; which answer to choose on each MCQ; whether to accept the easier-question offer for a weak topic; whether to re-read the recommended section or move on.

Interactions with other accepted participants. The Student Learner is the only in-product human actor. The other participants in the lifecycle are non-human: the Gemini LLM API (external provider) receives chunked text and returns structured JSON, and the application's own processing performs extraction, chunking, parsing, and persistence. The student's interaction with the provider is indirect — they see its result as study material, or see a safe failure when its output is bad.

Observable success. The student's document appears in their dashboard library; the study page shows their summary, animated key points, rendered diagram, rendered chart, and image gallery; their quiz answers are recorded; their per-topic accuracy is shown with weak topics flagged under 60%; and their dashboard shows a progress chart and quiz history that reflect their own attempts.

What makes this role distinct. The Student Learner is simultaneously the content provider (they supply the PDF), the consumer (they study the generated material), and the assessor (they take the quiz whose results drive their own personalization). No other role exists in the product, and no role has differentiated permissions over shared state — every student sees only their own workspace.

5. Core User Flows

Flow A — First-time student creates an account and reaches an empty workspace

1. The student opens the Landing page (anonymous) and reads what the platform does: any PDF becomes a personal visual study sheet.
2. The student chooses the primary action and goes to Sign Up.
3. On Sign Up, the student enters their registration details and a password, and submits.
4. The application hashes the password, creates the users row, and establishes a Flask session.
5. Observable result: the student lands on the Dashboard with an empty library and a prompt to upload their first PDF.
6. Failure/recovery: if the input is invalid or the account already exists, the form is retained with a readable message and the student corrects it or follows the link to Login.
7. Continuation: the student proceeds to Flow B.

Flow B — Returning student logs in and resumes their own work

1. The student opens Login (anonymous).
2. The student submits their credentials.
3. The application verifies them against the stored hash and establishes the session.
4. Observable result: the student reaches the Dashboard, showing their own documents, progress chart, weak topics, and quiz history.
5. Failure/recovery: failed verification shows an error without revealing which field was wrong; the student retries or goes to Sign Up.
6. Continuation: the student opens a document, uploads a new one, or reviews personalization.

Flow C — Student uploads a PDF and gets generated study material

1. From the Dashboard, the student goes to Upload.
2. The student selects a PDF file.
3. The application validates the type (must be PDF) and the size, then saves the file per user and creates the documents row (id, user_id, filename, upload_date).
4. The application extracts text page by page and embedded images with PyMuPDF.
5. The extracted text is split into chunks and sent to the Gemini free-tier LLM API (key read from .env).
6. The LLM returns structured JSON: summary, key points as short bullets, a Mermaid diagram (flowchart or mind map), chart data where the PDF has numbers or comparisons, and 10 MCQs with topic tags and difficulty.
7. The application parses and validates the JSON, then writes the content row (id, document_id, summary, points_json, diagram_code, chart_json) and the questions rows (id, document_id, topic, question, option_a–option_d, answer, difficulty).
8. Observable result: the student is routed to the Study page for the new document.
9. Failure/recovery: a wrong file type or oversized file is rejected before saving; an unreadable PDF fails at extraction; a failed chunk or bad LLM output is detected and rejected safely rather than stored as broken content. In each case the student sees a specific message and can retry the upload or return to the Dashboard, and the document is not presented as ready to study.
10. Continuation: the student studies the material in Flow D.

Flow D — Student studies the generated visual material

1. The student opens the Study page for a document.
2. The page presents discrete numbered panels: Summary, Key Points, Diagram, Chart, Image Gallery.
3. The student reads the summary.
4. The key points animate in one by one (AOS or CSS), so the student absorbs them in sequence.
5. The student views the Mermaid.js diagram of the concepts, rendered from diagram_code.
6. The student views the Chart.js chart, rendered from chart_json, showing the PDF's numbers or comparisons.
7. The student browses the gallery of the PDF's extracted embedded images.
8. Observable result: the student has a complete visual study sheet for the document.
9. Failure/recovery: if the diagram code is invalid, the Diagram panel shows a readable message while the other panels stay usable; if the document has no chart data or no embedded images, that panel shows its empty state rather than breaking the page.
10. Continuation: the student moves to the Quiz page (Flow E).

Flow E — Student takes the quiz and every answer is recorded

1. From the Study page or the Dashboard, the student opens the Quiz page for a document.
2. The page presents the generated MCQs with their options, topic tags, and difficulty.
3. For each question, the student selects an option and submits.
4. The application records an attempts row (id, user_id, question_id, correct, date) for every answer and shows correct/incorrect feedback.
5. Observable result: the student's answers are durably recorded against their account.
6. Failure/recovery: if a write fails, the student is told and can retry; an already-recorded attempt is not duplicated. If the document has no questions, the page shows an empty state with a route back to Upload/Study.
7. Continuation: the student moves to Personalization (Flow F).

Flow F — Student reviews weak topics and accepts easier questions

1. The student opens Personalization.
2. The application computes accuracy per topic from the student's recorded attempts joined to their questions' topic tags.
3. Observable result: the student sees their per-topic accuracy, with every topic under 60% flagged as weak.
4. For each weak topic, the app recommends re-reading that weak topic's section.
5. The student follows the recommendation back to the Study page to re-read the section, or accepts the offer to generate easier questions for that topic.
6. If the student accepts, the application generates easier questions for the weak topic and the student attempts them.
7. Observable result: the new attempts feed back into accuracy per topic, and the weak-topic flag updates as accuracy changes.
8. Failure/recovery: if easier-question generation fails, the failure is reported and the student's existing attempts and accuracy are unaffected. If the recommended section cannot be located, the recommendation still names the weak topic and the student can open the Study page.
9. Continuation: the student returns to the Dashboard (Flow G).

Flow G — Student tracks progress on the dashboard

1. The student opens the Dashboard.
2. Observable result: the student sees all uploaded documents with their filenames and upload dates, a progress chart built from their attempts, their weak topics, and their quiz history.
3. The student opens a document to continue studying it, or goes to Upload to add another PDF.
4. Failure/recovery: if the data fetch fails, a retry control is shown rather than an empty-looking library; a document whose processing failed is shown with its failure state rather than as ready.
5. Continuation: the student repeats Flows C–G for any further PDF, in any subject.

Flow H — Author receives the build stage by stage

1. The author starts with Stage 1: folder structure + DB setup.
2. The author receives complete, working code per file, with the file name above it, kept simple with comments so it can be explained in a viva, plus instructions for how to run and test the stage.
3. The author runs and tests the stage on Windows in VS Code.
4. The author says "next", and the next stage is delivered: Stage 2 register/login; Stage 3 PDF upload + text/image extraction; Stage 4 LLM integration (prompt design, JSON parsing, error handling); Stage 5 study page (animated points, Mermaid, Chart.js, images); Stage 6 quiz + personalization; Stage 7 dashboard + UI polish.
5. Observable result: each stage is delivered only after the previous one is acknowledged, and each stage arrives with its own run/test instructions.
6. Continuation: the sequence completes at Stage 7.

6. Visuals Colors and Theme

The creative direction is authoritative for this section: charming clarity after Susan Kare — pixel-perfect study icons on a paper ground. The emotional register is "my own friendly study desk", not enterprise SaaS: a small hand-made app that a student can explain in a viva — legible, tactile, a bit nostalgic, obviously built by one person who cares. It must never read as a blue-gradient AI startup template.

Palette (light mode)

Contrast check: ink on cream ≈ 14:1; white on pine ≈ 7.5:1; white on orange ≈ 3.9:1 — so orange is used for fills with dark ink text or as a 2px border/underline, never for small white text.

Typography

• Headings: VT323 — monospaced, pixel-terminal, wide tracking, all-caps for micro-labels. Used at large sizes for hero numerals, page titles, and section numbers.
• Body: IBM Plex Sans in 400/500/600 — a humanist grotesque with a slightly technical, drafting-table feel that pairs with pixel type without looking like a template.
• Scale: 1.25 modular with one jump: 72 / 56 / 40 / 28 / 20 / 16 / 14. Hero display 56px mobile → 112px desktop (clamp); section titles 28 → 40px; body 16px; micro-labels 12px all-caps with 0.12em tracking.
• Hierarchy comes from scale and the pixel/plain contrast — no bold-everything.

Shape language

Chunky 2px ink outlines on cards, 6px radii (small, deliberate — not pill), 1px dashed rules for dividers, and hard 45°-notched corners on topic badges. Everything reads like a drawn UI: solid fills, visible borders, no soft shadows except a 2px hard offset on the primary CTA.

Layout

Tidy 12-column grid with a visible 1px ink baseline rule system. A left rail (240px) holds the pixel-icon navigation. Content sits in a 720px reading measure for key points, while the diagram and chart panels break wider to the full grid. The Study page is a stack of discrete panels — Summary, Key Points, Diagram, Chart, Image Gallery — each introduced by a numbered pixel label (01, 02, 03…). The Dashboard uses icon tiles in a 4-up grid, each tile with a pixel glyph, a big numeral, and a 12px all-caps label.

Imagery

Extracted PDF images are treated as found artefacts: each sits in a white card with a 2px ink frame, a pixel corner tick, and a 12px caption of its page number. Missing or broken images get a hand-drawn pixel placeholder glyph. Navigation and status are carried by a small pixel icon set (document, page, diagram, chart, quiz, weak-topic) drawn on a 16×16 grid — the app's most distinctive asset.

Avoid

Blue/indigo primary or accent anywhere — no #2563EB, #4F46E5, #6366F1, no bootstrap-blue buttons; Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Poppins, or system-ui for headings or body; gradient-blob hero, glassmorphism panels, blurred frosted cards; a grid of identical hover-lift cards as the dashboard; soft drop shadows, pill buttons, 24px+ radii; emoji used in place of the pixel icon set; dark-mode-first surfaces — this is a paper-ground app; decorative animation beyond the staggered reveals and chart/diagram draw-ins.

7. Signature Design Concept

The pipeline as a printed worksheet.

The public entry is not a centred SaaS hero. It is a full-width cream band with a 112px VT323 headline — "TURN ANY PDF INTO YOUR OWN STUDY SHEET" — set flush-left and allowed to wrap across two lines, with a 2px orange underline running the full grid width beneath the word "PDF".

Under the headline sits a single hard-edged white card the width of the grid, showing a live miniature of the product's real pipeline as four pixel icons connected by 1px dashed ink arrows:

PDF → pages → diagram + quiz → progress

The CTA "Upload a PDF" sits inside the last node as a solid pine block with ink text. The right third of the band is empty cream, deliberately — the composition is asymmetric and confident, not centred.

This concept recomposes only accepted content, states, and controls: the four icons name the accepted pipeline (upload a PDF, extract pages, generate diagram and quiz, track progress), and the CTA is the accepted entry action that leads to Sign Up. It introduces no new behaviour, page, or destination.

8. Interaction Model & Motion Direction

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

Landing Hero Motion Brief

• Focal subject: the four-icon pipeline miniature — PDF → pages → diagram + quiz → progress — connected by 1px dashed ink arrows, with the "Upload a PDF" pine block as the terminal node.
• Input → transformation → outcome thesis: the student's arrival on the page is the input; the pipeline miniature reveals itself frame by frame, each icon and its connecting dashed arrow appearing in a hard step rather than an eased fade; the outcome is a composed first frame in which the whole pipeline is legible and the CTA is the obvious next action.
• Motion vocabulary: frame-by-frame, not eased. Hard steps, no bounce, no blur, no gradient drift. Hover states invert fill and ink instantly.
• Composed first frame: cream band, flush-left VT323 headline wrapped across two lines, the 2px orange underline beneath "PDF", the white pipeline card beneath it, the pine CTA block inside the last node, and the right third of the band left empty.
• Reduced-motion state: with prefers-reduced-motion, the pipeline renders fully composed in its final state — all four icons, all dashed arrows, and the CTA visible at once, with no staggered reveal. Nothing is hidden or unreadable.

Motion rules across the product

• Key points appear in 120ms steps with a hard 4px upward slide and a 1-frame ink flash, staggered 90ms apart (AOS with a custom "step" animation).
• Mermaid nodes draw with a stroke-dash reveal.
• Chart.js bars grow in 180ms linear.
• Hover states invert fill and ink instantly.
• No bounce, no blur, no gradient drift. No decorative animation beyond the staggered reveals and chart/diagram draw-ins.

9. Non-Functional Requirements

NFR-1 — Fixed technology stack The stack is fixed: Python, Flask, SQLite, PyMuPDF, Gemini free-tier LLM API, HTML/CSS/JS, Mermaid.js, Chart.js, AOS animations, on Windows + VS Code. Provenance: explicit. Rationale: the author must be able to build, run, and defend the project with the tools they already know.

NFR-2 — Secret handling The LLM API key must be kept in a .env file and must not be hard-coded into source files. Provenance: explicit. Rationale: the key is a credential for an external provider.

NFR-3 — Password security Passwords are stored hashed, never in plain text, and login uses Flask sessions. Provenance: explicit (Feature 1). Rationale: student accounts protect private documents and progress.

NFR-4 — Per-user data isolation Documents, generated content, questions, and attempts are stored per user and are only reachable by the owning student after login. Provenance: explicit (Feature 2, database tables) plus required_inference for access continuity. Rationale: the workspace is private and durable.

NFR-5 — Large-PDF resilience Large PDFs are handled by chunking the extracted text before sending it to the LLM. Provenance: explicit (Rules). Rationale: a single oversized request would fail or truncate.

NFR-6 — Safe handling of bad LLM output Malformed or unexpected LLM output is handled safely — detected, rejected, and reported — and is never stored as broken content or rendered as a broken page. Provenance: explicit (Rules). Rationale: the LLM is an external, non-deterministic dependency.

NFR-7 — Code legibility for a viva Code is kept simple, with comments, so the author can explain it in a viva. Each file is delivered complete and working, with its file name above it. Provenance: explicit (Rules). Rationale: the project is a solo college project assessed by explanation.

NFR-8 — Stage-gated delivery The build proceeds in the seven specified stages and waits for the author to say "next" before the next stage. Provenance: explicit (Rules). Rationale: the author must be able to run and test each stage before continuing.

NFR-9 — Run and test instructions per stage After each stage, instructions for how to run and test that stage are provided. Provenance: explicit (Rules). Rationale: the author needs to verify each stage on Windows in VS Code.

NFR-10 — Readable text and controls at every viewport Headlines, wordmarks, labels, numbers, card text, and controls stay entirely inside the viewport and their container at 375px, 768px, and 1280px, wrapping or scaling (for example font-size: clamp(...) with its mobile size) to fit, and no other element covers any part of them. Imagery, decoration, and motion may be cropped, bled, rotated, overlapped, or cut as the creative direction asks, as long as they cover no readable text or control. Provenance: explicit (creative direction). Rationale: the study material and quiz controls must remain usable on a student's laptop and phone.

NFR-11 — Reduced-motion usability With prefers-reduced-motion, the product provides a usable static arrangement: the pipeline and any staggered reveals render fully composed, and any horizontally scrollable content wraps into rows or scrolls so each item can be brought fully into view. Provenance: explicit (creative direction). Rationale: motion is decorative here, never load-bearing.

10. Tech Stack

All choices below are source-specified and preserved exactly.

• Language / runtime: Python (the author is a beginner in Python; code is kept simple and commented).
• Web framework: Flask.
• Database: SQLite, with the tables users, documents (id, user_id, filename, upload_date), content (id, document_id, summary, points_json, diagram_code, chart_json), questions (id, document_id, topic, question, option_a–option_d, answer, difficulty), and attempts (id, user_id, question_id, correct, date).
• PDF processing: PyMuPDF, for page-by-page text extraction and embedded image extraction.
• LLM: Gemini free-tier API, with the API key kept in a .env file.
• Frontend: HTML / CSS / JavaScript.
• Diagram rendering: Mermaid.js (flowchart or mind map).
• Chart rendering: Chart.js.
• Animation: AOS animations (or CSS) for the key points that animate in one by one.
• Development environment: Windows + VS Code.

No additional frameworks, services, or deployment platforms are introduced by this document.

11. Assumptions and Constraints

Constraints (explicit, binding).

1. The project is a solo college project built by a Computer Engineering diploma student (Semester 3, GTU) with basic Java, DBMS, and HTML knowledge and beginner-level Python.
2. The tech stack is fixed as listed in Section 10; no substitutions.
3. The LLM API key must live in a .env file.
4. The build proceeds in stages and pauses until the author says "next".
5. Each stage is delivered as complete, working code per file, with the file name above it.
6. Code is kept simple with comments so it can be explained in a viva.
7. Large PDFs are handled by chunking, and bad LLM output is handled safely.
8. How to run and test is provided after each stage.
9. The build starts with Stage 1 (folder structure + DB setup).

Assumptions (narrow, labeled).

1. [Assumption — required_inference] The student creates their own account through self-service sign-up, and a returning student verifies at login. This is inferred because documents, generated content, questions, and attempts are durable and private to one student, so the workspace must be bound to the correct person.
2. [Assumption — required_inference] The Dashboard, Upload, Study page, Quiz page, and Personalization require login; the Landing, Login, and Sign Up pages are anonymous. This follows from the per-user durability of the stored data.

3. [Assumption — required_inference] PDF extraction and chunked LLM processing must complete or fail safely before the generated study and quiz views can be used; a document whose processing failed is not presented as ready.
4. [Assumption — required_inference] The Personalization view is a distinct destination because its working context (per-topic accuracy, weak-topic flags, re-reading recommendations, easier-question offers) and its completion outcome differ from the Study page and the Dashboard, even though it is reached from both.
5. [Assumption — required_inference] The Upload workflow is a distinct destination because its working context (file selection, validation feedback, processing progress) and its failure outcomes differ from the Dashboard's document list.
6. [Assumption — required_inference] The Landing, Login, and Sign Up pages are distinct anonymous entry surfaces: the Landing explains the product, and Login and Sign Up are separate identity actions that cannot themselves require login.
7. [Assumption — required_inference] The LLM provider is an external dependency; the application owns the prompt, chunking, JSON parsing, validation, and safe failure handling around it.
8. [Assumption — required_inference] The application owns student identity and session continuity only. No differentiated permissions, roles, or role-based visibility are introduced, because no source requirement establishes differentiated control over shared state.
9. [Assumption — required_inference] The seven stages are a delivery sequence for current scope, not a roadmap; all seven stages are in scope now.

Explicit exclusions. No multi-teacher or classroom administration, no social or sharing features, no payment, no mobile app, no subject-specific content packs, and no account-management surface beyond register/login. The product is not a general document-management system, not a course platform, and not a chat interface.

12. Glossary

• Student Learner — The sole in-product human actor: a student who registers, logs in, uploads PDFs, studies the generated visual material, takes quizzes, and reviews personalization and dashboard progress.
• Document — A PDF uploaded by a student and saved per user; stored in the documents table with id, user_id, filename, upload_date.
• Content — The generated learning material for a document; stored in the content table with id, document_id, summary, points_json, diagram_code, chart_json.
• Key points — Short bullet points generated from the PDF, displayed on the Study page and animated in one by one.
• Diagram code — The Mermaid flowchart or mind map source generated by the LLM and rendered with Mermaid.js.
• Chart data — The structured data generated when the PDF contains numbers or comparisons, rendered with Chart.js.
• Question — A generated MCQ; stored in the questions table with id, document_id, topic, question, option_a–option_d, answer, difficulty.
• Attempt — A record of one answer given by a student; stored in the attempts table with id, user_id, question_id, correct, date.
• Topic tag — The topic label attached to each generated question, used to compute accuracy per topic.
• Difficulty — The difficulty label attached to each generated question.
• Weak topic — A topic whose accuracy is under 60%, flagged on the Personalization view and the Dashboard.
• Chunking — Splitting extracted PDF text into smaller pieces before sending it to the LLM, so large PDFs can be processed.
• Bad LLM output — Malformed or unexpected JSON returned by the LLM; detected and handled safely rather than stored or rendered.

• Stage — One of the seven gated build steps (Stage 1 folder structure + DB setup through Stage 7 dashboard + UI polish), each delivered complete and paused until the author says "next".
• Pixel icon set — The 16×16 grid icon set (document, page, diagram, chart, quiz, weak-topic) used in the navigation rail, dashboard tiles, and empty states.