Mindlexa details

MindLexa — Product Requirements Document

Version: 1.0
Stack: Django + React + PostgreSQL
Author: Internal
Status: Pre-Development

---

Table of Contents

1. Product Overview
2. System Architecture
3. Feature Catalog
4. Operation Pipelines
5. API Design
6. Data & Dictionary Strategy
7. Frontend Architecture
8. Background Jobs & Async
9. Security & Privacy
10. Phase Plan & MVP Scope
11. Non-Functional Requirements
12. Open Questions

---

1. Product Overview

1.1 What MindLexa Is

MindLexa is a Bangla-first English vocabulary learning web application. Its core loop is: encounter a word → understand it in context → retain it through spaced repetition → confirm mastery via review.

It is not a dictionary. It is not a flashcard app. It is a complete vocabulary acquisition system that meets the user wherever they encounter English — a PDF, a webpage, a textbook — and converts that encounter into a learning event.

1.2 Target Users

• Primary: Bangladeshi students (Class 6–HSC, undergraduate) preparing for exams (SSC, HSC, JBA, admission tests, IELTS, SAT).
• Secondary: General Bangladeshi users who want to improve English for career/daily use.

1.3 Core Learning Philosophy

• Words learned without context are forgotten within days. Context is the core data unit, not definitions.
• Spaced repetition (FSRS algorithm) is the only scientifically validated method for long-term retention at scale.
• Vocabulary size is measurable. Every feature must contribute toward the user seeing their vocabulary growing.

1.4 Guiding Constraints

• The entire UI must be usable on a mid-range Android phone on a 4G connection.
• Bangla script must render correctly at all sizes without third-party font loading failures.
• All features requiring AI (embeddings, context-aware definitions) must degrade gracefully when the API is unavailable.
• No feature should require the user to leave the app to “do something” and come back.

---

2. System Architecture

2.1 High-Level Stack

┌─────────────────────────────────────────────────────────┐
│                      Client Layer                        │
│   React SPA (Vite)  │  Browser Extension (MV3)          │
└────────────┬────────────────────────┬────────────────────┘
             │ HTTPS / REST           │ HTTPS / REST
┌────────────▼────────────────────────▼────────────────────┐
│                     Django Backend                        │
│  Django Ninja (API)  │  Celery Workers  │  Django Admin  │
└────────────┬────────────────────────┬────────────────────┘
             │                        │
┌────────────▼──────────┐  ┌──────────▼──────────────────┐
│  PostgreSQL 16         │  │  Redis                       │
│  + pg_trgm            │  │  - Celery broker/result       │
│  + pgvector           │  │  - API response cache         │
│  + pg_fts             │  │  - Session store              │
└───────────────────────┘  └──────────────────────────────┘

2.2 Django App Structure

mindlexa/
├── config/
│   ├── settings/
│   │   ├── base.py
│   │   ├── development.py
│   │   └── production.py
│   ├── urls.py
│   └── celery.py
├── apps/
│   ├── dictionary/         # Word, WordSense, ExampleSentence, WordRelationship, ContextExample
│   ├── users/              # User, UserWordKnowledge, UserIgnoredWord
│   ├── learning/           # Deck, DeckWord, UserDeckSubscription, Flashcard, SpacedRepetitionData
│   ├── documents/          # UserDocument, DocumentReadingProgress
│   ├── extension/          # ExtensionLookup
│   └── analytics/          # Aggregated, anonymized usage stats
├── api/
│   ├── v1/
│   │   ├── dictionary.py
│   │   ├── learning.py
│   │   ├── users.py
│   │   ├── documents.py
│   │   └── extension.py
│   └── schemas/            # Pydantic schemas for Django Ninja
├── tasks/
│   ├── embeddings.py       # Celery tasks for vector generation
│   ├── ocr.py              # Celery tasks for PDF/image OCR
│   ├── nlp.py              # Celery tasks for text parsing
│   └── analytics.py        # Periodic aggregation jobs
└── management/
    └── commands/
        ├── import_nctb.py
        ├── import_ielts.py
        ├── seed_frequency_ranks.py
        └── generate_embeddings.py

2.3 React App Structure

src/
├── app/
│   ├── store.ts            # Redux Toolkit store
│   ├── router.tsx          # React Router v6
│   └── App.tsx
├── features/
│   ├── dictionary/         # Word lookup, word detail page
│   ├── flashcards/         # Flashcard creation, review session (SRS)
│   ├── decks/              # Deck browser, deck detail, subscriptions
│   ├── pdfReader/          # PDF.js integration, colorization, word selection
│   ├── textToFlashcard/    # Paste text → extract words → batch add
│   ├── wordGraph/          # D3.js-powered related word visualization
│   ├── quiz/               # Quiz, matching, gap-fill game modes
│   └── auth/               # Login, register, profile
├── shared/
│   ├── components/         # WordCard, SenseChip, PronunciationButton, etc.
│   ├── hooks/              # useWordLookup, useSRS, useColorize, etc.
│   └── api/                # RTK Query endpoint definitions
└── workers/
    └── colorize.worker.ts  # Web Worker for PDF word colorization

2.4 Key Architectural Decisions

Decision	Choice	Reason
API framework	Django Ninja	Native async, Pydantic schemas, auto OpenAPI docs
SRS algorithm	FSRS (v4)	Empirically superior to SM-2 for retention
Search	PostgreSQL pg_trgm + FTS	No Elasticsearch dependency for MVP
Vector search	pgvector	Native Postgres, no separate vector DB needed
Async tasks	Celery + Redis	Mature, well-documented, handles OCR/embedding queues
State management	Redux Toolkit + RTK Query	Caching, optimistic updates, code-gen from OpenAPI
PDF rendering	PDF.js	Only mature open-source option, custom text layer support
Auth	JWT (djangorestframework-simplejwt)	Stateless, works for browser extension too

---

3. Feature Catalog

Every feature below is labeled with a phase: [MVP], [P2], or [P3].

---

3.1 Dictionary & Word Lookup

3.1.1 Word Lookup [MVP]

• User types a word in the search bar.
• System returns all WordSense entries for that word.
• Each sense shows: part of speech, sense number, meaning_en, meaning_bn, example sentences in English and Bangla, usage notes.
• Micro-features:
  • Real-time suggestions as user types (debounced, 300ms).
  • If word not found in DB, fallback to a “Did you mean…?” trigram suggestion list.
  • Pronunciation button: plays audio from Word.audio_url if available; falls back to browser Web Speech API.
  • UK/US phonetic display toggle.
  • “Add to My Library” button directly from the result.
  • “Mark as Known” button to set UserWordKnowledge.status = KNOWN.

3.1.2 Banglish Search [MVP]

• User types romanized Bangla (e.g., “akash”, “bhalobasa”) in the search bar.
• System queries WordSense.banglish_keywords using PostgreSQL trigram similarity.
• Returns ranked results by similarity score > 0.3.
• Micro-features:
  • Handles common typo variants (e.g., “obhidhan”, “abhidhan”, “ovhidhan” all return “অভিধান”).
  • Banglish input is detected automatically (no Latin English dictionary words matching).

3.1.3 Word Detail Page [MVP]

• Dedicated page at /word/{slug}.
• Sections: All senses (tabbed by POS), all example sentences, synonyms/antonyms carousel, related words from Word Graph.
• Micro-features:
  • “Words from the same root” section using WordRelationship.relation_type = 'root'.
  • Collocations section.
  • User note field (saved to Flashcard.user_note if the word is in their library).
  • “You encountered this word N times” counter from UserWordKnowledge.encounter_count.

---

3.2 Flashcard System

3.2.1 Flashcard Creation [MVP]

• A user can create a flashcard for any WordSense.
• Flashcard creation triggers:
  1. UserWordKnowledge upsert → status set to LEARNING.
  2. SpacedRepetitionData row created with state=0 (New), due_date=now().
• Micro-features:
  • User can choose which sense to make a flashcard for when a word has multiple senses.
  • User can attach a custom context sentence if no ContextExample exists.
  • User can assign the flashcard to an existing deck or create a new one.
  • User can write a personal mnemonic (user_note).

3.2.2 SRS Review Session [MVP]

• Entry point: “Study Now” button showing N due cards.
• Session flow:
  1. Fetch up to 20 due SpacedRepetitionData records where due_date <= now() and user = request.user, ordered by due_date ascending.
  2. Show front of card (word, phonetic, context sentence).
  3. User flips card manually.
  4. User rates recall: Again (1), Hard (2), Good (3), Easy (4).
  5. FSRS algorithm computes new stability, difficulty, due_date, state.
  6. Card goes to back of session queue if rated 1 or 2 (learning/relearning state).
  7. Session ends when queue is empty.
• Micro-features:
  • Session progress bar (X / total due).
  • Undo last rating (stores last 1 action in session state).
  • “Skip” button sends card to end of queue without recording a review.
  • End-of-session summary: cards reviewed, again%, retention rate, streak updated.
  • Daily goal progress widget updates after session.
  • Audio pronunciation on card flip.

3.2.3 Flashcard Management [MVP]

• Deck browser: list all user’s decks, sortable by last accessed / card count / due count.
• Deck detail: list all cards in deck, with individual status indicators (New / Learning / Review / Mastered).
• Micro-features:
  • Bulk move cards between decks.
  • Delete a flashcard (cascades to SpacedRepetitionData; updates UserWordKnowledge if no other flashcard exists for that word).
  • Edit card: change attached sense, context, note.
  • “Reset progress” button per card (resets SRS to New state).
  • Filter cards by state: New, Due Today, Mastered.

---

3.3 Learning Modes

3.3.1 Quiz Mode [P2]

• Standard multiple-choice quiz from user’s deck or a pre-made library deck.
• Question types (randomized):
  • Show English word → pick correct Bangla meaning from 4 options.
  • Show Bangla meaning → pick correct English word from 4 options.
  • Show context sentence with word blanked → pick correct word from 4 options.
• Distractors are pulled from: (a) words in the same deck, (b) words with similar frequency rank.
• Micro-features:
  • Incorrect answer shows the correct answer with full word detail.
  • Quiz result updates UserWordKnowledge.confidence field.
  • Timed mode (30 seconds per question, optional).
  • Score history chart per deck.

3.3.2 Matching Mode [P2]

• Grid of word-meaning pairs in scrambled order.
• User drags/taps to match English word with Bangla meaning.
• 6 pairs per round, drawn from due-soon flashcards.
• Micro-features:
  • Timer counts up (no pressure, just for tracking).
  • Correct pair animates green and locks.
  • Wrong pair shakes red.
  • Completion shows time taken and accuracy.

3.3.3 Gap-Fill Mode [P2]

• A paragraph (pulled from ExampleSentence or ContextExample) is shown with target words blanked.
• User types the missing word.
• Evaluation: case-insensitive, trims whitespace. Partial credit for first 3 characters correct.
• Micro-features:
  • Hint button reveals first letter (penalizes score).
  • After submission: correct answers highlighted, incorrect shown with correct word.
  • Source attribution shown (“From: NCTB Class 8 – Lesson 3”).

---

3.4 Digital Library & Deck System

3.4.1 Pre-Made Library [MVP]

• Browse official decks organized by hierarchy: Board → Class Level → Subject → Lesson.
• Hierarchy UI: collapsible tree or breadcrumb navigation.
• Each deck card shows: title, word count, subscriber count, cover image.
• “Subscribe” button adds deck to user’s library and enqueues all words as New flashcards.
• Micro-features:
  • Search within library (title, board, subject).
  • “You already know X of Y words in this deck” indicator (computed against UserWordKnowledge).
  • Sort by: Most Popular, Newest, Exam Relevance.
  • Preview deck: see first 10 words without subscribing.
  • Filter by exam type: IELTS, SAT, JBA, HSC, SSC.

3.4.2 User-Created Decks [MVP]

• Create a named deck.
• Add words via search, or batch-import from a list.
• Set deck visibility: private or public.
• Micro-features:
  • Add cover image (URL or upload, stored in object storage).
  • Reorder words via drag-and-drop (DeckWord.order).
  • Export deck as plain text (word + meaning per line) or CSV.
  • Share deck via link (if public).
  • Duplicate an official deck to customize it.

3.4.3 Progress Tracking [MVP]

• Per-deck stats: total words, New, Learning, Review, Mastered counts.
• Overall stats: total vocabulary size, daily streak, words due today, words reviewed this week.
• Micro-features:
  • Calendar heatmap of review activity (like GitHub contributions).
  • Vocabulary growth line chart (words mastered over time).
  • Daily goal progress ring (e.g., 20 cards/day target from User.preferences).
  • “Level up” milestone notifications: 100, 500, 1000, 2500, 5000 words known.

---

3.5 PDF Reader

3.5.1 PDF Upload & Processing [P2]

• User uploads a PDF file (max 50MB).
• Backend:
  1. Compute SHA-256 hash of file content → check if UserDocument with this hash exists for this user.
  2. If new, create UserDocument with status=pending, store file in object storage (S3/R2).
  3. Enqueue Celery task: process_pdf.delay(document_id).
• Celery task:
  1. Use PyMuPDF to extract text page-by-page. If a page has <50 chars (likely scanned), flag for OCR.
  2. For OCR pages: run Tesseract (or Google Vision API for higher accuracy) → extract text.
  3. Tokenize text by page, store extracted text in UserDocument.extracted_text (JSONB: {page_num: text}).
  4. Identify all English words → match against Word table → store UserDocument.word_positions (JSONB: {word_id: [{page, char_offset}]}).
  5. Set status=ready.
• Frontend polls GET /api/documents/{id}/status/ every 3 seconds until status=ready.
• Micro-features:
  • Upload progress bar (chunked upload for large files).
  • “Recent Documents” list on dashboard.
  • Document deletion (deletes from object storage + DB).

3.5.2 PDF Reading Interface [P2]

• PDF.js renders the PDF in a scrollable canvas.
• On top of the PDF.js text layer, a custom React layer highlights words.
• Colorization:
  • On document ready, fetch GET /api/users/me/known-word-ids/ → store in a JS Set (Redux + localStorage cache).
  • For each word token on the current page: check if word_id is in the Set.
  • Green highlight: word is in UserWordKnowledge with status LEARNING or KNOWN.
  • Yellow highlight: word is in DB but user has status UNKNOWN.
  • No highlight: word is a stop word or not in dictionary.
• Colorization runs in a Web Worker to avoid blocking the main thread during page renders.
• Micro-features:
  • Toggle colorization on/off (keyboard shortcut: C).
  • Toggle between “show known” (green only) and “show unknown” (yellow only) modes.
  • Page number indicator + jump-to-page input.
  • Zoom in/out controls (synced with DocumentReadingProgress.zoom_level).
  • Reading position auto-saved every 30 seconds to DocumentReadingProgress.
  • “Resume reading” button on document list shows last page.

3.5.3 In-PDF Word Lookup [P2]

• User clicks/taps any highlighted (or any) word in the PDF.
• A floating popup appears showing:
  • The word, phonetic, and most relevant WordSense (context-aware: chosen based on surrounding sentence).
  • Bangla meaning.
  • “Add to Library” button.
  • “Mark as Known” button.
  • “More” link → opens full Word Detail page in a side panel.
• Context-aware sense selection: extract the sentence containing the clicked word → send to backend → backend uses keyword matching or embedding similarity to rank WordSense entries and return the best match.
• Micro-features:
  • Popup auto-dismisses on scroll or outside click.
  • Popup can be pinned (stays open while user scrolls).
  • “Add with this context” captures the sentence as Flashcard.custom_context.
  • If word already in user’s library, popup shows current SRS state (e.g., “Due in 3 days”).

---

3.6 Text-to-Flashcard Tool

3.6.1 Text Input & Parsing [P2]

• User pastes any English text into a textarea (up to 5,000 words).
• On submit:
  1. Backend tokenizes text into individual words/phrases.
  2. Removes stop words (hardcoded list of ~500 common words).
  3. Lemmatizes remaining words (using NLTK or spaCy).
  4. Looks up each lemma in the Word table.
  5. Filters out words already in UserWordKnowledge with status KNOWN (unless “show all” is checked).
  6. Returns a ranked list of candidate words: frequency rank ascending (rarest words first).
• Micro-features:
  • Source type selector: paste text / enter URL (fetches page via backend proxy) / upload plain text file.
  • “Difficulty estimate” bar showing ratio of known to unknown words.
  • Words that are NOT in the dictionary are flagged separately (“N words not found in dictionary”).

3.6.2 Batch Flashcard Creation [P2]

• Results shown as a scrollable checklist.
• Each item: word, POS, Bangla meaning, example sentence.
• User checks words they want to add (or “Select All Unknown”).
• “Add Selected” creates flashcards for all checked words, linking ContextExample to the source text passage.
• Micro-features:
  • Filter list by POS (nouns only, verbs only, etc.).
  • Sort by: frequency (hardest first), alphabetical.
  • Click any word to expand full sense details inline.
  • “Add to Deck” dropdown: choose existing deck or create new one named after the source.
  • After adding, a summary shows “X words added, Y skipped (already in library)“.

---

3.7 Colorize Feature (Global)

This feature is not limited to PDF — it applies to any text surface the user controls.

3.7.1 Known Word ID Cache [MVP]

• GET /api/users/me/known-word-ids/ returns:

  {
    "word_ids": [123, 456, 789, ...],
    "generated_at": "2024-01-15T10:30:00Z",
    "total_count": 4231
  }

• Frontend stores this in Redux + localStorage with the generated_at timestamp.
• Cache is invalidated when: user adds/removes a flashcard, user marks a word known/ignored.
• For large vocabularies (>10,000 words): endpoint paginates as cursor-based response; client assembles the full Set progressively.
• Implementation note: The RTK Query hook useKnownWordIds() returns { ids: Set<number>, isLoading } — the Set is rebuilt once from the array and stored in a Redux non-serializable cache (using createSlice with custom Map/Set stored outside the Redux state tree, referenced via ref).

3.7.2 Colorize in Text-to-Flashcard [P2]

• As user pastes text into the textarea, words are colored in real-time.
• Green: known. Yellow: in dictionary but unknown. Grey: stop word. Red underline: not in dictionary.

---

3.8 Word Graph

3.8.1 Personal Word Graph [P3]

• A D3.js force-directed graph visualization.
• Nodes: words the user has status = KNOWN or LEARNING.
• Edges: WordRelationship connections between those words.
• Node size: proportional to UserWordKnowledge.confidence.
• Node color: by part of speech.
• Micro-features:
  • Click node → opens Word Detail side panel.
  • Hover node → shows quick definition tooltip.
  • Filter by relationship type (synonyms only, antonyms only, etc.).
  • “Suggest new word” button: finds words connected to known words but not yet in user’s library (1-hop neighbors).
  • Zoom, pan, reset viewport controls.
  • Export graph as PNG.

3.8.2 AI-Powered Semantic Graph [P3]

• For words with embedding populated, use pgvector cosine similarity to find semantically close words.
• “Semantic neighbors” are shown as a distinct edge type (dashed, colored differently from WordRelationship edges).
• GET /api/words/{id}/semantic-neighbors/?limit=10 → returns top 10 words by L2 distance.

---

3.9 Browser Extension

3.9.1 Core Extension Features [P3]

• When user selects/hovers over a word on any webpage:
  • Extension checks local chrome.storage.local cache of ignored words.
  • If not ignored: sends GET /api/extension/lookup/?word={word}&url={current_url} to MindLexa API.
  • Shows popup with word definition and action buttons.
• Popup action buttons: Add to Library / Mark as Known / Ignore Word / Open in MindLexa.
• “Add to Library” sends word + current page URL + surrounding sentence to POST /api/extension/add/.
• Micro-features:
  • Extension icon badge shows number of new words added today.
  • Right-click context menu: “Look up in MindLexa” (for selected text).
  • Settings popup: enable/disable auto-popup, set minimum word length, manage ignored words.
  • “Colorize this page” button: fetches word IDs from local cache, highlights all words on current page.
  • Offline mode: extension works with cached definitions for last 1,000 looked-up words.

3.9.2 Privacy Design [P3]

• No page URLs are stored on the server (only Flashcard.source_url, which is opt-in).
• ExtensionLookup logs only word + action, never URL.
• User can delete all extension history from settings.
• Ignored words list synced from server, merged with local stop-word list shipped with extension.

---

3.10 User Account & Settings

3.10.1 Authentication [MVP]

• Register: email + password. Email verification required before full access.
• Login: email + password → returns JWT access token (15 min) + refresh token (30 days).
• Social login: Google OAuth2 [P2].
• Password reset via email link.

3.10.2 Profile & Preferences [MVP]

• Set proficiency level (User.proficiency_level) — affects colorization threshold (e.g., absolute beginners get ALL words highlighted; advanced users only see rare words).
• Set daily study goal (stored in User.preferences['daily_goal']).
• Set native language (default: Bangla).
• Toggle: show Bangla meaning first on flashcards vs. English first.
• Toggle: auto-play pronunciation on card flip.
• Micro-features:
  • Avatar upload.
  • Delete account (GDPR-compliant: deletes all user data, anonymizes ContextExample.use_count contributions).
  • Export all data as JSON.

---

4. Operation Pipelines

This section describes, step by step, how each major system operation works end-to-end.

---

4.1 Word Lookup Pipeline

User types "ephemeral"
        │
        ▼
Frontend: debounce 300ms
        │
        ▼
GET /api/dictionary/words/?q=ephemeral
        │
        ▼
Backend: Word.objects.filter(text__iexact='ephemeral').prefetch_related(
             'senses__examples', 'outgoing_relations__target_word'
         ).first()
        │
    ┌───▼────────────────────────────────────────────────┐
    │ Word found?                                         │
    │  YES → serialize senses, examples, relationships    │
    │  NO  → trigram search: Word.objects.annotate(       │
    │         similarity=TrigramSimilarity('text', q)     │
    │        ).filter(similarity__gt=0.3)[:5]             │
    │         → return 404 with suggestions list          │
    └─────────────────────────────────────────────────────┘
        │
        ▼
Backend: annotate response with user-specific data (if authenticated):
    - UserWordKnowledge status for this word
    - Is word in any of user's decks?
    - SRS due date if flashcard exists
        │
        ▼
Frontend: render WordDetail component
    - Display all senses grouped by POS
    - Show user status badge (Unknown / Learning / Known)
    - Show "Add" or "In Library" button depending on status

---

4.2 Flashcard Creation Pipeline

User clicks "Add to Library" on word sense #2 of "bank"
        │
        ▼
Frontend: opens AddFlashcardModal
    - Shows sense selector (if word has multiple senses)
    - Shows deck selector dropdown
    - Shows context input (pre-filled if coming from PDF/extension)
    - Shows note input
        │
        ▼
POST /api/learning/flashcards/
{
  "word_sense_id": 42,
  "deck_id": 7,          // optional
  "context_example_id": null,  // null if custom
  "custom_context": "The bank raised interest rates.",
  "added_via": "manual",
  "user_note": "Think: river bank = money bank"
}
        │
        ▼
Backend (in a DB transaction):
    1. Validate: word_sense exists, user doesn't already have this sense as a flashcard
    2. Create Flashcard object
    3. Flashcard.save() triggers:
        a. UserWordKnowledge.objects.update_or_create(
               user=user, word=word_sense.word,
               defaults={'status': 'learning'}
           )
        b. SpacedRepetitionData.objects.create(
               flashcard=flashcard,
               user=user,
               due_date=timezone.now(),   ← due immediately (New state)
               state=0
           )
    4. If context_example_id provided:
        ContextExample.objects.filter(pk=context_example_id).update(
            use_count=F('use_count') + 1
        )
        │
        ▼
Response: {flashcard_id, srs_state, due_date, deck_title}
        │
        ▼
Frontend:
    - Invalidate RTK Query cache for "user known word IDs"
    - Update word status badge in UI to "Learning"
    - Show success toast: "Added to [Deck Name]!"

---

4.3 SRS Review Session Pipeline

User opens Study page
        │
        ▼
GET /api/learning/sessions/due-count/
→ SpacedRepetitionData.objects.filter(user=user, due_date__lte=now()).count()
→ Returns: {due_today: 23, new_today: 5}
        │
        ▼
User clicks "Study Now"
        │
        ▼
GET /api/learning/sessions/start/?limit=20
→ Fetches 20 due cards:
   SpacedRepetitionData.objects
     .filter(user=user, due_date__lte=now())
     .select_related('flashcard__word_sense__word', 'flashcard__context_example')
     .order_by('due_date')[:20]
→ Returns list of card objects with all display data
        │
        ▼
Frontend: initializes session queue in Redux
    - currentCard = queue[0]
    - Show front: word text, phonetic, context sentence (if available)
        │
        ▼
User flips card (click/tap/spacebar)
    - Show back: Bangla meaning, English meaning, POS, note
    - Show rating buttons: Again / Hard / Good / Easy
        │
        ▼
User selects rating (e.g., "Good" = 3)
        │
        ▼
Frontend: immediately advances to next card (optimistic)
        │
POST /api/learning/sessions/review/
{
  "srs_data_id": 88,
  "rating": 3,
  "review_duration_ms": 4200  // how long they looked at the card
}
        │
        ▼
Backend:
    1. Fetch SpacedRepetitionData object
    2. Run FSRS algorithm:
        new_state, new_due, new_stability, new_difficulty = fsrs.review(
            state=srs.state,
            stability=srs.stability,
            difficulty=srs.difficulty,
            rating=rating,
            elapsed_days=(now - srs.last_review).days
        )
    3. Update SpacedRepetitionData fields
    4. If rating == 1 (Again): add card back to session queue
    5. If stability crosses "mastered" threshold (e.g., >21 days):
        UserWordKnowledge.objects.filter(user=user, word=word).update(
            status='known', confidence=min(confidence+10, 100)
        )
        │
        ▼
Session ends when queue empty:
    POST /api/learning/sessions/complete/
    { reviewed: 20, again_count: 3, good_count: 12, easy_count: 5 }
    → Backend updates streak, daily goal progress
    → Returns session summary
        │
        ▼
Frontend: shows SessionSummary screen
    - Cards reviewed: 20
    - Retention rate: 85%
    - Streak: 🔥 7 days
    - Words mastered today: 2
    - Next session estimate: "14 cards due tomorrow"

---

4.4 PDF Processing Pipeline

User uploads "Bangladesh_History.pdf"
        │
        ▼
Frontend: chunks file into 5MB parts, uploads via multipart POST
POST /api/documents/upload/ (multipart/form-data)
        │
        ▼
Backend:
    1. Compute SHA-256 of file bytes
    2. Check: UserDocument.objects.filter(user=user, file_hash=hash).exists()
       If yes → return existing document_id (deduplication)
    3. Store file to S3/R2: upload_to=f"documents/{user.id}/{hash}.pdf"
    4. Create UserDocument(user, file_hash, title, file_url, status='pending')
    5. Enqueue: process_pdf.delay(document_id=doc.id)
    6. Return: {document_id, status: 'pending'}
        │
        ▼
Celery Worker: process_pdf(document_id)
    Step 1: Download PDF from S3 to worker temp dir
    Step 2: Open with PyMuPDF (fitz)
    Step 3: For each page:
        text = page.get_text("text")
        if len(text.strip()) < 50:
            # Likely scanned — flag for OCR
            image = page.get_pixmap(dpi=200)
            text = run_tesseract(image)   ← subprocess call
        page_texts[page_num] = text
    Step 4: Tokenize all text → lemmatize → deduplicate
    Step 5: Bulk lookup in Word table:
        found_words = Word.objects.filter(text__in=lemmatized_tokens)
        word_map = {w.text: w.id for w in found_words}
    Step 6: Build word_positions dict (JSONB):
        { word_id: [{"page": 3, "offset": 412}, ...] }
    Step 7: Update UserDocument:
        doc.extracted_text = page_texts   # JSONB
        doc.word_positions = word_positions
        doc.total_pages = len(page_texts)
        doc.status = 'ready'
        doc.save()
        │
        ▼
Frontend (polling GET /api/documents/{id}/status/ every 3s):
    status == 'ready' → navigate to PDF reader view
        │
        ▼
PDF Reader loads:
    7. Fetch document metadata (total_pages, word_positions)
    8. Fetch user's known word ID set (from cache or API)
    9. Initialize PDF.js with the file URL
    10. On each page render:
        a. Get words on this page from word_positions
        b. Pass to Web Worker: {pageWordIds, knownWordIdSet}
        c. Worker returns: {green: [...ids], yellow: [...ids]}
        d. Overlay colored highlights on PDF.js text layer

---

4.5 Text-to-Flashcard Pipeline

User pastes: "The ephemeral beauty of cherry blossoms..."
        │
        ▼
POST /api/tools/text-to-flashcard/analyze/
{ "text": "...", "source_type": "manual" }
        │
        ▼
Backend:
    Step 1: Tokenize using NLTK word_tokenize()
    Step 2: Remove stop words (hardcoded list + NLTK English stop words)
    Step 3: Lemmatize using WordNetLemmatizer
    Step 4: Deduplicate lemmas
    Step 5: Bulk DB lookup:
        words = Word.objects.filter(text__in=lemmas).prefetch_related(
            'senses__examples'
        )
    Step 6: Fetch user's known word IDs (from UserWordKnowledge)
    Step 7: For each found word:
        - Mark as 'known' if in known_ids
        - Mark as 'unknown' if not
        - Attach best WordSense (use first sense, or frequency-ranked)
    Step 8: Sort by frequency_rank ascending (hardest words first)
    Step 9: Return response:
    {
      "found": [ {word, senses, status, frequency_rank}, ... ],
      "not_found": ["soliloquize", ...],
      "stats": {
        "total_tokens": 312,
        "unique_words": 89,
        "already_known": 61,
        "new_words": 18,
        "difficulty_score": 0.72  // ratio of rare words
      }
    }
        │
        ▼
Frontend: renders interactive word checklist
    - Grouped: "New Words" / "Already Known" / "Not in Dictionary"
    - Each new word has a checkbox (checked by default)
        │
        ▼
User reviews list, unchecks common words, clicks "Add 14 Words"
        │
        ▼
POST /api/tools/text-to-flashcard/batch-add/
{
  "word_sense_ids": [12, 44, 87, ...],
  "deck_id": 5,
  "source_text_hash": "sha256...",
  "source_type": "manual"
}
        │
        ▼
Backend (bulk creation in single transaction):
    Flashcard.objects.bulk_create([...])
    SpacedRepetitionData.objects.bulk_create([...])
    UserWordKnowledge.objects.bulk_update_or_create([...])
    ContextExample.objects.get_or_create for each sentence
        │
        ▼
Response: { added: 14, skipped_duplicates: 2, deck_title: "My Reading" }

---

4.6 Browser Extension Lookup Pipeline

User hovers over word "profligate" on any webpage
        │
        ▼
Extension content script:
    1. Check: is word in LOCAL stop-word list (500 words)? If yes → skip
    2. Check: is word in chrome.storage.local['ignored_words']? If yes → skip
    3. Check: is word in chrome.storage.local['known_word_ids'] Set? 
       → If yes, mark popup accordingly but still show
    4. Check: is word in chrome.storage.local['definition_cache']?
       → If yes, show from cache immediately
    5. If not cached: GET /api/extension/lookup/?word=profligate
        │
        ▼
Backend /api/extension/lookup/:
    - Word lookup (same as dictionary pipeline)
    - Returns compact response (word, top 2 senses, phonetic only)
    - No URL logging
        │
        ▼
Extension popup renders:
    [profligate]   /ˈprɒflɪɡət/  🔊
    adj. wastefully extravagant
    bn: অমিতব্যয়ী, অপচয়কারী
    [Add to Library] [Mark as Known] [Ignore] [Open Full →]
        │
        ▼
User clicks "Add to Library"
        │
        ▼
POST /api/extension/add/
{
  "word_id": 334,
  "word_sense_id": 502,
  "added_via": "extension",
  "custom_context": "The profligate CEO was forced to resign."  // surrounding sentence
}
→ Same Flashcard creation pipeline as 4.2
→ Extension logs: ExtensionLookup(word, action='added')
→ Updates chrome.storage.local['known_word_ids'] locally

---

4.7 Colorization Pipeline (Global)

App startup (user is logged in)
        │
        ▼
RTK Query: useGetKnownWordIdsQuery()
→ GET /api/users/me/known-word-ids/
→ Returns: { word_ids: [1,4,7,...,N], generated_at: "..." }
        │
        ▼
Redux store:
    vocabulary.knownWordIds = new Set(word_ids)   // stored as ref, not in state
    vocabulary.cacheTimestamp = generated_at
    localStorage.setItem('knownWordCache', JSON.stringify({word_ids, generated_at}))
        │
        ▼
Cache invalidation triggers:
    - Flashcard added → dispatch(invalidateKnownWordCache())
    - Word marked known → dispatch(invalidateKnownWordCache())
    - Word ignored → dispatch(invalidateKnownWordCache())
    → Re-fetches /api/users/me/known-word-ids/ on next render
        │
        ▼
PDF Page Render:
    mainThread → extracts word tokens from PDF.js text layer
    mainThread → posts to colorize.worker.ts:
    {
      wordTokens: [{text, wordId, x, y, w, h}, ...],
      knownIds: serializedSet  // transferred as ArrayBuffer for perf
    }
        │
        ▼
colorize.worker.ts:
    for each token:
        if knownIds.has(token.wordId) → 'green'
        else if token.wordId → 'yellow'
        else → null (stop word / unknown)
    postMessage({colorMap: {tokenIndex: color}})
        │
        ▼
mainThread: applies CSS class overlays on PDF.js text spans
    .ml-known  { background: rgba(34,197,94,0.25); border-radius: 2px; }
    .ml-unknown { background: rgba(234,179,8,0.25); border-radius: 2px; }

---

5. API Design

5.1 Base URL & Versioning

All endpoints are prefixed with /api/v1/. Django Ninja auto-generates OpenAPI docs at /api/v1/docs.

5.2 Authentication

All protected endpoints require Authorization: Bearer {access_token} header. Token refresh: POST /api/v1/auth/token/refresh/.

5.3 Endpoint Reference

Dictionary

Method	Path	Description
GET	/dictionary/words/	Search words (q, pos, limit params)
GET	/dictionary/words/{id}/	Word detail with all senses
GET	/dictionary/words/{id}/senses/	All senses for a word
GET	/dictionary/words/{id}/relationships/	Synonyms, antonyms, collocations
GET	/dictionary/words/{id}/semantic-neighbors/	pgvector nearest neighbors [P3]
GET	/dictionary/search/banglish/?q=	Trigram banglish search

Users & Vocabulary

Method	Path	Description
GET	/users/me/	Current user profile
PATCH	/users/me/	Update profile/preferences
GET	/users/me/known-word-ids/	Full known word ID list (cached)
GET	/users/me/word-knowledge/	Paginated list of user’s word statuses
POST	/users/me/word-knowledge/	Set/update status for a word
DELETE	/users/me/word-knowledge/{word_id}/	Remove word knowledge entry
GET	/users/me/stats/	Overall stats (streak, vocab size, daily goal)
GET	/users/me/stats/history/	Historical review data for charts

Learning

Method	Path	Description
GET	/learning/flashcards/	List user’s flashcards (filterable)
POST	/learning/flashcards/	Create flashcard
GET	/learning/flashcards/{id}/	Flashcard detail
PATCH	/learning/flashcards/{id}/	Update (note, deck, context)
DELETE	/learning/flashcards/{id}/	Delete flashcard
GET	/learning/decks/	List user’s subscribed decks
POST	/learning/decks/	Create user deck
GET	/learning/decks/{id}/	Deck detail with word list
PATCH	/learning/decks/{id}/	Update deck metadata
DELETE	/learning/decks/{id}/	Delete deck
POST	/learning/decks/{id}/subscribe/	Subscribe to official deck
GET	/learning/library/	Browse official decks (board, class, subject filters)
GET	/learning/sessions/due-count/	How many cards due
GET	/learning/sessions/start/	Fetch due cards for session
POST	/learning/sessions/review/	Submit rating for a card
POST	/learning/sessions/complete/	End session, update streak

Documents

Method	Path	Description
POST	/documents/upload/	Upload PDF
GET	/documents/	List user’s documents
GET	/documents/{id}/	Document detail + status
GET	/documents/{id}/status/	Polling endpoint for processing status
PATCH	/documents/{id}/progress/	Save reading position
DELETE	/documents/{id}/	Delete document

Tools

Method	Path	Description
POST	/tools/text-to-flashcard/analyze/	Parse text, return word list
POST	/tools/text-to-flashcard/batch-add/	Batch create flashcards
POST	/tools/context-sense/	Given sentence + word → return best sense

Extension

Method	Path	Description
GET	/extension/lookup/?word=	Lightweight word definition
POST	/extension/add/	Add word from extension
GET	/extension/ignored-words/	Sync ignored words list
POST	/extension/ignore/	Add word to ignored list

5.4 Response Caching Strategy

Endpoint	Cache Type	TTL
/dictionary/words/{id}/	Redis	24h (invalidated on word update)
/learning/library/	Redis	6h
/users/me/known-word-ids/	Redis per-user	5min (invalidated on vocab change)
/learning/sessions/due-count/	No cache	—
/extension/lookup/	Redis	24h per word

---

6. Data & Dictionary Strategy

This is the highest-risk area of the project. The schema is ready; the data pipeline is not. The following strategy is required before any feature can go live.

6.1 Primary Data Sources

Wiktionary XML Dump (Free)

• Download: enwiktionary-latest-pages-articles.xml.bz2 (~1GB compressed).
• Parse using wiktionaryparser Python library or custom XML parser.
• Extracts: definitions (English), etymology, pronunciation (IPA), example sentences, synonyms/antonyms.
• Missing: Bangla (meaning_bn), Banglish keywords.
• Coverage: ~700,000 English entries.
• Plan: Import Wiktionary → fill meaning_en, phonetic_uk, phonetic_us, ExampleSentence.sentence_en, WordRelationship (synonyms/antonyms).

Bangla Meanings (AI-Generated, Curated)

• For initial seed of 10,000 most common words (frequency rank 1–10,000):
  • Use GPT-4o-mini batch API: input English word + POS + example → output Bangla meaning + Banglish keywords.
  • Cost estimate: ~$0.50–$2.00 per 1,000 words → $5–20 for 10,000 words (acceptable).
  • Human review: volunteer review process or paid spot-checks for top 1,000 words.
• Store AI-generated flag on WordSense (add is_ai_generated = BooleanField(default=False)) so these can be reviewed/corrected.

English Word Frequency List

• Use COCA (Corpus of Contemporary American English) or SUBTLEXus frequency list.
• Maps word → frequency_rank.
• Seed this first: python manage.py seed_frequency_ranks --source coca.

NCTB Vocabulary (Curated Manually)

• NCTB textbooks are publicly available.
• Extract vocabulary lesson by lesson (manual or semi-automated with OCR).
• Each lesson becomes one Deck.
• This is ~3,000–5,000 words total across Class 6–12.
• These words get human-curated Bangla meanings (highest quality).

IELTS / SAT / JBA Wordlists (Public Domain)

• Multiple IELTS Academic Word Lists (AWL) and SAT high-frequency lists are public.
• Import as official decks.
• ~1,500 words for IELTS AWL, ~800 for SAT Tier 1.

6.2 Data Import Order

Week 1: Seed frequency ranks (all words, just the rank)
Week 1: Import Wiktionary English data (definitions, phonetics, relationships)
Week 2: Run AI batch job for top 10,000 Bangla meanings + banglish keywords
Week 2: Import IELTS/SAT/JBA wordlists as Deck objects
Week 3: Manual NCTB vocabulary entry (or contracted to a data entry team)
Week 3: Generate embeddings via Celery (background, ongoing)
Ongoing: User-submitted corrections via a "Suggest correction" button on word detail page

6.3 Data Quality Controls

• WordSense.meaning_bn is a required field — no sense can be saved without a Bangla meaning.
• WordSense.banglish_keywords must have at least 1 entry for search to work.
• Automated tests check: every official deck word has at least 1 WordSense, every WordSense has at least 1 ExampleSentence.
• Admin dashboard (Django Admin) shows: words missing audio, words missing Bangla meaning, words missing embeddings.

---

7. Frontend Architecture

7.1 Key Libraries

Purpose	Library
Framework	React 18 + TypeScript
Build	Vite
State	Redux Toolkit + RTK Query
Routing	React Router v6
UI Components	shadcn/ui + Tailwind CSS
PDF Rendering	PDF.js (pdfjs-dist)
Graph Visualization	D3.js v7
Charts	Recharts
Animation	Framer Motion
Icons	Lucide React
Bangla Font	Hind Siliguri (self-hosted, no Google Fonts CDN dependency)

7.2 State Architecture

Redux Store
├── auth            { user, accessToken, refreshToken }
├── vocabulary      { knownWordIds: Set (ref), cacheTimestamp }
├── session         { queue, currentIndex, sessionStats }
├── ui              { sidebarOpen, activeModal, theme }
└── RTK Query APIs
    ├── dictionaryApi   (words, senses, search)
    ├── learningApi     (flashcards, decks, sessions)
    ├── documentApi     (upload, progress)
    └── userApi         (profile, knowledge, stats)

7.3 Offline & Caching Strategy

• RTK Query keepUnusedDataFor: 300 seconds for most endpoints.
• localStorage persists: known word ID cache, PDF reading positions, last session state.
• Service Worker (PWA): caches static assets + last 50 API responses.
• The app must be usable for a study session even when network drops mid-session (all due cards already fetched; review ratings queued and synced when connection restores).

7.4 Performance Requirements

• Initial page load (TTI): < 3 seconds on 4G (Bangladesh average: ~20 Mbps).
• PDF colorization: < 500ms per page (enforced by Web Worker offloading).
• Word lookup response: < 200ms p95 (Redis caching + DB indexes).
• SRS session: zero loading states after initial card fetch (all 20 cards pre-fetched).
• Flashcard flip animation: 60fps (CSS transform, no layout thrashing).

7.5 Bangla Typography Rules

• Font: Hind Siliguri 400 + 600 weights, self-hosted.
• Never use system fonts for Bangla text — renders inconsistently across Android versions.
• Bangla text line-height: 1.8 (default 1.5 clips descenders in Bangla script).
• Bangla text font-size: always at least 15px (smaller sizes are illegible on mobile).
• Never truncate Bangla text with CSS text-overflow: ellipsis — conjunct consonants break.

---

8. Background Jobs & Async

8.1 Celery Task Registry

Task	Trigger	Queue	Priority
process_pdf	PDF upload	documents	High
run_ocr	PDF page flagged as scanned	ocr	Normal
generate_embedding	New Word created	embeddings	Low
batch_generate_embeddings	Management command	embeddings	Low
aggregate_analytics	Cron, every hour	analytics	Low
update_srs_due_counts	Cron, midnight daily	system	High
send_daily_reminder_email	Cron, 8am user-local time	email	Normal
cleanup_old_documents	Cron, weekly	system	Low

8.2 Redis Configuration

# Two Redis databases
CELERY_BROKER_URL = "redis://localhost:6379/0"   # Task queue
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://localhost:6379/1",    # API response cache
    }
}

8.3 PDF Processing Error Handling

process_pdf failure modes:
    - File not found in S3 → retry 3x with exponential backoff → mark status='error'
    - Tesseract timeout (>120s) → mark page as 'ocr_failed', continue other pages
    - PyMuPDF crash → catch exception → mark status='error', notify admin via Sentry
    - Memory limit exceeded (>512MB) → Celery worker restart, retry once

All failures set UserDocument.status = 'error' and UserDocument.error_message = "..."
Frontend shows error state with "Try again" button.

---

9. Security & Privacy

9.1 Authentication Security

• JWT access tokens expire in 15 minutes. Refresh tokens expire in 30 days.
• Refresh tokens are stored in HttpOnly, SameSite=Strict cookies (not localStorage) to prevent XSS theft.
• Access tokens stored in memory only (Redux store) — lost on page refresh, silently refreshed via cookie.
• Rate limiting: 5 failed logins per IP per 15 minutes → 1 hour lockout (via django-ratelimit).

9.2 API Security

• All endpoints require authentication except: word lookup, public deck browse, register, login.
• CORS: allowed origins whitelist only (claude.ai equivalent production domain + localhost for dev).
• All user data endpoints validate request.user == object.user before returning data.
• File uploads: validate MIME type server-side (not just extension). Max size: 50MB. Virus scan via ClamAV before processing [P2].

9.3 Privacy Commitments

• Extension lookup logs no URLs.
• ExtensionLookup records are automatically deleted after 90 days.
• DocumentReadingProgress stores document hash (not file name or content) — user controls the file.
• Uploaded PDFs stored in private S3 bucket with per-user IAM path isolation.
• “Delete Account” must permanently delete: all flashcards, SRS data, documents (S3 + DB), word knowledge records. Anonymizes contributions to ContextExample.use_count.

---

10. Phase Plan & MVP Scope

Phase 1 — MVP (Months 1–3)

Goal: A working vocabulary learning app. No AI. No PDF. No extension.

Included:

• User auth (register, login, JWT)
• Dictionary: word lookup, Banglish search, word detail page
• Pre-seeded data: top 5,000 words with Bangla meanings (AI-generated), IELTS AWL, SAT deck
• Flashcard creation (manual, from search)
• SRS review session (FSRS)
• Basic deck management (create, subscribe to official decks)
• UserWordKnowledge tracking
• Colorize (in-app word search results only — green/yellow badges)
• User stats: streak, vocab count, daily goal

Not included in MVP:

• PDF reader
• Text-to-flashcard
• Quiz/matching/gap-fill modes
• Word Graph
• Browser extension
• NCTB full curriculum (only 1 sample class)
• Social login

MVP Success Metric: 50 real users complete at least 3 review sessions.

---

Phase 2 — Core Features (Months 4–6)

Included:

• PDF upload + processing + OCR
• PDF reader with colorization
• In-PDF word lookup popup
• Text-to-flashcard tool
• Quiz mode
• Matching mode
• Gap-fill mode
• Full NCTB Class 6–10 curriculum decks
• Google OAuth2 login
• Daily reminder emails
• Mobile-responsive polish pass

---

Phase 3 — Intelligence & Ecosystem (Months 7–12)

Included:

• Word Graph (D3.js, based on WordRelationship + pgvector neighbors)
• Browser extension (Chrome + Edge, Manifest V3)
• Semantic word recommendations
• AI-powered context-aware sense selection
• JBA / HSC / SSC / Admission exam decks (full)
• Word embedding generation (all words)
• Public deck sharing
• User-created deck marketplace
• Export to Anki format

---

11. Non-Functional Requirements

11.1 Scalability

• DB: PostgreSQL 16 with connection pooling via PgBouncer. Single node sufficient for MVP; read replica when DAU > 1,000.
• Django: Run 4 Gunicorn workers per server. Stateless — can scale horizontally.
• Celery: Start with 2 workers; scale ocr queue separately (CPU-heavy).
• Static files: Serve via CDN (Cloudflare R2 or AWS CloudFront).

11.2 Monitoring

• Error tracking: Sentry (Django + React).
• Performance: Django Silk for query profiling in development. Datadog or Grafana in production.
• Uptime: UptimeRobot pinging /api/v1/health/ every 60 seconds.
• Log all Celery task failures with full stack traces.

11.3 Testing

• Django: pytest-django. Coverage target: 80% on apps/learning/ and apps/dictionary/.
• FSRS algorithm: unit tests with known expected outputs for each rating+state combination.
• API: integration tests for all critical flows (flashcard creation, SRS review).
• React: Vitest + React Testing Library for component tests.
• E2E: Playwright for the 3 most critical flows: register→add word→complete session.

11.4 Database Migrations

• Never run migrations in production with zero downtime unless tested on a staging DB first.
• Any migration adding a NOT NULL column to Flashcard, SpacedRepetitionData, or UserWordKnowledge (high-row tables) must use a 3-step process: add nullable → backfill → add NOT NULL constraint.

---

12. Open Questions

These must be answered before development begins.

#	Question	Owner	Deadline
1	Which object storage provider? (AWS S3 / Cloudflare R2 / self-hosted MinIO)	Infra	Week 1
2	Which OCR service? (Tesseract for cost / Google Vision for accuracy)	Backend	Week 2
3	Budget for AI API calls (Bangla meaning generation + embeddings)?	Product	Week 1
4	NCTB data entry: internal effort or outsource?	Product	Week 2
5	What is the “mastered” FSRS stability threshold? (default: 21 days)	Backend	Week 1
6	Will the extension support Firefox at launch?	Frontend	Week 3
7	Is the Django admin sufficient for content management, or build a custom CMS?	Backend	Week 2
8	Who reviews/approves AI-generated Bangla meanings before publishing?	Content	Week 2
9	Domain name and hosting region (BD local / SG / IN for latency)?	Infra	Week 1
10	Licensing for IELTS/SAT wordlists — are the specific lists chosen public domain?	Legal	Week 2

---

frontend and visual details

MindLexa — Frontend Product Requirements Document

Version: 1.0
Stack: React 18 + TypeScript + Vite + Tailwind CSS + shadcn/ui
Status: Pre-Development

---

Table of Contents

1. Design System & Global Rules
2. Navigation & Shell
3. Authentication Pages
4. Dashboard — Command Center
5. SRS Study Session
6. Library Explorer
7. Deck Detail Page
8. My Library Page
9. Word Detail Page
10. PDF Reader Workspace
11. Text-to-Flashcard Tool
12. Quiz Mode
13. Matching Mode
14. Gap-Fill Mode
15. Word Graph Visualizer
16. Search Results Page
17. Profile & Settings
18. Statistics & Progress
19. Documents Manager
20. Browser Extension UI
21. Onboarding Flow
22. Admin / Content Panel
23. Error & Empty States
24. Page & Route Map

---

1. Design System & Global Rules

1.1 Color Palette

PRIMARY
  --color-primary-500: #4F46E5     (Indigo — main brand)
  --color-primary-600: #4338CA     (hover states)
  --color-primary-100: #EEF2FF     (tinted backgrounds)

SURFACE
  --color-bg:          #0F0F13     (dark mode base, near-black)
  --color-surface-1:   #17171D     (cards, panels)
  --color-surface-2:   #1F1F28     (nested cards, inputs)
  --color-surface-3:   #2A2A36     (hover surfaces)
  --color-border:      #2E2E3E     (subtle borders)

TEXT
  --color-text-primary:   #F0EFF8  (headings, important text)
  --color-text-secondary: #9B99B4  (labels, captions)
  --color-text-muted:     #5C5A72  (placeholders, disabled)

SEMANTIC
  --color-known:    #22C55E   (green  — word user knows)
  --color-unknown:  #EAB308   (yellow — word in DB, not known)
  --color-new:      #3B82F6   (blue   — new flashcard)
  --color-due:      #F97316   (orange — card due for review)
  --color-mastered: #A855F7   (purple — FSRS stability > 21d)
  --color-danger:   #EF4444   (red    — errors, "Again" button)
  --color-success:  #22C55E

COLORIZE OVERLAYS (PDF / text)
  --colorize-known:    rgba(34, 197, 94,  0.22)
  --colorize-unknown:  rgba(234, 179, 8,  0.20)
  --colorize-new:      rgba(59, 130, 246, 0.18)

Light mode uses inverted surface tokens. Toggle stored in User.preferences.theme. Default: dark.

1.2 Typography

ENGLISH FONT STACK
  Headings:  "Inter", system-ui, sans-serif
  Body:      "Inter", system-ui, sans-serif
  Mono:      "JetBrains Mono", monospace  (phonetics, code)

BANGLA FONT STACK
  All Bangla: "Hind Siliguri", sans-serif   (self-hosted, no CDN)
  Weight:     400 (body), 600 (headings)
  line-height: 1.85  (never below 1.7 for Bangla)
  font-size:   minimum 15px  (never smaller on mobile)

TYPE SCALE (rem)
  --text-xs:   0.75rem  / 12px   (badges, labels)
  --text-sm:   0.875rem / 14px   (secondary UI)
  --text-base: 1rem     / 16px   (body default)
  --text-lg:   1.125rem / 18px   (card titles)
  --text-xl:   1.25rem  / 20px   (section headers)
  --text-2xl:  1.5rem   / 24px   (page titles)
  --text-3xl:  1.875rem / 30px   (flashcard word display)
  --text-4xl:  2.25rem  / 36px   (hero numbers / stats)
  --text-5xl:  3rem     / 48px   (session end big number)

1.3 Spacing & Layout

• Base spacing unit: 4px. All spacing values are multiples of 4.
• Page max-width: 1280px, centered with mx-auto.
• Content max-width (text-heavy pages): 768px.
• Grid system: 12-column CSS Grid. Sidebar: 240px fixed. Content area: fluid.
• Mobile breakpoint: 768px. All layouts stack to single column below this.
• Touch targets: minimum 44×44px (all interactive elements on mobile).

1.4 Motion & Animation

TIMING
  --duration-fast:    100ms   (tooltips, badge changes)
  --duration-normal:  200ms   (modal open, drawer slide)
  --duration-slow:    350ms   (page transitions, card flip)
  --duration-xslow:   500ms   (graph animations)

EASING
  --ease-out:   cubic-bezier(0.16, 1, 0.3, 1)  (all entrances)
  --ease-in:    cubic-bezier(0.5, 0, 1, 0.5)   (exits)
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1)  (bouncy confirms)

RULES
  - Flashcard flip: CSS perspective transform, 350ms, --ease-out
  - Correct answer: scale(1.05) → scale(1) + green flash, 200ms
  - Wrong answer: translateX(-8px) shake ×2, 200ms
  - Page transitions: opacity 0→1 + translateY(8px)→0, 200ms
  - Reduce motion: all animations disabled when prefers-reduced-motion

1.5 Component Library Rules

• shadcn/ui is the base. Custom components extend, never replace.
• Every interactive element has 3 states defined: default, hover, active/pressed.
• Every async operation has 3 states: loading (skeleton), success, error.
• No spinners in the middle of content — always use skeleton loaders that match the shape of the loaded content.
• Tooltips on every icon-only button (no exceptions).
• Focus rings: 2px solid --color-primary-500, always visible (no outline: none).

---

2. Navigation & Shell

2.1 Desktop Sidebar

┌──────────────────────────────────────────────────────────────┐
│ SIDEBAR (240px, fixed left, full height)                      │
│ bg: --color-surface-1                                         │
│ border-right: 1px solid --color-border                        │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────────────────────┐                          │
│  │  [M] MindLexa          [≡]      │  ← Logo + collapse btn  │
│  └─────────────────────────────────┘                          │
│                                                               │
│  ┌─────────────────────────────────┐                          │
│  │  🔥 7-day streak                │  ← Streak badge          │
│  │  ████████░░  12/20 today        │  ← Daily progress bar   │
│  └─────────────────────────────────┘                          │
│                                                               │
│  ─── LEARN ──────────────────────────────────────────────    │
│                                                               │
│  [⚡] Study Now        [23 due]  ← Orange badge              │
│  [🏠] Dashboard                                               │
│  [📚] My Library                                              │
│  [📖] Library Explorer                                        │
│                                                               │
│  ─── TOOLS ──────────────────────────────────────────────    │
│                                                               │
│  [📄] PDF Reader                                              │
│  [✂️] Text → Flashcards                                       │
│  [🕸️] Word Graph                                              │
│                                                               │
│  ─── PRACTICE ───────────────────────────────────────────    │
│                                                               │
│  [🎯] Quiz                                                    │
│  [🔗] Matching                                                │
│  [✏️] Gap Fill                                                │
│                                                               │
│  ─────────────────────────────────────────────────────────   │
│                                                               │
│  [📊] Statistics                                              │
│  [⚙️] Settings                                                │
│                                                               │
│  ─────────────────────────────────────────────────────────   │
│  [Avatar] Rahim Uddin          [→ logout]                     │
└──────────────────────────────────────────────────────────────┘

Behavior:

• Active route: left border 3px solid --color-primary-500 + bg --color-primary-100/10.
• “Study Now” item always shows live due count badge. Refreshes every 60s.
• Sidebar can collapse to icon-only mode (64px wide). State persisted in localStorage.
• Collapsed mode: icons only, tooltips on hover showing label.
• On mobile: sidebar hidden by default, opens as a drawer with backdrop overlay.

2.2 Mobile Bottom Navigation

Visible only on screens < 768px. Fixed bottom bar replaces sidebar.

┌────────────────────────────────────────────────────┐
│  [🏠]     [📚]     [⚡]     [🔍]     [👤]          │
│ Home    Library  Study    Search   Profile          │
│                  [●23]                              │
└────────────────────────────────────────────────────┘

• “Study” tab shows orange dot badge with due count.
• Active tab: icon filled + label in --color-primary-500.
• Inactive: icon outline + label in --color-text-muted.

2.3 Global Search Bar

Present in the top header bar on all pages (desktop). Full-width overlay on mobile (triggered by search icon tap).

┌──────────────────────────────────────────────────────────────────┐
│ HEADER (56px height, full width minus sidebar)                    │
│ bg: --color-bg  border-bottom: 1px solid --color-border           │
│                                                                   │
│  [←Back]  [  🔍 Search words, Banglish স্বাগতম ...  ]  [🔔] [👤] │
└──────────────────────────────────────────────────────────────────┘

Search Dropdown (on focus/type):

┌──────────────────────────────────────────────────────┐
│  🔍  ephemeral                                        │
├──────────────────────────────────────────────────────┤
│  DICTIONARY MATCHES                                   │
│  ● ephemeral   adj  ক্ষণস্থায়ী                       │
│  ● ephemera    n    ক্ষণস্থায়ী জিনিস                 │
├──────────────────────────────────────────────────────┤
│  IN YOUR LIBRARY                                      │
│  ✓ ephemeral · Due in 3 days                         │
├──────────────────────────────────────────────────────┤
│  DECKS                                                │
│  📚 IELTS Academic Wordlist · 570 words               │
├──────────────────────────────────────────────────────┤
│  Press ↵ for full results                             │
└──────────────────────────────────────────────────────┘

• Debounce: 300ms.
• Keyboard navigation: ↑↓ to move, Enter to select, Escape to close.
• Banglish detected automatically: input “akash” → suggests words with banglish_keywords match.
• Max 3 results per section in dropdown. Full results on search page.

---

3. Authentication Pages

3.1 Login Page /login

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│              [M] MindLexa                                   │
│         Build your vocabulary, permanently.                 │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    SIGN IN                          │   │
│  │                                                     │   │
│  │  Email                                              │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │  rahim@example.com                          │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  │                                                     │   │
│  │  Password                          [Forgot?]        │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │  ••••••••••••                          [👁]  │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  │                                                     │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │            Sign In  →                       │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  │                                                     │   │
│  │  ────────────────── or ───────────────────         │   │
│  │                                                     │   │
│  │  ┌─────────────────────────────────────────────┐   │   │
│  │  │  [G]  Continue with Google                  │   │   │
│  │  └─────────────────────────────────────────────┘   │   │
│  │                                                     │   │
│  │  Don't have an account?  [Create one →]             │   │
│  └─────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

States & Validation:

• Empty submit: inline error under each empty field. “This field is required.”
• Wrong credentials: banner error at top of card. “Email or password is incorrect.”
• Loading: Sign In button shows spinner, disabled. All inputs disabled.
• Success: fade out, redirect to /dashboard or to ?next= param if present.
• “Forgot?” link → /forgot-password.
• No sidebar. Full-page centered layout. BG: subtle animated gradient (slow, 30s cycle).

---

3.2 Register Page /register

┌─────────────────────────────────────────────────────────────┐
│              [M] MindLexa                                   │
│         Start learning today — it's free.                   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                  CREATE ACCOUNT                     │   │
│  │                                                     │   │
│  │  Full Name                                          │   │
│  │  [________________________________]                 │   │
│  │                                                     │   │
│  │  Email Address                                      │   │
│  │  [________________________________]                 │   │
│  │                                                     │   │
│  │  Password                                           │   │
│  │  [________________________________]  [👁]           │   │
│  │  ████░░░░░░  Strength: Fair                         │   │
│  │                                                     │   │
│  │  Confirm Password                                   │   │
│  │  [________________________________]  [👁]           │   │
│  │                                                     │   │
│  │  I am primarily: (affects default content)          │   │
│  │  ○ HSC Student   ○ University Student               │   │
│  │  ○ IELTS Prep    ○ General Learner                  │   │
│  │                                                     │   │
│  │  [  Create My Account  →  ]                         │   │
│  │                                                     │   │
│  │  Already have an account?  [Sign in →]              │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Micro-details:

• Password strength bar: real-time, 5 levels (empty, weak, fair, strong, very strong) based on length + complexity.
• “I am primarily” selection sets User.proficiency_level default and pre-selects relevant decks in onboarding.
• After submit: redirects to /onboarding (not dashboard) for first-time users.
• Inline validation on blur for each field (not on keystroke).

---

3.3 Forgot Password /forgot-password

Single-input page. Email field + “Send Reset Link” button. After submit: success state showing “Check your inbox” with an email icon, no redirect. Back to login link.

3.4 Reset Password /reset-password?token=

Two password fields (new + confirm). On success: redirects to /login with success toast “Password updated. Please sign in.”

3.5 Email Verification /verify-email?token=

Auto-verifies on page load. Shows loading spinner → success state “Email verified! Welcome to MindLexa” + “Go to Dashboard” button. If token invalid/expired: error state + “Resend verification email” button.

---

4. Dashboard — Command Center

Route: /dashboard
Purpose: First page after login. Shows learning health at a glance and drives the user into action.

4.1 Full Layout

┌─────────────────────────────────────────────────────────────────────────────┐
│ HEADER: "Good morning, Rahim 👋"    Date: Monday, Jan 15      [🔔] [👤]      │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │  HERO STUDY CARD                                                     │  │
│  │  bg-gradient: indigo→purple, rounded-2xl, p-8                        │  │
│  │                                                                      │  │
│  │   🔥 7-Day Streak!                          ┌───────────────────┐   │  │
│  │                                              │   Today's Goal     │   │  │
│  │   You have  23 cards  due today.             │   ████████░░░░░░   │   │  │
│  │   Start studying to keep your streak.        │   12 / 20 reviewed │   │  │
│  │                                              └───────────────────┘   │  │
│  │   ┌──────────────────────────────┐                                   │  │
│  │   │   ⚡  Study Now  (23 due)    │   ← primary CTA, large, white     │  │
│  │   └──────────────────────────────┘                                   │  │
│  │   [Start with specific deck ▾]   ← secondary dropdown               │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐      │
│  │  TOTAL WORDS │  │  ACCURACY   │  │  REVIEWS    │  │  DUE SOON   │      │
│  │             │  │             │  │  THIS WEEK  │  │             │      │
│  │    2,341    │  │    87%      │  │    142      │  │    +48      │      │
│  │   words     │  │  retention  │  │   reviews   │  │  tomorrow   │      │
│  │  ↑ +14 today│  │  ↑ +2%      │  │  ↑ vs last  │  │             │      │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘      │
│                                                                             │
│  ┌──────────────────────────────────────┐  ┌───────────────────────────┐  │
│  │  RECENT DECKS                        │  │  UPCOMING REVIEWS         │  │
│  │                                      │  │                           │  │
│  │  [📖] HSC English 1st Paper          │  │  Today  ████  23          │  │
│  │       Lesson 3 · 8 cards due  [▶]    │  │  Tmrw   ██    48          │  │
│  │                                      │  │  +2d    █     12          │  │
│  │  [📖] IELTS Academic Word List       │  │  +3d    ██    31          │  │
│  │       12 cards due  [▶]              │  │  +4d    █     9           │  │
│  │                                      │  │  +5d    ███   41          │  │
│  │  [📖] My Custom Deck                 │  │  +6d    █     15          │  │
│  │       All caught up ✓  [▶]          │  │                           │  │
│  │                                      │  │  [View full forecast →]   │  │
│  │  [Browse all decks →]               │  │                           │  │
│  └──────────────────────────────────────┘  └───────────────────────────┘  │
│                                                                             │
│  ┌──────────────────────────────────────┐  ┌───────────────────────────┐  │
│  │  RECENT PDFs                         │  │  SUGGESTED WORDS          │  │
│  │                                      │  │                           │  │
│  │  [📄] Bangladesh History.pdf         │  │  Based on your IELTS deck │  │
│  │       Page 24 · 3 days ago   [▶]     │  │                           │  │
│  │                                      │  │  ● prolific  adj          │  │
│  │  [📄] Advanced English Grammar.pdf  │  │    producing much         │  │
│  │       Page 8 · 5 days ago    [▶]     │  │    প্রচুর উৎপাদনশীল      │  │
│  │                                      │  │    [+ Add]                │  │
│  │  [Upload new PDF +]                  │  │                           │  │
│  └──────────────────────────────────────┘  │  ● ameliorate  v          │  │
│                                            │    to make better         │  │
│                                            │    উন্নত করা              │  │
│  ┌──────────────────────────────────────┐  │    [+ Add]                │  │
│  │  STREAK CALENDAR                     │  │                           │  │
│  │  Jan 2025                            │  │  ● lucid  adj             │  │
│  │                                      │  │    clearly expressed      │  │
│  │  M  T  W  T  F  S  S                 │  │    সুস্পষ্ট               │  │
│  │  ●  ●  ●  ●  ●  ○  ●                 │  │    [+ Add]                │  │
│  │  ●  ●  ○  ●  ●  ●  ●                 │  │                           │  │
│  │                                      │  │  [See more suggestions →] │  │
│  │  🔥 Current: 7   🏆 Best: 23         │  └───────────────────────────┘  │
│  └──────────────────────────────────────┘                                  │
└─────────────────────────────────────────────────────────────────────────────┘

4.2 Component Details

Hero Study Card:

• Greeting changes: “Good morning” / “Good afternoon” / “Good evening” based on local time.
• If 0 due: hero changes to ”✓ All caught up!” green state with “Add new words” CTA.
• If streak = 0: shows “Start a streak today!” motivational variant.
• “Start with specific deck ▾” dropdown: lists user’s decks with due counts. Selecting one starts a filtered session.

Quick Stats Cards:

• Each stat card has a small sparkline chart (last 7 days) on hover.
• Delta indicator (↑ +14 today) shown only when value changed today; hidden otherwise.
• “Accuracy” stat links to /statistics.

Recent Decks:

• Max 3 most recently accessed decks by UserDeckSubscription.last_accessed.
• [▶] Play button starts study session immediately for that deck.
• “All caught up ✓” state shown when due_count = 0.

Upcoming Reviews Bar Chart:

• Mini bar chart, 7 bars (today + 6 days).
• Today’s bar is orange. Future bars are indigo/blue.
• Clicking a bar shows a tooltip: “Monday Jan 20 — 31 reviews due”.

Suggested Words:

• Pulled from 1-hop neighbors of user’s known words in WordRelationship.
• “Add” button is instant — creates flashcard optimistically, shows ✓ without page reload.

Streak Calendar:

• Green dot = studied. Empty circle = missed. Grey = future.
• Hover on any day: tooltip showing cards reviewed that day.

---

5. SRS Study Session

Route: /study (redirected from /study?deck=id for filtered sessions)
Purpose: Distraction-free, full-focus learning interface. No sidebar. No header.

5.1 Pre-Session Screen

┌─────────────────────────────────────────────────────────────────┐
│                    [✕ Exit to Dashboard]                        │
│                                                                 │
│                  ┌────────────────────────┐                    │
│                  │   Ready to Study?       │                    │
│                  │                         │                    │
│                  │   📚  IELTS Wordlist    │                    │
│                  │                         │                    │
│                  │  ┌──────┐ ┌──────┐      │                    │
│                  │  │  18  │ │  5   │      │                    │
│                  │  │ due  │ │ new  │      │                    │
│                  │  └──────┘ └──────┘      │                    │
│                  │                         │                    │
│                  │  ─── Session Settings ──│                    │
│                  │  Max cards: [20 ▾]      │                    │
│                  │  Card order: [Due first]│                    │
│                  │  Audio: [On ●]          │                    │
│                  │                         │                    │
│                  │  [  Start Session  →  ] │                    │
│                  └────────────────────────┘                    │
└─────────────────────────────────────────────────────────────────┘

5.2 Active Session Layout

┌─────────────────────────────────────────────────────────────────┐
│  [✕]  Card 7 of 23    ████████████░░░░░░░░░░░░  [⚙ Settings]   │
│       Progress bar: animated fill, percentage shown on hover    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                     FLASHCARD                            │  │
│  │                                                          │  │
│  │   ← (swipe left for  AGAIN)        (swipe right for EASY)→  │
│  │                                                          │  │
│  │   ────────────── FRONT FACE ──────────────               │  │
│  │                                                          │  │
│  │                    ephemeral                             │  │
│  │                  /ɪˈfem(ə)r(ə)l/   [🔊]                 │  │
│  │                                                          │  │
│  │   ─────────────── context ───────────────                │  │
│  │   "The ephemeral nature of social media                  │  │
│  │    trends makes them hard to study."                     │  │
│  │                                                          │  │
│  │   source: IELTS Reading — Cambridge 15                   │  │
│  │                                                          │  │
│  │                                                          │  │
│  │           [ Tap to reveal meaning ]                      │  │
│  │           or press  Spacebar                             │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌── PROGRESS ───────────────────────────────────────────────┐  │
│  │   ● New: 5   ● Learning: 3   ● Review: 15   ✓ Done: 6    │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

5.3 Revealed Card (Back Face)

The card flips with a 3D CSS perspective transform (Y-axis rotation).

┌──────────────────────────────────────────────────────────────┐
│                  FLASHCARD (BACK FACE)                       │
│                                                              │
│   ephemeral                             adj  [🔊]            │
│                                                              │
│   ─── Bangla ────────────────────────────────               │
│   ক্ষণস্থায়ী; অতি সংক্ষিপ্ত সময়ের জন্য                    │
│                                                              │
│   ─── English ───────────────────────────────               │
│   Lasting for only a short time;                            │
│   transitory.                                               │
│                                                              │
│   ─── Examples ─────────────────────────────               │
│   • The ephemeral beauty of a sunset.                       │
│   • সূর্যাস্তের ক্ষণস্থায়ী সৌন্দর্য।                      │
│                                                              │
│   ─── Synonyms ─────────────────────────────               │
│   [transient] [fleeting] [momentary]                        │
│                                                              │
│   [📝 Add note]   [See full word →]                         │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│    HOW WELL DID YOU REMEMBER?                                │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │          │ │          │ │          │ │          │       │
│  │  Again   │ │   Hard   │ │   Good   │ │   Easy   │       │
│  │   (1)    │ │   (2)    │ │   (3)    │ │   (4)    │       │
│  │   < 1m   │ │  ~10m    │ │  4 days  │ │  7 days  │       │
│  │          │ │          │ │          │ │          │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
│   [red]        [orange]     [green]       [blue]            │
│                                                              │
│                          [↩ Undo]                           │
└──────────────────────────────────────────────────────────────┘

Micro-details:

• Due date estimates below each button are computed from FSRS algorithm live.
• Keyboard shortcuts: 1 = Again, 2 = Hard, 3 = Good, 4 = Easy, Space = flip.
• Swipe gestures on mobile: left = Again, right = Easy, up = Good.
• [↩ Undo]: only available for 3 seconds after rating. Reverts last review.
• “Add note” opens an inline textarea on the card without navigating away.
• Synonyms are clickable pills → navigate to word detail in a new tab.

5.4 Session End Screen

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│              🎉  Session Complete!                              │
│                                                                 │
│              ┌─────────────────────────────┐                   │
│              │    23 cards reviewed         │                   │
│              │                             │                   │
│              │  ┌──────┐ ┌──────┐ ┌──────┐ │                   │
│              │  │  17  │ │  4   │ │  2   │ │                   │
│              │  │ Good+│ │ Hard │ │Again │ │                   │
│              │  └──────┘ └──────┘ └──────┘ │                   │
│              │                             │                   │
│              │  Retention Rate:  87%  ↑    │                   │
│              │  🔥 Streak: 8 days  (best!) │                   │
│              │  Words mastered today: 2    │                   │
│              │                             │                   │
│              │  Next review:               │                   │
│              │  Tomorrow · 48 cards        │                   │
│              └─────────────────────────────┘                   │
│                                                                 │
│         [ Study Again ]    [ Back to Dashboard ]               │
│                                                                 │
│  ─── WORDS YOU STRUGGLED WITH ───────────────────────────      │
│  ● ephemeral   · Again ×2    [Review now]  [See word →]        │
│  ● profligate  · Hard ×3     [Review now]  [See word →]        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Library Explorer

Route: /library
Purpose: Browse and subscribe to all pre-made official decks.

6.1 Full Layout

┌─────────────────────────────────────────────────────────────────────────┐
│  Library Explorer                                                       │
│  Discover pre-made decks for every exam and textbook.                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  🔍  Search decks, subjects, exams...  (Banglish supported)      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ─── BROWSE BY CATEGORY ────────────────────────────────────────────   │
│                                                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐        │
│  │   📗 NCTB        │  │  🎓 Admission   │  │  🌍 Standardized │        │
│  │   Class 6–12    │  │  Tests          │  │  Tests           │        │
│  │   48 decks      │  │  Medical/Engg   │  │  IELTS · SAT     │        │
│  │   3,200 words   │  │  Varsity        │  │  GRE · TOEFL     │        │
│  │   [Explore →]   │  │  [Explore →]   │  │   [Explore →]   │        │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘        │
│                                                                         │
│  ─── NCTB — CLASS 6 ────────────────────────────────────────────────   │
│  English 1st Paper                                                      │
│                                                                         │
│  ┌────────────────────────┐ ┌────────────────────────┐                 │
│  │  Lesson 1              │ │  Lesson 2              │                 │
│  │  Going to a New School │ │  Making Friends         │                 │
│  │                        │ │                        │                 │
│  │  32 words   ● Beginner │ │  28 words   ● Beginner │                 │
│  │  ★★★☆☆ (easy)         │ │  ★★★☆☆ (easy)         │                 │
│  │                        │ │                        │                 │
│  │  You know: 12 / 32 37% │ │  You know: 0 / 28  0%  │                 │
│  │  [████░░░░░░░░]        │ │  [░░░░░░░░░░░░░░]      │                 │
│  │                        │ │                        │                 │
│  │  [Preview]  [+ Add]    │ │  [Preview]  [+ Add]    │                 │
│  └────────────────────────┘ └────────────────────────┘                 │
│                                                                         │
│  ─── IELTS ─────────────────────────────────────────────────────────   │
│                                                                         │
│  ┌────────────────────────┐ ┌────────────────────────┐                 │
│  │  Academic Word List    │ │  IELTS High Frequency  │                 │
│  │                        │ │                        │                 │
│  │  570 words  ● Advanced │ │  800 words  ● Advanced │                 │
│  │  ★★★★★ (hard)         │ │  ★★★★☆ (hard)         │                 │
│  │                        │ │                        │                 │
│  │  4,231 learners        │ │  3,102 learners        │                 │
│  │  You know: 89 / 570    │ │  Not started            │                 │
│  │                        │ │                        │                 │
│  │  [Preview]  [+ Add]    │ │  [Preview]  [+ Add]    │                 │
│  └────────────────────────┘ └────────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────────┘

Micro-details:

• “You know: X / Y” computed from UserWordKnowledge against deck’s word list on page load.
• ”[+ Add]” button: changes to ”[✓ Added]” + green after click; optimistic update.
• “[Preview]” opens a drawer/modal showing first 10 words of the deck without navigating away.
• Category cards are sticky headers when scrolling within a filtered view.
• Deck difficulty tags: Beginner / Intermediate / Advanced / Expert — derived from average Word.frequency_rank.
• Star rating (1–5) is static visual difficulty indicator, not user rating.
• Learner count pulled from UserDeckSubscription count.

6.2 NCTB Drill-Down View

When user clicks “Explore →” on NCTB category:

┌─────────────────────────────────────────────────────────────────┐
│  [← Library]  NCTB Textbooks                                   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  CLASS  [6] [7] [8] [9] [10] [11] [12]  ← tab switcher  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  SUBJECT  [English 1st Paper ▾]   [English 2nd Paper ▾]        │
│                                                                 │
│  Showing: Class 6 · English 1st Paper · 12 lessons             │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Lesson 1: Going to a New School   32 words  [+ Add]     │  │
│  │  Lesson 2: Making Friends          28 words  [✓ Added]   │  │
│  │  Lesson 3: Our School Garden       41 words  [+ Add]     │  │
│  │  ...                                                     │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  [+ Add All Class 6 Lessons]                                    │
└─────────────────────────────────────────────────────────────────┘

---

7. Deck Detail Page

Route: /decks/:id
Purpose: View all words in a deck, stats, and study options.

┌─────────────────────────────────────────────────────────────────────┐
│  [← Library]                                      [⋮ More]          │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │  [COVER IMAGE — gradient placeholder if no image]           │   │
│  │  📖  IELTS Academic Word List                                │   │
│  │  Official · Advanced · 570 words                            │   │
│  │  4,231 learners · Updated Jan 2025                          │   │
│  └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐           │
│  │  89      │  │  47      │  │  412     │  │  22      │           │
│  │ known    │  │ learning │  │ not yet  │  │ mastered │           │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘           │
│                                                                     │
│  Your progress:  [████████░░░░░░░░░░░░░░░]  28%  (158 / 570)      │
│                                                                     │
│  ┌──────────────────────────┐  ┌──────────────────────────┐        │
│  │  [⚡ Study Due (18)]      │  │  [+ Add to My Library]   │        │
│  └──────────────────────────┘  └──────────────────────────┘        │
│                                                                     │
│  TABS: [All Words] [Due] [New] [Mastered] [Search within]          │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  FILTER: [All POS ▾]  [A-Z ▾]  [Status ▾]                 │    │
│  ├────────────────────────────────────────────────────────────┤    │
│  │                                                            │    │
│  │  abandon      v      ত্যাগ করা         ● Learning  [⋮]    │    │
│  │  aberrant     adj    অস্বাভাবিক         ○ New       [⋮]    │    │
│  │  abeyance     n      স্থগিতাবস্থা       ✓ Mastered  [⋮]    │    │
│  │  abhor        v      ঘৃণা করা           ● Due        [⋮]    │    │
│  │  ...                                                       │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  Showing 1–30 of 570 [Load more]                                    │
└─────────────────────────────────────────────────────────────────────┘

[⋮] row menu options: View word detail / Edit flashcard note / Remove from deck / Reset progress.

Tab behavior:

• “Due” tab shows only cards where SpacedRepetitionData.due_date <= now().
• “Mastered” tab shows cards where FSRS stability > 21 days.
• “Search within” tab: inline search filtered to deck’s words only.

---

8. My Library Page

Route: /my-library
Purpose: Manage all personal decks and subscriptions.

┌─────────────────────────────────────────────────────────────────────┐
│  My Library                               [+ Create New Deck]        │
│  All your flashcard decks in one place.                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  TABS: [All Decks] [Official Decks] [My Decks] [Shared with Me]    │
│                                                                     │
│  SORT: [Last Accessed ▾]    FILTER: [All ▾]                        │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  [GRID / LIST toggle]                                        │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ─── GRID VIEW ──────────────────────────────────────────────────  │
│                                                                     │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │  NCTB Class 8    │  │  IELTS AWL       │  │  My Custom Deck  │  │
│  │  Lesson 4        │  │                  │  │                  │  │
│  │  [gradient bg]   │  │  [gradient bg]   │  │  [gradient bg]   │  │
│  │                  │  │                  │  │                  │  │
│  │  41 words        │  │  570 words       │  │  28 words        │  │
│  │  8 due  ●        │  │  18 due  ●       │  │  All caught up ✓ │  │
│  │                  │  │                  │  │                  │  │
│  │  [▶ Study] [⋮]   │  │  [▶ Study] [⋮]   │  │  [▶ Study] [⋮]   │  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
│                                                                     │
│  ─── LIST VIEW ──────────────────────────────────────────────────  │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  📖 NCTB Class 8 · Lesson 4  │  41  │  8 due  │  [▶] [⋮]   │  │
│  │  📖 IELTS AWL                 │ 570  │ 18 due  │  [▶] [⋮]   │  │
│  │  📝 My Custom Deck            │  28  │  0 due  │  [▶] [⋮]   │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

[⋮] menu options per deck:

• Open Deck · Study Now · Edit (title, description, cover) · Export as CSV · Delete / Unsubscribe · Duplicate.

Create New Deck modal:

  Title: [____________________]
  Description: [____________________]
  Visibility: (●) Private  (○) Public
  [ Create Deck ]

---

9. Word Detail Page

Route: /words/:slug
Purpose: Complete information about one word. Serves as a reference and discovery page.

┌─────────────────────────────────────────────────────────────────────┐
│  [← Back]         WORD DETAIL                    [⋮]                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ephemeral                                    [● Learning — 4 days] │
│  /ɪˈfem(ə)r(ə)l/  [🔊 UK] [🔊 US]                                  │
│                                                                     │
│  ─── SENSES ─────────────────────────────────────────────────────  │
│                                                                     │
│  TABS: [adj (1)] [n (1)]   ← if multiple POS                       │
│                                                                     │
│  Sense 1 — adjective                                                │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  EN: Lasting for only a short time; transitory.            │    │
│  │  BN: ক্ষণস্থায়ী; যা অতি অল্প সময়ের জন্য বিদ্যমান থাকে।  │    │
│  │                                                            │    │
│  │  Examples:                                                 │    │
│  │  • The ephemeral nature of fame.                           │    │
│  │    খ্যাতির ক্ষণস্থায়ী প্রকৃতি।                            │    │
│  │  • Social media trends are ephemeral.                      │    │
│  │    সোশ্যাল মিডিয়ার ট্রেন্ডগুলো ক্ষণস্থায়ী।               │    │
│  │                                                            │    │
│  │  Usage note: Often used in academic writing.               │    │
│  │                                                            │    │
│  │  [+ Add This Sense to Library]   [✓ Already in Library]   │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ─── RELATIONSHIPS ────────────────────────────────────────────   │
│                                                                     │
│  Synonyms:   [transient] [fleeting] [momentary] [transitory]       │
│  Antonyms:   [permanent] [enduring] [eternal]                      │
│  Collocations: [ephemeral beauty] [ephemeral existence]            │
│                                                                     │
│  ─── WORD FAMILY ──────────────────────────────────────────────   │
│  Root: [Greek: ephemeros — for a day]                              │
│  Derived: [ephemera (n)] [ephemerally (adv)]                       │
│                                                                     │
│  ─── YOUR NOTES ────────────────────────────────────────────────  │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  💭 "Like a mayfly — lives for only a day"         [Save]  │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ─── FLASHCARD STATUS ─────────────────────────────────────────   │
│  In deck: IELTS AWL · Due in 4 days · Reviewed 3×  · Good ×2      │
│  [Review now]  [Reset progress]  [Move to different deck]          │
│                                                                     │
│  ─── RECENTLY ADDED BY COMMUNITY ─────────────────────────────   │
│  "The ephemeral quality of the artwork..."  — IELTS Practice Test  │
│  "...ephemeral moments of happiness..."     — Cambridge Reading    │
│                                                                     │
│  [🚩 Report incorrect meaning]  [✏️ Suggest correction]            │
└─────────────────────────────────────────────────────────────────────┘

Synonym/Antonym chips: Clickable — navigate to that word’s detail page. Color indicates if user knows the word (green = known, yellow = unknown, grey = not in library).

---

10. PDF Reader Workspace

Route: /reader (upload) · /reader/:documentId (view)
Purpose: Read PDFs with real-time vocabulary colorization and in-place word lookup.

10.1 Upload State

┌─────────────────────────────────────────────────────────────────────┐
│  PDF Reader                                                         │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                                                              │  │
│  │                [📄 Drop PDF here]                            │  │
│  │                                                              │  │
│  │       Drag & drop a PDF file, or  [Browse files]            │  │
│  │                                                              │  │
│  │          Max size: 50MB · PDF files only                     │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  ─── YOUR RECENT DOCUMENTS ─────────────────────────────────────  │
│  [📄] Bangladesh History.pdf  · Page 24  · 3 days ago   [Open]    │
│  [📄] Advanced Grammar.pdf   · Page 8   · 5 days ago   [Open]    │
└─────────────────────────────────────────────────────────────────────┘

10.2 Processing State

┌─────────────────────────────────────────────────────────────────────┐
│  Processing: Bangladesh_History.pdf                                 │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐   │
│  │                                                             │   │
│  │   [████████████████████████░░░░░░]  78%                    │   │
│  │                                                             │   │
│  │   📄 Extracting text from pages...                          │   │
│  │   ✓ Page text extracted (pages 1–45)                        │   │
│  │   ↻ Running OCR on scanned pages (46–50)...                 │   │
│  │   ○ Building vocabulary index...                            │   │
│  │                                                             │   │
│  │   This usually takes 30–60 seconds for large PDFs.          │   │
│  │   You can navigate away and come back — we'll save it.      │   │
│  │                                                             │   │
│  └─────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

10.3 Reader Layout (Ready State)

┌─────────────────────────────────────────────────────────────────────────────────┐
│ TOOLBAR (48px)                                                                  │
│ [←] Bangladesh_History.pdf   [pg 24/98]   [🔍-][100%][🔍+]   [Colorize ●]       │
│                               [< >]        [⛶Full][📥DL]      [🔊 Auto-play ○]  │
├──────────────────────────────────┬──────────────────────────────────────────────┤
│ SIDEBAR (280px)                  │ PDF CANVAS (fluid)                           │
│                                  │                                              │
│ ─ VOCABULARY ──────────         │  ┌────────────────────────────────────────┐  │
│ This page: 43 words              │  │                                        │  │
│ Known: 31 (72%)  ██████████░░░░  │  │  Chapter 3: The Liberation War         │  │
│ Unknown: 12 (28%)                │  │                                        │  │
│                                  │  │  The [ephemeral] dreams of freedom     │  │
│ UNKNOWN WORDS                    │  │  had gripped the [populace] since the  │  │
│ ON THIS PAGE:                    │  │  early days of [insurgency]. Despite   │  │
│                                  │  │  the [arduous] struggle, the           │  │
│ ● ephemeral   adj                │  │  [indomitable] spirit of the people    │  │
│   ক্ষণস্থায়ী     [+]             │  │  remained [steadfast] throughout...    │  │
│                                  │  │                                        │  │
│ ● populace    n                  │  │  Legend:                               │  │
│   জনসাধারণ      [+]             │  │  [green bg] = known  [yellow] = new   │  │
│                                  │  │                                        │  │
│ ● insurgency  n                  │  └────────────────────────────────────────┘  │
│   বিদ্রোহ        [+]             │                                              │
│                                  │                                              │
│ ● arduous     adj                │                                              │
│   কঠিন; পরিশ্রমসাধ্য  [+]        │                                              │
│                                  │                                              │
│ ─ BATCH ADD ──────────          │                                              │
│ [+ Add all unknown (12)]         │                                              │
│                                  │                                              │
│ ─ DOCUMENT ────────────         │                                              │
│ 234 total words found            │                                              │
│ 189 in dictionary                │                                              │
│ 45 not in dictionary             │                                              │
│                                  │                                              │
│ [📊 Full word analysis]          │                                              │
└──────────────────────────────────┴──────────────────────────────────────────────┘

10.4 Word Selection Popup

When user clicks any colorized word in the PDF canvas, a floating Popover appears anchored near the word:

                    ┌──────────────────────────────────────┐
                    │  ephemeral               adj  [🔊]   │
                    │  /ɪˈfem(ə)r(ə)l/                    │
                    │  ──────────────────────────────────  │
                    │  ক্ষণস্থায়ী; অতি সংক্ষিপ্ত সময়ের  │
                    │                                      │
                    │  "The ephemeral nature of fame       │
                    │   makes it dangerous to pursue."     │
                    │                                      │
                    │  ┌──────────┐ ┌────────┐ ┌────────┐ │
                    │  │ + Add    │ │ ✓ Know │ │ Ignore │ │
                    │  └──────────┘ └────────┘ └────────┘ │
                    │  [See full word →]    [📌 Pin popup] │
                    └──────────────────────────────────────┘

Behavior:

• Popup auto-dismisses on scroll (unless pinned).
• “Add” captures the current sentence as custom_context.
• “Know” marks as UserWordKnowledge.status = KNOWN.
• “Ignore” adds to UserIgnoredWord.
• Word already in library: “Add” shows ”✓ In library · Due in 3 days”.
• “Pin popup” keeps it open while user continues reading; [✕] to close.
• On mobile: popup renders as a bottom sheet (slides up from bottom, 40% height).

10.5 Colorize Toggle States

[Colorize ●] ON state:
  Known words:   green highlight (#22C55E at 22% opacity)
  Unknown words: yellow highlight (#EAB308 at 20% opacity)
  Toggle color indicator: green dot

[Colorize ○] OFF state:
  No highlights. Toggle indicator: grey dot.

[Colorize mode selector (right-click or long-press toggle)]:
  ○ Show all (green + yellow)
  ○ Show only unknown (yellow only)
  ○ Show only known (green only)

---

11. Text-to-Flashcard Tool

Route: /tools/text-to-flashcard
Purpose: Paste any text and convert unknown words into flashcards in bulk.

11.1 Input State

┌─────────────────────────────────────────────────────────────────────┐
│  Text → Flashcards                                                  │
│  Paste any English text and we'll extract vocabulary for you.       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  SOURCE TYPE:  (●) Paste Text   (○) Enter URL   (○) Upload .txt    │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                                                              │  │
│  │  Paste your English text here...                             │  │
│  │                                                              │  │
│  │  The ephemeral nature of social media means that even the    │  │
│  │  most prolific creators struggle to maintain relevance...    │  │
│  │                                                              │  │
│  │  [Words already colorized live as you type]                  │  │
│  │  Green = known  Yellow = unknown  Red underline = not in DB  │  │
│  │                                                              │  │
│  │                                          312 words  ████░░░░│  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  OPTIONS:  [☑ Filter out words I already know]                     │
│            [☑ Show only nouns, verbs, adjectives, adverbs]         │
│            Target deck: [IELTS Prep ▾] [+ Create new]             │
│                                                                     │
│  [  Analyze Text  →  ]                                              │
└─────────────────────────────────────────────────────────────────────┘

11.2 Results State

┌─────────────────────────────────────────────────────────────────────┐
│  Analysis Results                           [← Edit text]           │
│                                                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐              │
│  │  18      │ │  61      │ │   9      │ │  89      │              │
│  │ new      │ │ already  │ │ not in   │ │ total    │              │
│  │ words    │ │ known    │ │   DB     │ │ checked  │              │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘              │
│                                                                     │
│  Difficulty: ████████░░  Hard (72% rare words)                     │
│                                                                     │
│  FILTER: [All POS ▾]   SORT: [Rarest first ▾]                      │
│                                                                     │
│  ─── NEW WORDS (18) ───────────────────────────────────────────   │
│                                                                     │
│  [☑] ephemeral     adj  ক্ষণস্থায়ী              freq: 8,241       │
│      "...ephemeral nature of social media..."   [▼ expand]        │
│                                                                     │
│  [☑] prolific      adj  প্রচুর উৎপাদনশীল        freq: 12,891      │
│      "...most prolific creators struggle..."    [▼ expand]        │
│                                                                     │
│  [☑] indomitable   adj  অদম্য; অজেয়             freq: 45,231      │
│      "...indomitable spirit of the people..."  [▼ expand]        │
│                                                                     │
│  [ ] arduous       adj  কঠিন; পরিশ্রমসাধ্য      freq: 31,002      │
│      (already unchecked — user opted out)       [▼ expand]        │
│                                                                     │
│  ─── NOT IN DICTIONARY (9) ────────────────────────────────────   │
│  blogosphere, hashtag, selfie... (slang / proper nouns)            │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  [☑ Select all (14)]                                         │  │
│  │                                                              │  │
│  │  Add to deck: [IELTS Prep ▾]                                 │  │
│  │                                                              │  │
│  │  [  Add 14 Selected Words to Library  →  ]                   │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

Expanded row (▼ expand):

  ephemeral     adj  ক্ষণস্থায়ী
  ──────────────────────────────
  Sense 1: Lasting for only a short time; transitory.
  Example: "The ephemeral beauty of cherry blossoms."
  [Use this context sentence ●]
  [Use sentence from my text ○]  "...ephemeral nature of..."

11.3 Batch Add Success State

  ✓  14 words added to "IELTS Prep"!
  2 were already in your library and were skipped.

  [Start studying these words now →]   [Add more text]

---

12. Quiz Mode

Route: /practice/quiz

12.1 Quiz Setup Screen

┌─────────────────────────────────────────────────────────────────────┐
│  Quiz Mode                                                          │
│                                                                     │
│  Source deck: [IELTS AWL ▾]                                         │
│                                                                     │
│  Question types:                                                    │
│  [☑] English → Bangla meaning                                       │
│  [☑] Bangla meaning → English word                                  │
│  [☑] Fill-in from context sentence                                  │
│                                                                     │
│  Card pool:  (●) Due cards  (○) All cards  (○) New only            │
│  Number of questions: [20 ▾]                                        │
│  Timed: [Off ▾]  (options: Off / 15s / 30s / 60s per question)     │
│                                                                     │
│  [  Start Quiz  ]                                                   │
└─────────────────────────────────────────────────────────────────────┘

12.2 Active Quiz Screen

┌─────────────────────────────────────────────────────────────────────┐
│  Quiz   Question 7 / 20     [██████░░░░░░░░░░░░░░]    Score: 5/6   │
│                                                        ●●●●●○       │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  What is the Bangla meaning of:                                     │
│                                                                     │
│                   ephemeral                                         │
│              (adjective)  /ɪˈfem(ə)r(ə)l/  [🔊]                   │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  A.  স্থায়ী; দীর্ঘমেয়াদী                                    │  │
│  └──────────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  B.  ক্ষণস্থায়ী; অতি সংক্ষিপ্ত সময়ের                       │  │← correct
│  └──────────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  C.  জটিল; বহুমুখী                                           │  │
│  └──────────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  D.  শক্তিশালী; প্রভাবশালী                                   │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  [⏱ 0:18]  Timer bar (if timed mode on)                            │
└─────────────────────────────────────────────────────────────────────┘

After answer selected:

• Correct: chosen option turns green. ”✓ Correct!” toast. Next question after 800ms.
• Wrong: chosen option turns red. Correct option turns green. Shows brief explanation. “Next →” button.
• Score dots at top: ● green = correct, ○ red = wrong.

12.3 Quiz Results Screen

┌─────────────────────────────────────────────────────────────────────┐
│  Quiz Complete!                                                     │
│                                                                     │
│        Score:  17 / 20     85%  ↑ +3% vs last quiz                 │
│                                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                          │
│  │  17      │  │  3       │  │  1m 42s  │                          │
│  │ correct  │  │ wrong    │  │  time    │                          │
│  └──────────┘  └──────────┘  └──────────┘                          │
│                                                                     │
│  WRONG ANSWERS:                                                     │
│  ● ephemeral  →  You chose: "স্থায়ী"  Correct: "ক্ষণস্থায়ী"       │
│  ● arduous    →  You chose: "সহজ"     Correct: "কঠিন; পরিশ্রমসাধ্য" │
│  ● profligate →  You chose: "মিতব্যয়ী" Correct: "অমিতব্যয়ী"      │
│                                                                     │
│  [Study missed words]   [Retake Quiz]   [Back to Dashboard]        │
└─────────────────────────────────────────────────────────────────────┘

---

13. Matching Mode

Route: /practice/matching

┌─────────────────────────────────────────────────────────────────────┐
│  Matching   Round 1 / 3               ⏱ 0:42    Score: 4 matched    │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Match each word to its Bangla meaning.                             │
│                                                                     │
│  ┌──────────────────────┐        ┌────────────────────────────┐    │
│  │  ephemeral           │        │  বিদ্রোহ; অভ্যুত্থান       │    │
│  └──────────────────────┘        └────────────────────────────┘    │
│                                                                     │
│  ┌──────────────────────┐        ┌────────────────────────────┐    │
│  │  insurgency  ●────── │────────│──●  ক্ষণস্থায়ী             │    │
│  └──────────────────────┘  (line)└────────────────────────────┘    │
│                                                                     │
│  ┌──────────────────────┐        ┌────────────────────────────┐    │
│  │  arduous    [LOCKED✓]│        │  অদম্য; অজেয় [LOCKED ✓]   │    │
│  └──────────────────────┘        └────────────────────────────┘    │
│                                                                     │
│  ┌──────────────────────┐        ┌────────────────────────────┐    │
│  │  indomitable         │        │  কঠিন; পরিশ্রমসাধ্য        │    │
│  └──────────────────────┘        └────────────────────────────┘    │
│                                                                     │
│  ┌──────────────────────┐        ┌────────────────────────────┐    │
│  │  prolific            │        │  প্রচুর উৎপাদনশীল          │    │
│  └──────────────────────┘        └────────────────────────────┘    │
│                                                                     │
│  Tap a word, then tap its meaning to match.                         │
└─────────────────────────────────────────────────────────────────────┘

States:

• Selected word: highlighted border (primary color).
• Correct match: both cards turn green, lock with ✓, connecting line turns green.
• Wrong match: both cards shake red, deselect, no penalty to score.
• All matched: auto-advance to next round after 1s.

---

14. Gap-Fill Mode

Route: /practice/gap-fill

┌─────────────────────────────────────────────────────────────────────┐
│  Gap Fill   Exercise 3 / 5                              Score: 2/2  │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Fill in the missing words.                                         │
│  Source: IELTS Reading — Cambridge 15, Test 2                       │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │                                                              │  │
│  │  The _____________ dreams of freedom had gripped the         │  │
│  │      [  ephemeral  ]   ← text input                         │  │
│  │                                                              │  │
│  │  _____________ since the early days of the movement.        │  │
│  │      [  populace  ]                                          │  │
│  │                                                              │  │
│  │  Despite the _____________ struggle, the _____________ spirit│  │
│  │               [__________]               [__________]        │  │
│  │                                                              │  │
│  │  of the people remained throughout.                          │  │
│  │                                                              │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  [💡 Hint: first letter]  (costs 1 point)                           │
│                                                                     │
│  [  Check Answers  ]                                                │
└─────────────────────────────────────────────────────────────────────┘

After “Check Answers”:

• Correct: input turns green, shows ✓.
• Wrong: input turns red, shows correct word in green. Bangla meaning shown below.
• Partially correct (first 3 chars match): orange, counts as 0.5 points.

---

15. Word Graph Visualizer

Route: /word-graph

15.1 Full Layout

┌─────────────────────────────────────────────────────────────────────────────────┐
│ TOOLBAR                                                                         │
│ [Word Graph]  [🔍 Focus on word...]  [Filter ▾]  [Layout ▾]  [Export PNG]      │
│              [Only known ●] [Show potential ○]                                  │
├──────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │                          D3.js CANVAS                                  │    │
│  │                                                                        │    │
│  │         [ephemeral]───synonym───[transient]                            │    │
│  │              │                      │                                  │    │
│  │           derived               derived                                │    │
│  │              │                      │                                  │    │
│  │         [ephemera]            [transience]                             │    │
│  │              │                                                         │    │
│  │           antonym                                                      │    │
│  │              │                                                         │    │
│  │         [permanent]───synonym───[enduring]                             │    │
│  │              │                                                         │    │
│  │           derived                                                      │    │
│  │              │                                                         │    │
│  │         [permanently]                                                  │    │
│  │                                                                        │    │
│  │  NODE COLORS:                                                          │    │
│  │  ● Green (large)   = Known word                                        │    │
│  │  ● Blue (medium)   = Learning                                          │    │
│  │  ● Grey (small)    = Not in library (potential)                        │    │
│  │  ● Purple (ring)   = Mastered                                          │    │
│  │                                                                        │    │
│  │  EDGE COLORS:                                                          │    │
│  │  — Indigo     = Synonym                                                │    │
│  │  — Red        = Antonym                                                │    │
│  │  — Green      = Derived / Root                                         │    │
│  │  -- Dashed    = AI semantic neighbor (pgvector)                        │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
│                                                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐       │
│  │  [−]  Zoom  [+]    [⟲ Reset view]    Showing 234 words / 891 links  │       │
│  └─────────────────────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────────────────┘

15.2 Node Click Panel (Side Panel)

When user clicks any node, a right panel slides in (320px):

  ┌──────────────────────────────────────────┐
  │  ephemeral                      [✕]      │
  │  adj · Known · Mastered                  │
  │  Reviewed 12× · Last: 3 days ago         │
  │                                          │
  │  ── Connected Words (8) ──               │
  │  Synonyms:  transient, fleeting...       │
  │  Antonyms:  permanent, enduring...       │
  │  Derived:   ephemera, ephemerally        │
  │  Semantic:  momentary, impermanent...    │
  │                                          │
  │  [Open Word Detail →]                   │
  │  [Center graph on this word]             │
  │  [Hide this word from graph]             │
  └──────────────────────────────────────────┘

Filter dropdown options:

• Show only known words / Show potential words too
• Filter by relationship type: Synonyms / Antonyms / Root words / All
• Filter by POS: Nouns / Verbs / Adjectives / All
• Minimum word connections: 2+ / 5+ / 10+

Layout options: Force-directed / Radial / Hierarchical / Cluster by POS.

---

16. Search Results Page

Route: /search?q=ephemeral

┌─────────────────────────────────────────────────────────────────────┐
│  Search results for "ephemeral"                                     │
│  5 words · 2 decks · 0 in your library                              │
│                                                                     │
│  TABS: [Words (5)] [Decks (2)] [In My Library (0)]                  │
│                                                                     │
│  ─── WORDS ─────────────────────────────────────────────────────   │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  ephemeral   adj   ক্ষণস্থায়ী                              │    │
│  │  Lasting for only a short time; transitory.                │    │
│  │  [+ Add to Library]   [See full word →]                    │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  ephemera    n     ক্ষণস্থায়ী বস্তুসমূহ                   │    │
│  │  Things that exist or are used for only a short time.      │    │
│  │  [+ Add to Library]   [See full word →]                    │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ─── DECKS ─────────────────────────────────────────────────────   │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────┐    │
│  │  IELTS Academic Word List  · contains "ephemeral"          │    │
│  │  570 words  ·  Advanced                                    │    │
│  │  [View Deck]   [+ Add to Library]                          │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ─── BANGLISH SUGGESTIONS ─────────────────────────────────────   │
│  Did you mean: "ephemeral" via "ifemeraal"? ← only shown if query  │
│  appeared to be romanized Bangla                                    │
└─────────────────────────────────────────────────────────────────────┘

---

17. Profile & Settings

Route: /settings

17.1 Settings Page Layout

┌─────────────────────────────────────────────────────────────────────┐
│  Settings                                                           │
│                                                                     │
│  SIDE TABS:                CONTENT AREA:                            │
│  ─────────               ─────────────────────────────────────     │
│  Profile          ●       PROFILE                                   │
│  Preferences              ┌──────────────────────────────────────┐  │
│  Notifications            │  [Avatar]  [Change photo]            │  │
│  Privacy                  │  Name:  [Rahim Uddin           ]      │  │
│  Account                  │  Email: [rahim@example.com      ]     │  │
│  Data Export              │  Native Language:  [Bangla ▾]         │  │
│  Danger Zone              │  Proficiency:  [Intermediate ▾]       │  │
│                           │                                       │  │
│                           │  [Save Changes]                       │  │
│                           └──────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

17.2 Preferences Section

  STUDY PREFERENCES
  ─────────────────────────────────────────────────────
  Daily study goal:          [20 ▾] cards per day
  Max new cards per session: [10 ▾]
  Card order in session:     [Due first ▾]
  Show Bangla first:         [Off ●──────────────── ]
  Auto-play pronunciation:   [On  ──────────────●  ]
  Session reminder time:     [8:00 PM ▾]

  DISPLAY
  ─────────────────────────────────────────────────────
  Theme:      (●) Dark   (○) Light   (○) System
  Font size:  [────●────────]  Medium
  Bangla script size: [────────●──]  Large

  PDF READER
  ─────────────────────────────────────────────────────
  Default colorize mode: [Show all ▾]
  Highlight opacity:     [────●────────]  50%
  Auto-save position:    [On ──────────────●]

  SRS ALGORITHM
  ─────────────────────────────────────────────────────
  "Mastered" threshold:  [21 days ▾] stability
  Max daily reviews:     [200 ▾]
  FSRS parameters:       [Use defaults ▾]
  [⚠️ Reset all SRS progress]  ← destructive, requires confirmation

17.3 Privacy Section

  EXTENSION PRIVACY
  ─────────────────────────────────────────────────────
  Log extension lookups: [Off ●────────────────]
  Delete all extension history: [Delete History]

  DATA
  ─────────────────────────────────────────────────────
  [Export all my data as JSON]
  [Export my vocabulary as CSV]
  [Export my flashcards as Anki .apkg]

  DANGER ZONE
  ─────────────────────────────────────────────────────
  [Delete Account]  ← red button, confirmation modal required

---

18. Statistics & Progress

Route: /statistics

┌─────────────────────────────────────────────────────────────────────────────────┐
│  Statistics                                    Period: [This Week ▾]            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │  2,341   │  │  87%     │  │  🔥 8    │  │  142     │  │  +23     │        │
│  │  total   │  │ retention│  │  days    │  │ reviews  │  │ this week│        │
│  │  words   │  │  rate    │  │  streak  │  │ this wk  │  │ new words│        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
│                                                                                 │
│  ─── VOCABULARY GROWTH ──────────────────────────────────────────────────────  │
│  ┌──────────────────────────────────────────────────────────────────────────┐  │
│  │  Total words mastered over time (line chart — Recharts)                  │  │
│  │                                                              ___          │  │
│  │                                                         ____/             │  │
│  │                                                    ____/                  │  │
│  │                                          _________/                       │  │
│  │  _______________________________________/                                 │  │
│  │  Jan    Feb    Mar    Apr    May    Jun    Jul    Aug    Sep    Oct        │  │
│  └──────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ─── DAILY REVIEWS ──────────────────────────────────────────────────────────  │
│  ┌──────────────────────────────────────────────────────────────────────────┐  │
│  │  Reviews per day this month (bar chart)                                  │  │
│  │  ██████ ██████ ██ ████████ ██████ ░░ ████████ ██████████ ████████ ██     │  │
│  │  1      2      3  4        5      6  7         8          9         10   │  │
│  └──────────────────────────────────────────────────────────────────────────┘  │
│                                                                                 │
│  ─── STUDY CALENDAR ─────────────────────────────────────────────────────────  │
│  [GitHub-style heatmap — 52 weeks × 7 days]                                    │
│  ░ = 0   ▒ = 1–10   ▓ = 11–30   █ = 31+  reviews                              │
│                                                                                 │
│  ─── WORD STATUS BREAKDOWN ──────────────────────────────────────────────────  │
│  ┌──────────────────────────────────────┐  ┌───────────────────────────────┐  │
│  │  Donut chart:                        │  │  By part of speech:            │  │
│  │  ● Mastered:  22  (1%)               │  │  Nouns      ████████  890      │  │
│  │  ● Review:   412  (18%)              │  │  Verbs      ██████    621      │  │
│  │  ● Learning:  47  (2%)               │  │  Adjectives ██████    534      │  │
│  │  ● New:     1860  (79%)              │  │  Adverbs    ███       296      │  │
│  │                                      │  │                                │  │
│  └──────────────────────────────────────┘  └───────────────────────────────┘  │
│                                                                                 │
│  ─── DECK PERFORMANCE ───────────────────────────────────────────────────────  │
│  ┌────────────────────────────────────────────────────────────────────────┐    │
│  │  Deck               Words    Retention   Progress    Last Studied      │    │
│  │  IELTS AWL          570      91%         ████░  28%  2 hours ago       │    │
│  │  NCTB Class 8       41       78%         ████████ 68% 1 day ago        │    │
│  │  My Custom Deck     28       94%         ██████████ 100%  3 days ago   │    │
│  └────────────────────────────────────────────────────────────────────────┘    │
│                                                                                 │
│  ─── UPCOMING FORECAST ──────────────────────────────────────────────────────  │
│  Projected review load for next 14 days (area chart)                           │
│                                                                                 │
│  [Export statistics as PDF]                                                     │
└─────────────────────────────────────────────────────────────────────────────────┘

---

19. Documents Manager

Route: /documents
Purpose: List of all uploaded PDFs, status, and reading progress.

┌─────────────────────────────────────────────────────────────────────┐
│  My Documents                               [+ Upload New PDF]       │
│                                                                     │
│  SORT: [Last opened ▾]   STATUS: [All ▾]                            │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  [📄]  Bangladesh History.pdf                                │  │
│  │        50 pages  ·  2.4 MB  ·  Uploaded Jan 10               │  │
│  │        Reading: Page 24 / 50  ██████████████░░░░░░░  48%     │  │
│  │        Vocabulary: 234 words found · 89 unknown               │  │
│  │        [Open →]  [Word Analysis]  [⋮]                         │  │
│  ├──────────────────────────────────────────────────────────────┤  │
│  │  [📄]  Advanced English Grammar.pdf                          │  │
│  │        ↻ Processing... (OCR in progress for pages 46–50)     │  │
│  │        [View progress]                                        │  │
│  ├──────────────────────────────────────────────────────────────┤  │
│  │  [📄]  Cambridge IELTS 15.pdf                                │  │
│  │        200 pages  ·  8.1 MB  ·  Uploaded Jan 5               │  │
│  │        Reading: Page 1 / 200  ░░░░░░░░░░░░░░░░░░░░░  0%      │  │
│  │        Vocabulary: 1,231 words found · 412 unknown            │  │
│  │        [Open →]  [Word Analysis]  [⋮]                         │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  [⋮] menu: Open / Word Analysis / Add all unknown words / Delete    │
└─────────────────────────────────────────────────────────────────────┘

Word Analysis modal/page (per document):

• Shows top 50 unknown words from the document (sorted by frequency rank ascending = hardest first).
• Quick batch-add button.
• Word cloud visualization.

---

20. Browser Extension UI

Platform: Chrome Extension (Manifest V3) · Popup (400×500px) + Side Panel (320px).

20.1 Extension Popup (Main View)

┌──────────────────────────────────────────────────────┐
│  [M] MindLexa                    [Rahim ▾]  [⚙]     │
├──────────────────────────────────────────────────────┤
│                                                      │
│  🔍  [  Search a word, Banglish ok...  ]             │
│                                                      │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ─── RECENTLY LOOKED UP ────────────────────────    │
│                                                      │
│  ephemeral  adj  ক্ষণস্থায়ী          [✓ Added]      │
│  profligate adj  অমিতব্যয়ী           [+ Add]        │
│  arduous    adj  কঠিন; পরিশ্রমসাধ্য   [+ Add]        │
│  indomitable adj অদম্য               [✓ Added]      │
│  populace   n   জনসাধারণ             [Ignored]      │
│                                                      │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ─── TODAY ──────────────────────────────────────   │
│  +4 words added   ·   🔥 8-day streak                │
│  Due today: 23    [Study Now →]                      │
│                                                      │
│  [Colorize this page]   [Open MindLexa ↗]            │
└──────────────────────────────────────────────────────┘

20.2 Extension Word Popup (Triggered by hover/selection)

Appears on the webpage near the selected word. Not inside the browser popup.

┌─────────────────────────────────────────────────────┐
│  [M]  ephemeral                      adj  [🔊] [✕]  │
│       /ɪˈfem(ə)r(ə)l/                              │
│  ─────────────────────────────────────────────────  │
│  ক্ষণস্থায়ী; অতি সংক্ষিপ্ত সময়ের জন্য।            │
│  Lasting for only a short time.                     │
│  ─────────────────────────────────────────────────  │
│  "...ephemeral trends in social media..."           │
│  ─────────────────────────────────────────────────  │
│  [+ Add to Library]  [✓ I Know]  [✗ Ignore]         │
│  [See more →]                                       │
└─────────────────────────────────────────────────────┘

Behavior:

• Popup position: above the selected word if space allows; below otherwise.
• Z-index: above all page elements.
• Auto-dismiss: 8 seconds after last interaction, or on Escape.
• If word already in library: “In Library · Due in 4 days” instead of [+ Add].
• Offline: shows cached definition (last 1,000 lookups in chrome.storage.local).

20.3 Extension Settings Popup

┌──────────────────────────────────────────────────────┐
│  ← Settings                                         │
│                                                      │
│  Auto-popup on hover:   [On  ──────────────●]        │
│  Hover delay:           [500ms ▾]                   │
│  Min word length:       [4 chars ▾]                  │
│  Show on already-known: [Off ●─────────────]         │
│                                                      │
│  Ignored words: 12  [Manage →]                       │
│                                                      │
│  Account: Rahim Uddin                                │
│  [Sign out]                                          │
└──────────────────────────────────────────────────────┘

---

21. Onboarding Flow

Route: /onboarding (shown once, after first registration)
5-step wizard. Full-screen. No sidebar.

Step 1 — Welcome

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│                    [M] Welcome to MindLexa!                         │
│                                                                     │
│               Let's set up your personal learning                   │
│               experience in under 2 minutes.                        │
│                                                                     │
│               ○──●──○──○──○  Step 1 of 5                           │
│                                                                     │
│                       [Get Started →]                               │
└─────────────────────────────────────────────────────────────────────┘

Step 2 — Proficiency Self-Assessment

  How would you rate your English?

  ┌─────────────────────┐  ┌─────────────────────┐
  │  😰 Absolute         │  │  😊 Beginner         │
  │  Beginner            │  │  Know common words   │
  │  Just starting out   │  │  Can read basic text │
  └─────────────────────┘  └─────────────────────┘

  ┌─────────────────────┐  ┌─────────────────────┐
  │  🙂 Intermediate    │  │  😎 Advanced         │
  │  Can read newspapers│  │  Near fluent         │
  │  Some difficulty    │  │  Complex texts fine  │
  └─────────────────────┘  └─────────────────────┘

Step 3 — Learning Goal

  What's your primary reason for learning?

  [☑] NCTB / School Exams   [ ] HSC Preparation
  [ ] University Admission  [☑] IELTS / TOEFL
  [ ] SAT / GRE             [ ] General Improvement
  [ ] Career / Professional [ ] Reading English books

  [Continue →]

Step 4 — Quick Vocabulary Test (Optional)

  Let's see what you already know. (5 quick questions)

  What does "ephemeral" mean?
  (●) ক্ষণস্থায়ী
  (○) শক্তিশালী
  (○) বিস্তৃত
  (○) পরিশ্রমী

  [Skip test →]   Progress auto-advances after 5 answers.

Step 5 — Add First Deck

  Based on your goals, here are our top picks:

  [☑] IELTS Academic Word List (570 words)
  [☑] HSC English Important Words (800 words)
  [ ] NCTB Class 11–12 Complete (1,200 words)

  [Add Selected & Go to Dashboard →]

---

22. Admin / Content Panel

Route: /admin-content (restricted: user.is_staff = True)
Note: Separate from Django Admin (/django-admin/). This is a custom, user-friendly content management UI built in React.

22.1 Admin Dashboard

┌─────────────────────────────────────────────────────────────────────┐
│  Content Admin                               [Logged in: Admin]     │
│                                                                     │
│  SIDE NAV:                                                          │
│  [📊] Overview                                                      │
│  [📖] Dictionary Words                                              │
│  [📚] Decks & Lessons                                               │
│  [👥] Users                                                         │
│  [⚠️] Quality Issues                                                │
│  [📥] Data Import                                                   │
└─────────────────────────────────────────────────────────────────────┘

22.2 Quality Issues Page

The most important admin view for content quality.

┌─────────────────────────────────────────────────────────────────────┐
│  Quality Issues                                                     │
│                                                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐              │
│  │  234     │ │  89      │ │  12      │ │  3       │              │
│  │ missing  │ │ missing  │ │ missing  │ │ missing  │              │
│  │ meaning  │ │ bangla   │ │ audio    │ │ embed    │              │
│  │ _bn      │ │ keywords │ │ url      │ │ ding     │              │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘              │
│                                                                     │
│  FILTER: [Missing meaning_bn ▾]                                     │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐  │
│  │  Word         POS  meaning_en                    Action      │  │
│  │  ephemeral    adj  Lasting for only a short...  [Edit]       │  │
│  │  profligate   adj  Recklessly extravagant...    [Edit]       │  │
│  │  ...                                                         │  │
│  └──────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  [🤖 AI Fill Selected (GPT-4o-mini)] ← batch fills meaning_bn      │
└─────────────────────────────────────────────────────────────────────┘

22.3 Word Edit Modal

  ┌──────────────────────────────────────────────────────────────────┐
  │  Edit Word: ephemeral                                            │
  │                                                                  │
  │  SENSE 1 — adjective                                             │
  │  meaning_en: [Lasting for only a short time; transitory.       ] │
  │  meaning_bn: [ক্ষণস্থায়ী; অতি সংক্ষিপ্ত সময়ের জন্য বিদ্যমান  ] │
  │  banglish:   [ephemeral, ephimeraal, ifemeraal               +] │
  │                                                                  │
  │  Examples:                                                       │
  │  [The ephemeral beauty of cherry blossoms.                     ] │
  │  [+ Add example]                                                 │
  │                                                                  │
  │  [+ Add new sense]                                               │
  │                                                                  │
  │  [Save]  [Cancel]  [🚩 Flag for review]                          │
  └──────────────────────────────────────────────────────────────────┘

---

23. Error & Empty States

Every page must handle all 3 non-ideal states. No blank white screens. No generic browser errors.

23.1 Empty States

Page	Empty State Content
My Library (no decks)	Illustration of an empty bookshelf. “Your library is empty. Browse pre-made decks or create your own.” + [Browse Library] + [Create Deck]
Dashboard (no due cards)	Green checkmark illustration. “You’re all caught up! Nothing due today.” + [Add more words] + [Browse Library]
Study Session (nothing due)	“No cards due right now. Great job keeping up!” + next due time + [Browse decks]
Search results (no match)	“No results for ‘xyz’” + trigram suggestions (if any) + [Add this word manually]
Word Graph (< 5 words)	Dashed outline of a graph. “Add at least 5 words to your library to see your word graph.” + [Browse Library]
Recent PDFs (none)	PDF upload drop zone is shown directly instead of list.

23.2 Error States

Error	UI Treatment
API 500	Toast: “Something went wrong. Please try again.” + [Retry] button. No page crash.
Network offline	Sticky banner at top: “You’re offline. Changes will sync when reconnected.” Session still usable (pre-fetched cards).
PDF processing failed	Inline error on document card with [Try again] button and error message.
Word not in dictionary	Search result shows “Not found” with suggestion to add via manual entry or report.
Auth expired	Redirect to /login with toast: “Your session expired. Please sign in again.” Preserves ?next= param.

23.3 Loading States (Skeletons)

Every list and card component must have a skeleton variant that matches its loaded shape.

DECK CARD SKELETON:
┌──────────────────┐
│ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓  │  ← cover image placeholder (animated shimmer)
│ ▓▓▓▓▓▓▓▓▓▓▓    │  ← title
│ ▓▓▓▓▓  ▓▓▓▓▓   │  ← metadata
│ ▓▓▓▓▓▓▓▓▓▓▓    │  ← progress bar shape
└──────────────────┘

WORD DETAIL SKELETON:
  ▓▓▓▓▓▓▓▓▓▓▓    (word)
  ▓▓▓▓▓▓          (phonetic)
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓   (meaning line 1)
  ▓▓▓▓▓▓▓▓▓▓▓▓▓▓          (meaning line 2)

---

24. Page & Route Map

Complete route registry for the React Router v6 configuration.

PUBLIC ROUTES (no auth required)
────────────────────────────────────────────────────────
/                         → Redirect: /dashboard if authed, else /landing
/landing                  → Marketing landing page [P2]
/login                    → Login page
/register                 → Register page
/forgot-password          → Forgot password
/reset-password           → Reset password (token in URL param)
/verify-email             → Email verification (token in URL param)
/words/:slug              → Word detail (public — no user-specific data)
/library                  → Library Explorer (public browse)
/decks/:id/preview        → Deck preview (public, first 10 words)

PROTECTED ROUTES (auth required — redirects to /login if not authed)
────────────────────────────────────────────────────────
/onboarding               → Onboarding wizard (redirected after first register)
/dashboard                → Dashboard / Command Center
/study                    → SRS Session (all due cards)
/study?deck=:id           → SRS Session (filtered to one deck)
/my-library               → My library (subscribed decks)
/my-library/new           → Create new deck (modal or page)
/decks/:id                → Deck detail
/words/:slug/edit         → User note edit (redirects to /words/:slug on save)
/reader                   → PDF upload / document list
/reader/:documentId       → PDF reader workspace
/documents                → All documents manager
/tools/text-to-flashcard  → Text-to-Flashcard tool
/practice                 → Practice mode selector hub
/practice/quiz            → Quiz mode
/practice/matching        → Matching mode
/practice/gap-fill        → Gap-fill mode
/word-graph               → Word Graph visualizer
/search                   → Search results page (?q= param)
/statistics               → Stats & progress page
/settings                 → Settings (tabbed: profile, prefs, privacy, account)
/settings/profile         → Deep link to profile tab
/settings/preferences     → Deep link to preferences tab
/settings/privacy         → Deep link to privacy tab
/settings/data            → Deep link to data export tab

STAFF-ONLY ROUTES (auth + is_staff required)
────────────────────────────────────────────────────────
/admin-content                → Custom admin dashboard
/admin-content/words          → Word management
/admin-content/words/:id      → Word edit
/admin-content/decks          → Deck management
/admin-content/import         → Data import tools
/admin-content/quality        → Quality issue queue
/admin-content/users          → User management

EXTENSION-SPECIFIC ROUTES (extension popup internal routing)
────────────────────────────────────────────────────────
ext://popup                   → Extension popup main view
ext://popup/search            → Extension word search
ext://popup/settings          → Extension settings
ext://sidepanel               → Chrome side panel full view [P3]

---

Visual images of website