Immersive Product Feature Specification

Status (2026-08-20): moved here from the repo root (#394 docs sweep). Written before the Bridge Method redesign (#280); treat the redesign design doc (immersive_redesign_extension_design.md) and bridge_method.md as authoritative where they differ. Pending a currency review.

1. Product vision

Immersive is a language-learning application for web and mobile, focused on helping learners build practical ability through grammar, conjugation, reading, listening, writing, memorisation, and AI-guided explanation.

The product combines:

structured grammar content aligned to CEFR levels (A1–C1)
free public reference tools for verb conjugation and grammar
personal learning lists and deck creation
document-based reading and writing support
AI explanation and coaching throughout the product
writing practice with targeted vocabulary reuse
spaced-repetition memorisation (FSRS algorithm)

The overall goal is to make language learning measurable, adaptive, content-rich, easy to revisit, and useful for both study and real reading/writing.

2. Platform

Immersive targets two platforms:

Platform	Stack	Status
Web	Rails 8.1, PostgreSQL, Redis, Sidekiq, Stimulus + Turbo, Propshaft	Shipping
Mobile	To be determined (native or hybrid)	Not started

Feature requirements in this spec are written to be platform-agnostic. Where a feature depends on platform-specific capability (e.g. push notifications, offline review), that is noted inline.

3. User types

Primary users

Self-directed language learners who want clear structure and progress tracking.
Learners who want both reference tools and active practice.
Learners who like building their own study materials.

Secondary users

Users seeking a free verb/conjugation reference (no login required).
Users who want AI help while studying.
Users who want to move from passive reading to active writing.

4. Product pillars

4.1 Reference

Fast access to verb tables, example sentences, pronunciation, and translations.

4.2 Practice

Adaptive grammar quizzes, listening practice, writing practice, and memorisation decks.

4.3 Capture

Ability to save words, sentences, and concepts into learning lists and notebooks.

4.4 Personalisation

Placement, CEFR alignment, weak-point tracking, adaptive review, and AI-generated study support.

4.5 Output

Users should not only read and review, but also write, recall, and apply what they learn.

5. Account and access model

Public access

Some features are available without login to attract organic traffic and serve as a reference tool.

Logged-in access

Personalised learning, learning lists, decks, AI features, progress tracking, and writing evaluation require login.

Requirements

Public users can access verb tables and conjugation references.
Logged-in users can save items, create decks, track progress, and use AI learning workflows.

Status

Built. User accounts use Devise with Pundit for authorisation. Public verb pages and grammar browsing exist. Login gates personalised features.

6. Reference and discovery features

6.1 Verb tables with sentence examples

Summary

Immersive offers free verb tables as a public feature, positioned as an alternative to Verbix.

Requirements

Users can search for verbs without login.
Each verb page shows full conjugation tables grouped by mood and tense.
Each conjugated form has an example sentence.
Example sentences include translation and audio where available.
Pages are indexable for SEO.
Search is fast and tolerant of inflected or slightly imperfect input.

User value

Immediate utility without signup. Strong SEO landing pages. Creates trust before asking users to register.

Status

Built. VerbLemma -> Conjugation -> SentenceConjugation pipeline is complete across 7 languages. Resources::VerbsController serves public verb pages with conjugation grids grouped by mood. Audio is generated just-in-time via AWS Polly. Background sentence matching uses PostgreSQL full-text search with GIN indexes.

Key models: VerbLemma, Tense, Conjugation, Infinitive, Verbal, SentenceConjugation, SentenceInfinitive.

See: docs/features/verbs/verbs_architecture.md

6.2 Grammar concept library

Summary

A browsable grammar library organised by CEFR level and topic.

Requirements

Grammar concepts grouped by CEFR level (A1–C1).
Concept pages include explanation, examples, related forms, and common mistakes.
Concepts link to quizzes, cards, and writing activities.
Content authored in target language with translations into learner fluent languages.

Status

Built. 343 French grammar notes across A1–C1 with translations in 5 languages (EN, ES, IT, PT, CA). Grammar curricula also exist for English, Spanish, Italian, Portuguese, and Catalan. Notes are organised into 28 grammatical categories with controlled vocabulary. Fill-in-the-blank exercises (GrammarExercise) link sentences to notes.

Content is authored as markdown files in db/imports/grammar/ and managed in-app via ActiveAdmin. Published notes are visible to logged-in users.

Key models: GrammarCategory, GrammarNote, GrammarNoteTranslation, GrammarExercise.

See: docs/features/grammar_notes.md, db/imports/grammar/fr/programme-guide.md

Gap: Concept pages do not yet link to decks, cards, or writing activities. Cross-linking between grammar and practice surfaces is a future integration point.

6.3 Document viewer and reader support

Summary

Users can read documents in the target language and interact directly with words and sentences.

Requirements

Users can open and view a document in the target language.
Clicking a word allows: translation, pronunciation/audio, add to learning list, AI explanation.
Clicking a sentence allows: sentence translation, pronunciation/audio, add to learning list, AI explanation or breakdown.
Reader experience is fast and minimally disruptive.

User value

Turns reading into active learning. Lets users collect vocabulary and phrases in context. Bridges real content and study workflows.

Status

Partially built. Document viewer exists with read and write modes. Documents split into document_words and document_sentences. Click-to-translate and click-to-play-audio work for both words and sentences. The Language Coach (AI assistant) is available in-context.

Key models: Document, DocumentWord, DocumentSentence, Folder.

See: docs/features/documents/documents.md

Gap: “Add to learning list” action does not exist yet (learning lists are not built). AI explanation is available via the Language Coach but not as an inline popover on word/sentence click.

6.4 Document editor

Summary

Users can write and edit target-language documents inside the product, with AI coaching.

Requirements

Support document viewing and editing.
Selection-based actions for words and sentences.
AI assistance available in-context.
Saved highlights or selected items can flow into learning lists.

Status

Partially built. Write mode exists. The Language Coach assesses submitted writing and gives feedback. Two-column layout (document 2/3, chat 1/3) is available.

Gap: No selection-based actions beyond the coach. No flow from document highlights into learning lists.

7. Adaptive learning and structured study

7.1 Placement test

Summary

New users can take a placement test that estimates their CEFR level.

Requirements

Initial level detection per language.
Result seeds study plan and recommendations.
Users may later adjust starting level manually.

Status

Not built.

7.2 CEFR-aligned study structure

Requirements

Grammar concepts organised by A1–C1.
Learners can browse by level.
App recommends current level and next stretch level.
Content supports structured progression between levels.

Status

Partially built. Grammar notes and categories are fully organised by CEFR level. Learners can browse by level via GrammarCategory. The curriculum in db/imports/grammar/ defines learning objectives per level and category in learning-objectives.yml.

Gap: No recommendation engine to suggest current or stretch level. No adaptive progression logic.

7.3 Adaptive grammar quiz engine

Summary

Quiz sequences adapt based on errors and current mastery.

Requirements

Quiz generation uses learner history.
Wrong answers increase future exposure to related concepts.
Mastered concepts appear less often.
Quiz flow may follow a study plan or be manually chosen.

Status

Not built. Foundation exists: GrammarExercise provides fill-in-the-blank questions linked to grammar notes. StudyEvent and UserAbility track per-resource mastery across modalities. The adaptive scheduling layer and quiz sequencing engine are not yet implemented.

7.4 Guided study plan

Summary

The app recommends what the learner should do next.

Requirements

Dashboard shows recommended next activity.
Guided plan draws from weak points, current level, and review timing.
Users can leave guided mode and self-direct at any time.

Status

Not built.

7.5 Weak-point notebook

Summary

A notebook tracks concepts the user missed and wants to revisit.

Requirements

Incorrect answers map to a grammar concept.
Users can save items to notebook.
Notebook stores error history, last review date, and mastery state.
Notebook can feed future quizzes and deck generation.

Status

Not built. UserAbility tracks correct/incorrect counts and flagged state per resource, which can serve as the data layer. The notebook UI and the connection from quiz errors to grammar concepts are not implemented.

8. Vocabulary, sentence capture, and learning lists

8.1 Learning list

Summary

The user maintains a personal list of words and sentences collected from across the product.

Sources

Items can be added from:

document viewer
verb tables
grammar pages
quizzes
cards
AI chat interactions
writing correction output

Requirements

A learning list item may include:

source text
lemma/base form if relevant
translation
pronunciation/audio reference
source sentence or context
tags
status (new, learning, mastered)

User value

Creates a single place to capture useful language. Supports later review and deck creation.

Status

Not built. The closest existing features are Bookmark (polymorphic save of grammar notes, documents, decks) and Category/Categorization (tags on decks). Neither provides the structured capture-with-metadata that a learning list requires. This is a new feature requiring its own data model.

8.2 AI-assisted list enrichment

Summary

AI can help organise or transform learning-list items.

Requirements

AI may group items by topic, grammar, or difficulty.
AI may propose which items should become cards.
AI may generate explanations or example sentences for saved items.

Status

Not built. Depends on learning list (8.1).

9. Decks and memorisation

9.1 Prebuilt conjugation decks

Summary

Ready-made decks focused on conjugations, available without custom setup.

Requirements

Decks available by language, level, tense, or theme.
Decks can be used directly without custom setup.
Prebuilt decks draw from existing conjugation data and example sentences.

User value

Immediate memorisation practice. Low-friction path from browsing to study.

Status

Built. Public verb decks exist. Deck has scopes for public and verb/conjugation decks. VerbCard links to Conjugation with sentence pairs. Decks are browsable from verb pages via Resources::ConjugationsController.

9.2 User-generated decks from learning lists

Summary

Users can create decks from saved words and sentences.

Requirements

User can manually select items from learning list to create a deck.
Deck creation can also be suggested or automated by AI.
User can choose deck type: vocabulary, sentence recall, conjugation, mixed review.

Status

Not built. Depends on learning list (8.1). Users can currently create decks manually and add cards, but there is no flow from a saved-items list to deck creation.

9.3 Spaced-repetition memorisation system

Summary

Immersive includes its own flashcard/deck study experience using FSRS spaced repetition.

Requirements

Card-based review with spaced repetition scheduling.
Front/back or prompt/answer card models.
Cards can include: word, sentence, translation, audio, grammar note, AI explanation link.
Users can review by deck, tag, or due items.
Four review modes: read, write, listen, speak.
Per-deck limits for new cards and reviews per day.

User value

Keeps memorisation inside the app. Reduces need to export to external tools.

Status

Built. Custom FSRS implementation in lib/fsrs/ with Reviews::FsrsScheduler service. Card STI supports VerbCard, SentenceCard, WordCard, NumberCard. Four review modes with auto-grading via Levenshtein distance (Reviews::AnswerGrader). Per-deck new_cards_per_day and max_reviews_per_day. Nested decks via materialised path. Anki export available.

Key models: Deck, Card (STI), Review.

See: docs/features/fsrs.md

Gap: No “review by tag” across decks. No AI explanation link on cards. TextCard controller exists but is less developed than other card types.

9.4 AI-generated cards and deck shaping

Summary

AI can help turn captured material into study cards.

Requirements

AI can propose card formats from learning-list items.
AI can choose useful prompts, distractors, or recall angles.
AI can generate concise explanations for difficult cards.
Users should be able to review and edit before saving generated cards.

Status

Not built.

10. AI support across the application

10.1 Contextual AI chat

Summary

Users can open chat in many contexts to ask for explanation.

Supported surfaces

grammar concepts
quiz review
notebook items
decks and cards
document viewer
writing correction results
verb pages

Requirements

AI chat knows the current context (selected word, sentence, card, concept).
The user does not need to restate the context.
Chat can explain: grammar, meaning, nuance, conjugation, pronunciation, usage differences, why an answer was wrong.

User value

Turns static study surfaces into interactive tutoring moments.

Status

Partially built. The Language Coach exists as an AI assistant within the document viewer (read and write modes). It uses ruby_llm. Prompts are managed via BasePrompt with YAML configuration.

See: docs/technical/prompt_architecture.md

Gap: AI chat is only available in documents. Expanding to grammar pages, verb pages, quiz review, decks, and cards requires new context-passing and UI entry points on each surface.

10.2 AI explanation on cards

Summary

During memorisation, the user can open an explanation for a card.

Requirements

From any card, user can ask: what does this mean? why is this form used? how is it different from another form? give more examples.
Card context is passed automatically to AI.

Status

Not built.

11. Listening features

11.1 Listening transcription practice

Summary

Users listen to short target-language segments and transcribe them.

Requirements

Exercises organised by level and topic.
Short segment-by-segment audio playback.
User types what they hear.
System compares answer to expected transcript.
User gets corrected transcript and error view.
Mistakes can be saved to learning list or notebook.

Status

Not built. The foundation exists: the “listen” review mode on cards plays audio and auto-grades typed answers via Levenshtein distance. TTS audio generation is operational. A dedicated listening transcription exercise (independent of card review) is not yet implemented.

11.2 Pronunciation playback across the app

Summary

Audio playback is available wherever useful.

Requirements

Audio may be available for:

words
sentences
verb conjugation examples
deck cards
document selections

Status

Built. Just-in-time TTS via AWS Polly with S3 storage. The audio_player_for helper renders a clickable audio icon on any resource. Audio is generated on first click if not already attached. Background preparation (Resources::Verbs::PrepareAudioJob) pre-generates audio for verb pages.

See: docs/features/resource_audio.md

12. Writing practice

12.1 Writing prompt generation

Summary

The application suggests writing topics for the learner.

Requirements

AI can suggest topics based on: current CEFR level, grammar goals, recent mistakes, learning-list vocabulary.
Prompts can be themed, open-ended, or constrained.

Status

Not built.

12.2 Required vocabulary suggestions

Summary

The app recommends words or phrases from the learning list that the learner should try to use in writing.

Requirements

Before writing, the system suggests relevant target vocabulary.
User may choose to include some or all suggested items.
Suggestions should come from saved words, sentences, or weak concepts.

User value

Encourages active reuse of learned material. Helps move items from recognition into production.

Status

Not built. Depends on learning list (8.1).

12.3 AI writing evaluation and correction

Summary

The system reviews learner writing and provides feedback.

Requirements

Grade the writing according to learner level.
Identify errors.
Provide corrected version.
Explain why corrections were made.
Offer alternative ways to express the same idea.
Identify recurring weak areas.
Optionally add problem items to notebook or learning list.

Feedback categories

Grammar, agreement, word choice, tense choice, idiomaticity, spelling, clarity, style appropriate to level.

Status

Partially built. The Language Coach in document write mode assesses submitted writing and gives feedback. The structured evaluation framework (grading, error categorisation, alternative suggestions, recurring weak-area tracking) is not yet implemented.

12.4 Alternative phrasing suggestions

Summary

The app shows better or different ways to express the learner’s intended meaning.

Requirements

Suggest more natural alternatives.
Distinguish between: correct but unnatural, incorrect, more advanced alternative, more concise alternative.

Status

Not built.

13. Progress and motivation

13.1 Achievement dashboard

Requirements

Track:

quizzes completed
study streaks
cards reviewed
concepts mastered
listening sessions completed
writing tasks completed
learning-list growth
reuse of saved vocabulary in writing

Status

Not built. The data layer exists: StudyEvent logs all interactions (views, reviews, audio plays) with timestamps, and UserAbility tracks per-resource mastery with correct/incorrect counts and success rates. An analytics dashboard proposal exists in docs/features/admin_tools/proposed_analytics_metrics.md but targets admin, not learners.

13.2 Brainmap / mastery map

Summary

A visual map of progress across grammar or language concepts.

Requirements

Interactive visual representation of learned and weak concepts.
Colour-coded mastery states.
Click to review or practise specific nodes.

Status

Not built. The grammar category/note hierarchy and UserAbility per-resource scores provide the data. Visualisation is not implemented.

13.3 Improvement timeline

Requirements

Show progress over time for:

estimated mastery
grammar accuracy
listening accuracy
writing performance
card retention
CEFR-readiness indicators

Status

Not built. StudyEvent records are timestamped and immutable, providing the raw data for time-series analysis. No aggregation or visualisation layer exists.

14. Key workflows

14.1 Public reference user

Search verb.
View conjugation table.
Read example sentence for a form.
Play pronunciation.
Decide to sign up for personalised study.

Status: Fully supported.

14.2 Reading-to-learning workflow

Open document in target language.
Click a word or sentence.
See translation and hear pronunciation.
Add item to learning list.
Later create a deck from saved items.

Status: Steps 1–3 work. Steps 4–5 depend on learning lists (8.1) and user-generated decks (9.2).

14.3 Quiz-to-review workflow

Take adaptive quiz.
Get corrections.
Save weak concepts to notebook.
Open AI chat for explanation.
Review later through deck or notebook.

Status: Not yet possible. Depends on adaptive quiz engine (7.3), weak-point notebook (7.5), and contextual AI chat (10.1).

14.4 Capture-to-deck workflow

Save words and sentences from various surfaces.
Open learning list.
Create deck manually or ask AI to generate one.
Review via card-based study.

Status: Step 4 works. Steps 1–3 depend on learning lists (8.1) and AI deck generation (9.4).

14.5 Writing workflow

Receive a writing prompt.
See suggested vocabulary from learning list.
Write response.
Receive grade, corrections, explanations, and alternatives.
Save weak points for future review.

Status: Step 3 works (document write mode). Step 4 is partially built (Language Coach gives feedback). Steps 1, 2, 5 are not built.

15. Feature groups by product area

15.1 Public / free acquisition features

Feature	Status
Free verb tables	Built
Example sentence for each conjugation	Built
Pronunciation playback on reference pages	Built
SEO-friendly reference pages	Built

15.2 Core logged-in learning features

Feature	Status
User accounts	Built
CEFR organisation	Built
Grammar concept library	Built
Prebuilt decks	Built
Card review (FSRS)	Built
Document viewer	Built
Bookmarks	Built
Placement test	Not built
Adaptive quizzes	Not built
Guided study plan	Not built
Notebook	Not built
Learning list	Not built

15.3 Premium / intensive learning features

Feature	Status
AI explanation (documents)	Built
AI explanation (all surfaces)	Not built
AI deck generation	Not built
Document interaction tools	Partially built
Listening transcription	Not built
Writing correction and grading	Partially built
Achievement dashboard	Not built
Brainmap and timeline	Not built

16. Non-goals

The following are explicitly out of scope for the current product direction:

Live tutoring or teacher marketplace. Immersive is a self-directed tool, not a tutoring platform.
User-generated public content. Users can create personal decks and lists but not publish courses or lessons to other users.
Gamification mechanics. No XP points, leaderboards, or competitive elements. Progress tracking focuses on mastery, not competition.
Language pairs without grammar curriculum. New languages require structured grammar content before full learning features are available.
Offline-first architecture. Mobile may support offline review in future, but the product assumes connectivity for AI features, audio generation, and sync.
Chat-based general conversation practice. AI chat is contextual to study surfaces, not open-ended conversation.

17. Key data model entities

This section summarises the primary models in the system grouped by domain. Models marked with “(new)” do not yet exist.

Verbs and conjugation

Model	Purpose
`VerbLemma`	Canonical dictionary form of a verb, per language
`Tense`	Mood + tense combination per language
`Conjugation`	Fully inflected finite form (person x mood x tense)
`Infinitive`	Unconjugated infinitive forms with variants
`Verbal`	Participles and gerunds, with gender/number
`VerbLemmaTranslation`	Translation of lemma into fluent language
`SentenceConjugation`	Links sentences to conjugations
`SentenceInfinitive`	Links sentences to infinitives

Grammar

Model	Purpose
`GrammarCategory`	Groups notes by topic within a CEFR level and language
`GrammarNote`	Single grammar concept with markdown content
`GrammarNoteTranslation`	Translation of a note into a fluent language
`GrammarExercise`	Fill-in-the-blank exercise linking a sentence to a note

Decks and cards

Model	Purpose
`Deck`	Collection of cards, supports nesting via materialised path
`Card` (STI)	Base card with FSRS scheduling fields
`VerbCard`	Card tied to a conjugation
`SentenceCard`	Card for sentence recall
`WordCard`	Card for vocabulary
`NumberCard`	Card for number practice
`Review`	Immutable record of a single card review

Study tracking

Model	Purpose
`StudyEvent`	Immutable log of all user interactions with resources
`UserAbility`	Aggregated mastery state per user per resource

Documents

Model	Purpose
`Document`	Target-language document for reading or writing
`DocumentWord`	Individual word extracted from a document
`DocumentSentence`	Individual sentence extracted from a document
`Folder`	Hierarchical organisation of documents

User and access

Model	Purpose
`User`	Account with Devise authentication
`Bookmark`	Polymorphic save (GrammarNote, Document, Deck)
`Category`	User-created tag
`Categorization`	Polymorphic join linking categories to resources

Proposed new models

Model	Purpose
`LearningList` (new)	Personal collection of captured words and sentences
`LearningListItem` (new)	Individual item with source text, translation, tags, status
`Notebook` / `NotebookEntry` (new)	Weak-point tracking with error history and mastery state
`PlacementResult` (new)	Outcome of a placement test per language
`StudyPlan` / `StudyPlanStep` (new)	Recommended activities based on level and weak points
`WritingSubmission` (new)	User writing with AI evaluation, grade, and corrections
`WritingPrompt` (new)	AI-generated or curated writing topic

18. MVP phases

Shipped (current state)

Public verb tables with conjugation grids and example sentences (7 languages).
Grammar concept library with 343+ French notes, CEFR A1–C1, 5 translation languages.
User accounts with Devise/Pundit.
Decks with FSRS spaced repetition (verb, sentence, word, number cards).
Four review modes: read, write, listen, speak.
Document viewer with read/write modes, click-to-translate, audio.
Language Coach AI in documents.
Just-in-time TTS audio across the app.
Bookmarks and categories.
StudyEvent and UserAbility tracking.
Anki export/sync.

MVP next: capture and adaptive practice

Learning list with multi-surface capture (document, verb, grammar, quiz).
Adaptive grammar quiz engine using existing exercises and UserAbility data.
Weak-point notebook fed by quiz errors.
AI chat expanded to grammar pages and verb pages.
Achievement dashboard with basic metrics (cards reviewed, streaks, concepts mastered).

MVP next+1: guided learning and output

Placement test.
CEFR-aware study plan and recommendation engine.
Create decks from learning list (manual and AI-generated).
AI explanation on cards during review.
Brainmap / mastery visualisation.
Improvement timeline.

MVP next+2: production skills

Listening transcription practice (standalone exercises, not just card review mode).
Writing prompt generation with vocabulary suggestions from learning list.
AI writing evaluation: grading, error categorisation, corrections, alternatives.
Alternative phrasing suggestions.
Recurring weak-area detection across writing submissions.

Mobile

Timeline and platform to be determined.
Initial scope: card review, learning list, grammar browsing, audio playback.
AI features and document interaction to follow.

19. One-sentence product definition

Immersive is a language-learning application that combines free public verb references, CEFR-aligned grammar content, adaptive practice, reading and document-based capture, AI explanation, spaced-repetition memorisation, and guided writing correction into one integrated study system.