Personal Study Assistant

1. Product Overview

1.1. A learning companion that helps students and self-learners study

more effectively and retain what they learn.

1.2. Core problem: learners often struggle to know what to study, how to
study it, and whether they truly understand the material, leading to
wasted effort and low confidence. Should center the experience on
helping users learn better, not just consume more content.

2. Jobs to Be Done

2.1 Figuring out how to learn

2.1.1 An appropriate roadmap should be generated for the user .

2.1.2 User should be pushed into the correct direction , instead of

them trying to figure out how to learn .

2.1.3 User should be recommended some study techniques like

pomodoro technique, feynmann technique etc.

2.1.4 Prioritise important things over trivial ones .

2.2 Providing the users relevant resources for learning

2.2.1 Corresponding to each roadmap , appropriate reference books

, internet articles , blogs , videos , documentation (for coding) .

2.2.2 Providing deeper insights into a topic by an expert .

2.2.3 Providing the user PYQs , example problems , solved

problems , which could be especially useful for competitive exams .
 2.3 Interactive Learning

2.3.1 Include visual learning methods - like videos , flowcharts ,

drag and drop activities , diagrams , learning tree , Venn diagrams , etc.

2.3.2 Users should be able to revise their topics , and keep track of
their revision too .

2.3.3 User should be given activity questions , short quizzes ,

based on the content studied .

2.4 Tracking Progress

2.4.1 User should be able to keep track of what all he has learnt ,
what hasn’t , what’s he good at , etc .

2.4.2 User should be shown his strengths and weaknesses

2.4.3 User’s readiness for exams/interviews should be conveyed

appropriately .

2.5 Motivating The User

2.5.1 Provide encouragement by gamifying the user experience .

Help the user maintain study or revision streaks and habits .

2.5.2 Encourage the user to keep going on by validating their

progress , offering encouragement and helpful advice .

2.5.3 Act as a mentor or coach , answer questions anytime ,

guide learning decisions .
3. Functional Requirements

3.1 Learning Roadmap & Guidance

3.1.1 Personalized Roadmap Generator

● Generate learning paths based on user goals.

● Adapt roadmap based on current skill level.
● Break large subjects into milestones and subtopics.
3.1.2 Learning Navigator

● Recommend the next best topic to study.

● Prevent users from skipping critical prerequisites.
● Suggest alternate learning paths when users get stuck.
3.1.3 Study Strategy Recommendation Engine

● Recommend suitable study techniques (Pomodoro, Feynman,

Active Recall, Spaced Repetition, etc.).
● Recommend techniques based on subject type and learner
profile.
● Explain how and when to use each technique.
3.1.4 Topic Prioritization System

● Identify high-impact concepts.

● Mark topics as mandatory, recommended, or optional.
● Highlight frequently tested concepts for exams/interviews.

3.2 Learning Resource Discovery & Curation

3.2.1 Resource Recommendation Engine

● Recommend books, articles, blogs, videos, courses,

documentation, and tutorials.
● Map resources directly to roadmap topics.
● Filter resources by difficulty level and learning style.
3.2.2 Expert Insight Layer

● Provide expert explanations and practical insights.

● Surface common misconceptions and pitfalls.
 ● Explain real-world applications and industry relevance.
3.2.3 Practice Resource Repository

● Provide PYQs, solved examples, sample questions, and

exercises.
● Categorize questions by difficulty and topic.
● Recommend practice sets based on learner weaknesses.

3.3 Interactive Learning Experience

3.3.1 Interactive Content Generation

● Generate diagrams, flowcharts, concept maps, learning trees, and

visual summaries.
● Support drag-and-drop learning activities.
● Provide interactive simulations where applicable.
3.3.2 Revision Management System

● Allow users to mark topics for revision.

● Schedule revision sessions automatically.
● Maintain revision history and revision streaks.
3.3.3 Quiz & Assessment Engine

● Generate quizzes from studied content.

● Provide MCQs, short-answer questions, and application-based
questions.
● Give instant feedback and explanations.
3.3.4 Active Recall Support

● Generate flashcards automatically.

● Conduct conversational questioning sessions.
● Prompt learners to explain concepts in their own words.
3.3.5 Personalized Learning Sessions

● Adapt content difficulty dynamically.

● Adjust pace based on user performance.
● Recommend additional learning material when needed.
3.4 Progress Tracking & Performance Analytics
3.4.1 Learning Dashboard

● Track completed, ongoing, and pending topics.

● Display overall learning progress.
● Maintain learning history.
3.4.2 Strength & Weakness Analysis

● Identify strong and weak concepts.

● Track performance trends over time.
● Highlight areas needing improvement.
3.4.3 Readiness Assessment System

● Estimate exam readiness.

● Estimate interview preparedness.
● Provide confidence scores for different topics.
3.4.4 Learning Analytics & Insights

● Track study hours and consistency.

● Measure retention and recall performance.
● Generate periodic progress reports.

3.5 Motivation, Coaching & Engagement

3.5.1 Gamification Engine

● Maintain study streaks.

● Award points, badges, and achievements.
● Introduce milestone-based rewards.
3.5.2 Progress Validation & Encouragement

● Celebrate learning milestones.

● Provide personalized encouragement messages.
● Highlight improvement over time.
3.5.3 AI Learning Coach

● Answer learning-related questions anytime.

● Provide personalized study advice.
● Help users make learning decisions.
 3.5.4 Goal Management System

● Allow users to define learning goals.

● Break goals into achievable milestones.
● Track progress against goals.
3.5.5 Habit Formation Support

● Send study and revision reminders.

● Recommend optimal study schedules.
● Encourage consistent learning behavior.

3.6 Knowledge Validation & Mastery Measurement

3.6.1 Concept Mastery Evaluation

● Assess conceptual understanding.

● Detect misconceptions and knowledge gaps.
● Recommend remedial learning activities.
3.6.2 Practical Application Assessment

● Provide real-world problems and case studies.

● Evaluate application of knowledge.
● Measure problem-solving ability.
3.6.3 Retention Measurement System

● Evaluate long-term retention.

● Detect forgotten concepts.
● Trigger revision recommendations automatically.

4. Edge Cases & Failure Modes

4.1 Learning Roadmap & Guidance

4.1.1 Personalized Roadmap Generator

● User enters a goal so vague (e.g., "learn everything") that no

coherent roadmap can be generated — system must prompt for a
more specific goal.
 ● User's stated skill level contradicts their quiz/assessment
results — system should flag the mismatch and ask the user to
confirm rather than silently override.
● A subject has no well-established learning order (e.g.,
Creative Writing, Philosophy) — roadmap must handle non-linear or
cyclical dependency graphs.
● User wants to learn two conflicting or heavily overlapping
subjects simultaneously (e.g., two competing programming
frameworks) — system must handle resource and milestone
deduplication.
● Roadmap grows to 200+ topics — the UI must paginate or
collapse the tree; rendering the entire graph at once may freeze
low-end devices.

4.1.2 Learning Navigator

● User manually marks all prerequisites as complete without actually

studying them — navigator must enforce a minimum quiz score
before unlocking advanced topics.
● User skips a recommended topic after multiple prompts — system
must not loop indefinitely and should offer an alternate path.
● User is simultaneously progressing on two roadmaps whose
prerequisite chains share a topic — completing it in one roadmap
must reflect across both.

4.1.3 Study Strategy Recommendation Engine

● User has a documented learning disability (e.g., ADHD, Dyslexia)

and receives strategies that are ineffective for their learning needs.
● User requests a technique that contradicts evidence-based learning
for the chosen subject (e.g., pure re-reading for Mathematics) —
system should recommend alternatives without forcing them.
● Two recommended techniques have conflicting time requirements
within the same session — system must provide one clear
recommendation.

4.1.4 Topic Prioritization System

● User's target exam date is in the past due to a data-entry mistake —

system must validate dates before generating priorities.
● Two topics are marked mandatory while covering identical content
— deduplication must prevent inflated effort estimates.
4.2 Learning Resource Discovery & Curation
4.2.1 Resource Recommendation Engine

● Recommended video/article URL is broken or removed —

system must automatically suggest alternatives.
● Recommended resource is region-locked or paywalled for the
user's location.
● The same resource is recommended repeatedly across
multiple subtopics.
● User prefers a language for which limited learning resources
exist.
● Documentation links point to deprecated APIs or outdated
versions.
● Recommended resource difficulty does not match user
proficiency.
● Resource metadata (duration, difficulty, author, publication
date) is inaccurate.

4.2.2 Expert Insight Layer

● Expert content exists only in video form but the user requires
accessibility support (captions/transcripts).
● Expert insights contradict concepts the user has already
mastered.
● AI-generated expert insights contain factual inaccuracies.
● Different experts provide conflicting advice on the same topic.

4.2.3 Practice Resource Repository

● User exhausts all available PYQs for a niche certification.

● Practice question references an image that fails to load.
● User submits an extremely long open-ended answer that
exceeds supported limits.
● Solutions associated with questions are incorrect.
● Duplicate questions appear across multiple practice sessions.
● Questions belong to outdated exam syllabi.

4.3 Interactive Learning Experience

4.3.1 Interactive Content Generation
● Generated flowchart contains 50+ nodes and becomes
unreadable without zooming.
● Drag-and-drop activities become difficult to use on small
touchscreen devices.
● AI-generated concept maps time out due to long processing
times.
● Browser does not support technologies required for interactive
simulations.
● Generated diagrams contain overlapping labels or unreadable
content.
● Interactive content fails to load under poor network conditions.

4.3.2 Revision Management System

● User marks 80+ topics for revision on a single day, creating an

unrealistic schedule.
● Revision streak breaks because sessions occur across
midnight boundaries.
● User's device clock is incorrect, causing scheduling errors.
● User misses revisions for several weeks, creating hundreds of
overdue items.
● Duplicate revision reminders are generated for the same topic.

4.3.3 Quiz & Assessment Engine

● User attempts to generate a quiz without studying enough

content.
● Same question appears multiple times in the same quiz.
● User submits an empty answer.
● Network disconnects during quiz submission.
● Quiz timer continues running after an application crash.
● Assessment scores fail to save after submission.
● Questions are significantly easier or harder than the learner's
level.

4.3.4 Active Recall Support

● AI-generated flashcards contain factual errors.

● User starts a recall session before studying any content.
● User pastes an extremely large explanation (e.g., 10,000+
characters).
● Flashcard deck contains duplicate cards.
● Learner repeatedly receives already-mastered flashcards.
 4.3.5 Personalized Learning Sessions

● Difficulty drops sharply after a few incorrect answers caused

by fatigue.
● User intentionally answers incorrectly to receive easier
content.
● Personalization engine receives insufficient performance data.
● Adaptive recommendations conflict with the user's roadmap
sequence.

4.4 Progress Tracking & Performance Analytics

4.4.1 Learning Dashboard

● User has not studied anything yet and dashboard metrics

become meaningless.
● Topic is deleted from a roadmap after study time has already
been recorded.
● Dashboard attempts to load multiple years of detailed learning
history.
● Progress percentage exceeds 100%.
● Completed topics disappear after synchronization failures.

4.4.2 Strength & Weakness Analysis

● User has attempted too few assessments to generate reliable

conclusions.
● User is strong in theory but weak in practical application for
the same topic.
● Temporary poor performance incorrectly labels a topic as
weak.
● Analysis is generated from outdated assessment data.

4.4.3 Readiness Assessment System

● User's exam is tomorrow but only a small portion of the

syllabus is completed.
● User has not configured any target exam or interview.
● Readiness score is generated from insufficient evidence.
● Assessment model ignores practical problem-solving ability.
 4.4.4 Learning Analytics & Insights

● User accidentally leaves a study session running overnight,

recording 14+ hours.
● Study hours for a subject become negative due to
synchronization or calculation errors.
● Offline study sessions are duplicated after synchronization.
● Study sessions overlap and inflate total learning time.
● Progress reports cannot be delivered because notifications or
email are disabled.

4.5 Motivation, Coaching & Engagement

4.5.1 Gamification Engine

● User receives the same badge multiple times.

● Study streak breaks because of server outages rather than
user inactivity.
● Point counters exceed expected limits (e.g., 999,999+ points).
● Users discover loopholes to gain points without learning.
● Gamification begins to incentivize point collection over actual
learning.

4.5.2 Progress Validation & Encouragement

● User receives encouragement despite poor performance.

● Encouragement messages become repetitive and lose
effectiveness.
● Multiple milestone celebrations appear simultaneously.
● User remains inactive for weeks but continues receiving
excessive notifications.

4.5.3 AI Learning Coach

● User asks questions outside the learning domain (medical,

legal, personal advice).
● Coach provides factually incorrect guidance.
● Coach repeatedly misunderstands the user's question.
● User asks the same question many times due to frustration.
● Previous conversation context is lost during a coaching
session.
 4.5.4 Goal Management System

● User sets a goal requiring an unrealistic study schedule (e.g.,

20+ hours/day).
● Goal deadline is already in the past.
● User deletes a goal that still has active milestones.
● Multiple goals compete for the same study time allocation.
● Goal progress calculations become inconsistent after roadmap
modifications.

4.5.5 Habit Formation Support

● User disables notification permissions at the operating-system

level.
● Study reminders are delivered at inappropriate times after
international travel.
● Excessive reminders create notification fatigue.
● Reminder schedules conflict with user-defined availability
windows.

4.6 Knowledge Validation & Mastery

Measurement
4.6.1 Concept Mastery Evaluation

● User passes mastery checks by guessing correctly on

multiple-choice questions.
● Same concept appears under different names in different
roadmaps.
● Mastery is declared after too few assessments.
● Mastery calculations ignore long-term retention.
● User memorizes answers without understanding underlying
concepts.

4.6.2 Practical Application Assessment

● User submits code that enters an infinite loop.

● Case study references a third-party tool or API that no longer
exists.
● Multiple valid solutions exist but the grading system accepts
only one.
 ● Project-based evaluations are scored incorrectly.
● Users rely heavily on external assistance, inflating scores.

4.6.3 Retention Measurement System

● User returns after 90+ days of inactivity and receives

hundreds of overdue revisions.
● Retention model marks a concept as forgotten despite recent
strong quiz performance.
● Frequently revised concepts continue to be flagged as weak.
● Long inactivity periods distort forgetting-curve calculations.
● Revision recommendations become excessively frequent and
intrusive.

4.7 Data, Storage & Content Limits

4.7.1 Notes & Learning Content

● Notes exceed maximum character limits.

● User uploads unsupported file formats.
● Attached files exceed upload size limits.
● Embedded images fail to render.
● Auto-save fails while editing notes.
● Duplicate notes are created due to synchronization conflicts.
● User accidentally deletes important notes.

4.7.2 Media & Resource Delivery

● Videos fail to load because of bandwidth limitations.

● PDFs become corrupted or unreadable.
● External learning platforms experience downtime.
● Recommended resources are removed by third-party
providers.
● Downloaded resources exceed available device storage.

4.7.3 Account & Synchronization

● Progress is lost after logout or reinstallation.

● Offline activity fails to synchronize when connectivity returns.
● Simultaneous edits from multiple devices cause conflicts.
● Duplicate learning sessions appear after synchronization.
 ● Learning history is partially missing after device migration.

5. Non-Functional Requirements
5.1 Performance

● Response Time: The app shell must load within 2 seconds on a 4G

connection. AI-powered features (roadmap generation, coach responses)
must stream first tokens within 1.5 seconds and complete within 8 seconds
at P95. Quiz generation must complete within 3 seconds.
● Concurrent Users: The system must sustain 50,000 concurrent active
users without degradation, with the ability to auto-scale to 200,000 during
exam season peaks (e.g., March–April, October–November).
● Offline Performance: Core study flows — reading notes, reviewing
flashcards, and completing downloaded quizzes — must function fully
offline. Sync must complete within 30 seconds of reconnection with no
data loss.
● Dashboard Load: The learning dashboard must render meaningful data
within 3 seconds even for users with 2+ years of history, using server-side
aggregation rather than client-side computation.
● Diagram & Visual Generation: AI-generated flowcharts, concept maps,
and learning trees with up to 100 nodes must render within 5 seconds.
Beyond 100 nodes, the system must offer a simplified summary view.

5.2 Reliability & Availability

● Uptime SLA: 99.9% monthly uptime (≤ 43.8 minutes of downtime

per month) for all core learning flows. AI coaching and generation
features may degrade to 99.5% with graceful fallback to pre-
generated or cached content.
● Data Durability: User progress, quiz results, notes, and streaks
must be persisted with zero data loss. RPO (Recovery Point
Objective) ≤ 1 minute; RTO (Recovery Time Objective) ≤ 15
minutes.
● Graceful Degradation: If the AI service is unavailable, the app must fall
back to static resources, cached recommendations, and pre-built quizzes
 — without showing a full error screen. Affected features must be labelled
"temporarily unavailable."
● Streak Protection: Streak data must be immune to server-side outages.
Any day lost due to a verified infrastructure failure must be automatically
restored, logged, and communicated to the user.
● Sync Reliability: Offline sessions must sync atomically on reconnection
— no partial writes, no duplicate session records. Conflicts from
simultaneous multi-device edits must be resolved using a last-write-wins
policy with a conflict log visible to the user.

5.3 Scalability

● Per-User Storage: The system must support up to 5 GB of notes,

flashcards, and downloaded resources per user without performance
degradation.
● Roadmap Complexity: The roadmap engine must handle subjects with up
to 1,000 topic nodes and 3,000 dependency edges without UI freeze or
generation timeout.
● Historical Data: Analytics queries spanning 3+ years of user history must
be served from pre-aggregated tables, not raw event logs, to keep query
times under 2 seconds.
● Content Catalogue: The resource catalogue must scale to 10 million+
indexed resources across all subjects and languages without degrading
recommendation latency.

5.4 Security & Privacy

● Authentication: Email + password (bcrypt, cost factor ≥ 12),

Google OAuth 2.0, and Apple Sign-In must all be supported at
launch. Multi-factor authentication must be available as an opt-in
for all users.
● Session Management: Access tokens expire after 15 minutes; refresh
tokens expire after 30 days of inactivity. A maximum of 5 concurrent device
sessions per user is enforced, with the ability to remotely revoke any
session.
● Data Isolation: Every database query must be scoped by user_id at the
ORM layer. No cross-user data leakage is permissible even within a multi-
tenant architecture. Raw SQL bypassing the ORM requires a security
review sign-off.
 ● Encryption: All data in transit must use TLS 1.3+. All data at rest must use
AES-256. PII fields (name, email, phone) must be double-encrypted at the
application layer.
● AI Content Audit: All AI-generated content — flashcards, coach
messages, quiz questions — must carry an ai_generated flag, be
surfaceable for human review, and be disclaimable in the UI.
● Data Privacy (GDPR/DPDP): Users must be able to export all their data
within 72 hours of request (GDPR Article 20) and request full, irreversible
deletion within 72 hours (Article 17). The app must comply with India's
Digital Personal Data Protection Act (DPDP) 2023 for users in India.

5.5 Accessibility

● WCAG Compliance: All screens must meet WCAG 2.1 Level AA. All
interactive elements — quizzes, drag-and-drop, flashcards — must be fully
keyboard-navigable and compatible with screen readers (VoiceOver,
TalkBack).
● Text Scaling: The entire UI must remain fully usable at system font sizes
up to 200% without horizontal scroll, content clipping, or broken layouts.
● Colour Contrast: All text-on-background combinations must meet a
minimum contrast ratio of 4.5:1 (AA). Primary body text must meet 7:1
(AAA).
● Media Accessibility: All recommended videos surfaced in the app must
carry verified subtitles or transcripts before being shown to users who have
enabled accessibility mode. Audio-only content must have a text
equivalent.
● Touch Targets: All interactive elements must meet a minimum tap target
size of 44 × 44 px, particularly for drag-and-drop activities and flashcard
controls.

5.6 Usability

● Onboarding Completion Rate: ≥ 80% of new users must complete

the goal-setting and skill-assessment onboarding flow within their
first session. If a user exits mid-onboarding, progress must be
saved and resumed on next launch.
● Error Messaging: Every user-facing error must state: what went wrong,
why it happened, and what the user should do next. No raw error codes,
HTTP status numbers, or stack traces must appear in the production UI.
 ● Mobile-First Layout: All core flows must be fully operable on a 375 px
viewport (iPhone SE baseline) without horizontal scrolling. Complex views
like the roadmap graph must offer a mobile-optimised collapsed view by
default.
● Empty States: Every dashboard widget, list, and analytics panel must
have a meaningful empty state — a helpful prompt or call-to-action —
rather than a blank card, zero%, or divide-by-zero error.
● Loading States: Every AI-powered operation that takes more than 1
second must show a loading indicator with an estimated wait time.
Operations exceeding 10 seconds must offer a "notify me when ready"
option.

5.7 Maintainability & Observability

● Test Coverage: Unit test coverage must be ≥ 80% for all business-
logic modules (streak calculation, spaced repetition, mastery
evaluation, roadmap generation). Integration tests are mandatory
for all critical user flows.
● Logging & Tracing: Structured logs must be emitted for every AI call,
resource fetch, quiz submission, and sync event. Distributed tracing
(OpenTelemetry or equivalent) must span all backend services to enable
root-cause analysis within 15 minutes of an incident.
● Feature Flags: All major features must be deployable behind
feature flags. New AI model versions must be A/B tested on ≤
10% of users before full rollout, with automatic rollback if error
rates exceed a defined threshold.
● Alerting: Automated alerts must fire within 5 minutes if: AI response P95
latency exceeds 10 seconds, error rate exceeds 1% on any critical
endpoint, or sync failure rate exceeds 0.5%.

5.8 Localisation & Internationalisation

● Language Support: The full UI must be localised in English, Hindi, and

Spanish at launch. Date, time, and number formats must adapt to the
user's locale automatically.
● RTL Support: Right-to-left layout support (for Arabic, Hebrew, Urdu) must
be architected into the design system from day one, even if not fully
activated until Phase 2.
● Resource Availability Transparency: When fewer than 3 learning
resources exist for a topic in the user's selected language, the system
 must display a clear notice ("Limited resources available in your
language") and offer English-language alternatives — never silently return
zero results.
● Timezone Handling: All server-stored timestamps are UTC. Streak
calculations, reminder scheduling, and session recording must always use
server-side UTC as the source of truth; the device's local timezone is used
solely for display.

6. Technical Design — Entity Relationships

6.1 Core Principle

A User is the owner of everything. All data belongs to exactly one user, and a
user only ever sees their own. The only exceptions are globally shared catalogue
entities — Resources, Badge definitions, and Question banks — which are read-
only for users and managed by the platform.

6.2 Entities & Relationships

User : The root entity. Every other entity either belongs to a User directly or
traces back to one through a parent entity. Stores: name, email (encrypted),
hashed password, preferred language, timezone, accessibility settings,
notification preferences, and subscription tier. A User has many Goals,
StudySessions, Notifications, and AICoachMessages.

Goal : Belongs to one User. Represents the user's top-level learning intention —
e.g., "Clear UPSC Prelims 2026" or "Get a job as a backend engineer." Stores:
title, description, target date, and status (active | completed | archived). A Goal
has one or more Roadmaps. Deleting a Goal cascades to archive — not hard-
delete — all its Roadmaps, Milestones, and linked ProgressRecords, so historical
data is preserved.

Roadmap : Belongs to one Goal (and therefore one User). Represents a

directed acyclic graph (DAG) of Topics for a given subject. Stores: subject name,
difficulty level, creation source (ai_generated | manual), and status (active |
archived). A User may have many Roadmaps across different Goals. A
Roadmap has many Topics; the ordering and dependencies between Topics are
stored in a separate TopicDependency join table (topic_id →
prerequisite_topic_id) to keep the Topic entity flat and queryable.

Topic : Belongs to one Roadmap. Represents a single learnable unit — a

chapter, concept, or skill. Stores: canonical_id (a platform-wide slug used to
deduplicate the same concept appearing in multiple Roadmaps), title, priority
(mandatory | recommended | optional), estimated_duration_minutes, and status
(not_started | in_progress | completed | archived). A Topic has many Resources
(via a join table), many Notes, many Flashcards, many QuizQuestions, and one
ProgressRecord. Prerequisites are expressed via the TopicDependency table,
not as a field on Topic itself.

TopicDependency : A join table. Each row expresses: "Topic B requires Topic A

to be completed first." Stores: roadmap_id, topic_id, prerequisite_topic_id. This
structure allows the navigator to compute the next unlockable topic without
loading the full graph into memory.

Resource : A globally shared catalogue entity — not owned by a single user.

Represents an external learning asset. Stores: url, title, type (video | article | book
| documentation | course | blog | podcast), language, difficulty (beginner |
intermediate | advanced), author, published_at, and is_broken (set by an async
health-check job that runs every 7 days). Resources are linked to Topics via a
TopicResource join table that additionally stores a relevance_score and
region_lock flags. Broken or region-locked resources are filtered out at query
time, never at write time, so the catalogue remains intact.
Note : Belongs to one User and one Topic. Stores: body (plain text or markdown,
max 50,000 characters enforced at both the API and DB constraint layer),
created_at, updated_at, and is_deleted (soft-delete flag). Notes are never hard-
deleted — they are archived when their parent Topic is archived. Auto-save
events write a draft version every 30 seconds; the draft is promoted to the live
Note on explicit save or session close.

Flashcard : Belongs to one User and one Topic. Stores: front, back,
creation_source (ai_generated | manual), is_flagged_incorrect, and created_at. A
Flashcard has exactly one SpacedRepetitionRecord. Duplicate flashcards
within the same Topic (identical front text) are rejected at the API layer.

SpacedRepetitionRecord : One-to-one with a Flashcard. Stores:

next_review_date (UTC), interval_days, ease_factor, repetition_count, and
last_reviewed_at (UTC). All date comparisons run against server-side UTC. The
forgetting curve recalculates after every review. When a user returns after 90+
days of inactivity, the system caps the daily review batch at a configurable
maximum (default: 30 cards/day) rather than scheduling everything at once —
the backlog drains gradually.

StudySession : Belongs to one User and one Topic. Records a single

focused study event. Stores: session_type (reading | flashcards | quiz |
recall | video), started_at (UTC), ended_at (UTC), and duration_seconds
(computed server-side as ended_at − started_at). Hard constraints:
duration_seconds must be ≥ 0 and ≤ 36,000 (10 hours); any session
exceeding 10 hours is flagged for user confirmation before being
recorded. Study hours can never be negative — any sync correction
that would produce a negative value is floored to zero and logged for
audit.

Quiz : Belongs to one User. Represents a single quiz attempt. Stores: topic_ids
(one or many topics covered), question_count, started_at, completed_at,
score_percent, and quiz_type (topic_review | mock_exam | weakness_drill |
mastery_check). A Quiz cannot be generated if the user has studied fewer than 3
items for the target topic — this is enforced at the service layer. A Quiz has many
QuizQuestions.
QuizQuestion : Belongs to one Quiz. Stores: question_text, question_type (mcq
| short_answer | application), options (JSON array, MCQ only), correct_answer,
user_answer, is_correct, and feedback_text. User answers are immutable once
submitted. Empty submissions are recorded as incorrect with standard feedback
— they never cause an error. Questions are deduplicated at quiz-assembly time
so the same question cannot appear twice in a single Quiz.

ProgressRecord : One-to-one with a (User × Topic) pair. The single source of

truth for a user's standing on a given topic. Stores: mastery_score (0–100),
quiz_attempts, correct_rate_last_5, last_assessed_at, is_mastered (boolean —
only set true after passing at least 2 spaced-repetition-gated assessments, not
just one high score), and confidence_score. A jump from below 80 to 100 in a
single attempt is flagged as anomalous and triggers a mastery verification quiz
before the topic is marked complete.

Streak : One-to-one with a User. Stores: current_streak_days,

longest_streak_days, last_activity_date (UTC), and
outage_restored_days (a count of days credited back due to verified
server outages). Streak logic runs server-side on UTC midnight so
device clock manipulation cannot affect it. A "streak day" is satisfied if
at least one StudySession of ≥ 5 minutes is completed within a rolling
24-hour UTC window.

Badge : A globally shared catalogue entity (not per-user). Stores: name,

description, icon_url, trigger_condition (e.g., "7_day_streak",
"first_topic_mastered"), and is_repeatable. A UserBadge join table records:
user_id, badge_id, awarded_at, and award_count. Before awarding a badge, the
system checks UserBadge — if is_repeatable is false and a record already
exists, the award is silently skipped.

Notification : Belongs to one User. Stores: type (study_reminder | revision_due |

milestone | coach_nudge | streak_warning), scheduled_for (UTC), delivered_at,
opened_at, and channel (push | in_app | email). When push permissions are
revoked at the OS level, the channel falls back to in_app automatically —
notifications are never silently dropped. Undelivered notifications older than 7
days are archived, not deleted, so the audit log is preserved.

AICoachMessage : Belongs to one User. Represents a single turn in a coaching

conversation. Stores: session_id (groups messages into a conversation), role
(user | assistant), content_text, timestamp (UTC), is_flagged_incorrect, and
flag_reviewed_at. Messages are retained for 90 days for audit and model fine-
tuning. The full session_id message chain is passed as context on every new
turn so the coach has continuity within a session — but context does not persist
across separate sessions unless the user explicitly saves a summary.

LearningGoalMilestone : Belongs to one Goal. Represents an intermediate

checkpoint on the path to a Goal — e.g., "Complete the OS module" or "Score
70%+ on 3 mock tests." Stores: title, due_date, linked_topic_ids (array),
is_completed, and completed_at. Milestones are cascade-archived when their
parent Goal is deleted. If a linked Topic is removed from the Roadmap, the
milestone still exists but the orphaned topic_id is flagged for the user to re-map.

6.3 Key Constraints & Invariants

● All timestamps are stored and compared in UTC. Device timezone is used
only for display and reminder scheduling.
● StudySession.duration_seconds is always ≥ 0 and ≤ 36,000.
Violations are rejected at the API boundary.
● [Link] is capped at 50,000 characters;
QuizQuestion.user_answer at 5,000 characters — enforced at both
the API validation layer and as a DB column constraint.
● A ProgressRecord.is_mastered flag can only be set to true by the
server after a minimum of 2 passing assessments across 2 separate
sessions. Client-side writes to this field are rejected.
● Resource URLs are health-checked asynchronously every 7 days.
Broken resources are flagged and hidden from all recommendation queries
until manually reviewed and unflagged.
● All AI-generated content carries an ai_generated: true flag. This field
is immutable after creation.
 ● Every database query involving user data must include a user_id scope
clause. Raw SQL that bypasses the ORM requires a mandatory security
review before merging.
● Streak state is computed and written server-side only. No client can
directly write to current_streak_days or last_activity_date.

7. AI Leverage - How do we leverage AI ?

7.1 Core Principle

AI is not a feature in this product — it is the engine. Every major user flow is
either initiated, personalised, or evaluated by an AI model. The goal is not to
surface content faster but to replace the role of a good human tutor: one who
knows what you know, what you don't, how you learn best, and what to say to
keep you going.

7.2 Roadmap & Learning Path Generation

What AI does: The AI takes a user's stated goal, current skill level, available
time per day, and target date — and generates a fully structured, dependency-
ordered learning roadmap. It understands prerequisite chains (you cannot learn
dynamic programming before understanding recursion), estimates time per topic
based on subject complexity, and calibrates the path for the user's level so a
beginner and an advanced learner pursuing the same goal get meaningfully
different roadmaps.

How it adapts: As the user progresses, the AI continuously re-evaluates the

roadmap. If the user is consistently underperforming on a cluster of topics, the AI
inserts remedial content. If they are flying through a section, it compresses or
skips lower-priority subtopics. The roadmap is never static after generation.

Failure handling: If the goal is too vague for the AI to generate a coherent path,
it must ask targeted clarifying questions — not return a generic roadmap or an
error screen.

7.3 Personalised Resource Curation

What AI does: For each topic on a user's roadmap, the AI ranks and filters the
global resource catalogue — books, videos, articles, documentation, blogs —
based on the user's learning style preference (visual, reading-heavy, example-
driven), their current proficiency on the topic, and their past engagement patterns
(did they finish the last video? did they rate the last article highly?). It does not
just return the highest-rated resource globally; it returns the right resource for this
specific user at this specific moment.

How it adapts: If a user consistently abandons videos halfway through but

finishes articles, the AI shifts its recommendations toward text. If a user has
flagged a resource as unhelpful, that signal is fed back into the ranking model for
their future sessions.

Failure handling: When no suitable resource exists in the catalogue for a topic
in the user's language or at their level, the AI must say so explicitly and offer the
closest available alternative — it must never hallucinate a resource URL or
silently recommend something irrelevant.

7.4 Quiz & Assessment Generation

What AI does: Rather than pulling from a fixed question bank, the AI generates
contextually relevant quiz questions from the user's own notes, the resources
they studied, and the topic's core concepts. It produces a mix of question types
— MCQs for recall, short-answer for comprehension, application questions for
deeper understanding — calibrated to the user's current mastery score on that
topic.

How it adapts: The difficulty of generated questions adjusts in real time based
on the user's running performance within the session. A user answering correctly
consistently will receive progressively harder questions. A user struggling will
receive easier foundational questions before stepping back up.

Failure handling: The AI must not generate a quiz if insufficient study content
exists for the topic. Factually incorrect questions flagged by the user are logged,
removed from active rotation immediately, and queued for review — the AI does
not re-serve a flagged question until it has been verified.

7.5 Active Recall & Flashcard Generation

What AI does: After a user studies a topic — reads notes, watches a video,
completes a session — the AI automatically extracts the key concepts and
generates flashcard pairs (front: question or term; back: answer or definition). It
identifies the highest-value concepts to convert rather than generating a card for
every sentence, producing a focused, high-signal deck rather than an
overwhelming one.

How it adapts: The AI integrates with the spaced repetition engine. It tracks
which cards the user consistently gets right and gradually retires them from
active rotation. Cards that are repeatedly answered incorrectly are rewritten by
the AI in a simpler or differently framed way to break the pattern of repeated
failure.

Failure handling: Every AI-generated flashcard carries a "flag as incorrect"

option. Flagged cards are immediately hidden from the user's deck and queued
for AI re-generation or human review, not just silently retired.

7.6 AI Learning Coach (Conversational Tutor)

What AI does: The AI coach acts as an always-available personal tutor. Users

can ask it anything about a topic they are studying — "explain this concept
differently," "why does this formula work," "what is the difference between X and
Y," "I keep getting this wrong, what am I missing." The coach has full context of
the user's roadmap, current topic, recent quiz performance, and study history, so
its answers are always situated in what the user already knows and what they
are working toward.

How it adapts: The coach adjusts the complexity of its explanations based on
the user's assessed level. It uses analogies calibrated to the user's background
— a medical student studying data structures will receive different analogies than
a computer science undergraduate. When it detects a frustration pattern
(repeated same question, declining quiz scores), it proactively shifts to a Socratic
questioning approach rather than re-explaining the same content.

Failure handling: The coach must recognise and decline out-of-scope queries
(medical advice, legal questions, personal problems) with a polite redirect. When
it detects that it has given an incorrect answer (via user flag or internal
confidence threshold), it must acknowledge the error explicitly, correct itself, and
not defensively repeat the wrong answer. If a user asks the same question five or
more times in a session, the coach must escalate — offering an alternative
explanation format, a resource link, or a suggestion to take a break.
7.7 Strength & Weakness Analysis

What AI does: The AI continuously analyses the user's performance data across
all quizzes, recall sessions, and active recall responses to build a dynamic
concept-level understanding map. It distinguishes between surface-level
familiarity (can recall the definition) and deep understanding (can apply the
concept to a novel problem), and flags which type of weakness a user has for
each topic.

How it adapts: The AI does not label a topic as "weak" based on one bad quiz. It
looks for patterns across multiple sessions and over time. A topic is only flagged
as a genuine weakness when performance is consistently below threshold
across at least three separate assessments. Temporary dips due to fatigue or
distraction are smoothed out.

Failure handling: When the data is insufficient to make a reliable judgement

(fewer than 3 assessments on a topic), the AI must display a confidence indicator
— "Based on limited data" — rather than presenting a weak conclusion with false
confidence.

7.8 Exam & Interview Readiness Assessment

What AI does: Given a user's target exam or interview type, the AI models what
a passing candidate looks like — required topics, minimum mastery thresholds,
practical skills — and compares that against the user's current ProgressRecords.
It outputs a readiness score per topic and an overall readiness percentage, along
with a prioritised list of the highest-impact gaps to close before the target date.

How it adapts: As the target date approaches, the AI shifts its prioritisation
strategy — moving from depth-first to triage mode, focusing the user exclusively
on high-frequency, high-weight topics rather than comprehensive coverage. It
recalculates the readiness estimate after every completed session so the score
always reflects current state.

Failure handling: If the target date is tomorrow and readiness is critically low,
the AI must not inflate the score to be encouraging. It must present the reality
clearly, immediately offer a triage plan for the remaining time, and avoid
demotivating language. A score of 23% shown with a concrete 12-hour action
plan is more useful than a softened score with no plan.
7.9 Habit & Motivation Intelligence

What AI does: The AI monitors the user's study behaviour patterns — time of
day they are most productive, session lengths before drop-off, subjects they
avoid, days they are most likely to skip — and uses this to generate a
personalised study schedule and reminder strategy. It does not send reminders
at fixed times; it sends them at the times that have historically correlated with the
user actually studying.

How it adapts: If a user's engagement with reminders drops off

(notifications opened but no session started, or notifications ignored
entirely), the AI changes its approach — reducing frequency, changing
the message tone, or switching channel (push → in-app banner). It
never escalates volume when a user is disengaging; it de-escalates
and recalibrates.

Failure handling: The AI must never send motivational messages that imply
guilt or shame for inactivity. After 30 consecutive days of inactivity, the message
strategy must shift to a low-pressure re-engagement prompt — a single message
offering a very small, easy re-entry action — rather than continuing a cycle of
ignored notifications.

7.10 Content Integrity & Hallucination Guardrails

What AI does: Every piece of AI-generated content — roadmap topics, flashcard

answers, quiz question feedback, coach explanations — is tagged with an
ai_generated flag and a confidence tier (high | medium | low). Low-confidence
outputs are either withheld pending review or shown with an explicit disclaimer.
Users can flag any AI output as incorrect with a single tap, triggering immediate
removal from active use and queuing for human review.

How it is governed: The AI is never the final authority on factual correctness in

high-stakes domains (medicine, law, mathematics proofs). In these domains, AI
outputs are cross-referenced against the curated resource catalogue before
being served. The coaching layer is explicitly scoped to learning guidance — it
does not give advice outside its domain, and it acknowledges uncertainty rather
than confabulating confident-sounding answers.