FlashDay vNext — greenfield rebuild

Decision

Stop evolving the current lesson runner/content architecture.

The existing application remains in Git history as a prototype/reference. vNext is a greenfield learning system built in the same repository on rebuild/vnext.

Do not port old lessons, UI, gamification, AI tutor, or Firebase-specific assumptions by default. Every old subsystem must earn its way back by satisfying the new learning architecture.

Product problem

The old project was built bottom-up:

content
→ widgets
→ lesson runner
→ review
→ features
→ attempt to infer learning

vNext will be built top-down:

REAL-LIFE CAPABILITY
→ evidence contract
→ assessment task
→ learning progression
→ practice/retrieval
→ spacing/transfer
→ learner model
→ session planner
→ UI

North Star

The learner must become able to understand and use English in situations outside the app.

No metric is allowed to stand in for that:

• lesson completion;
• streak;
• XP;
• time in app;
• flashcard count;
• transcript match;
• AI conversation time.

Reference inputs

Keep as research inputs, not implementation constraints:

• Duolingo: curriculum sequencing, constrained personalization, integrated review, experimentation.
• GSE/CEFR: capability-oriented outcomes and assessment alignment.
• Nation Four Strands: program-level balance.
• Retrieval practice + spacing: durable memory.
• Corrective feedback + retry.
• Transfer/delayed assessment.
• Vietnamese learner-specific research to be added separately.

vNext architecture

1. Capability graph

Atomic ability nodes. Each defines:

• performance;
• criteria;
• conditions;
• prerequisites;
• language requirements;
• evidence required;
• transfer condition;
• external framework mappings where useful.

Mission != capability. A mission may exercise several capabilities.

2. Assessment-first contract

Before designing teaching screens, define:

• what counts as a successful attempt;
• what support is allowed;
• what invalidates independence;
• what must be tested later;
• what changes in transfer context.

3. Learning progression

Default progression:

comprehensible input
→ notice
→ guided retrieval
→ supported output
→ interaction
→ feedback
→ retry
→ delayed retrieval
→ transfer
→ fluency

Not every session must contain every phase.

4. Learner evidence model

Append-only durable events.

Separate:

• observed attempt;
• support used;
• correctness/task success;
• modality;
• latency where useful;
• confidence only when measurable;
• delayed evidence;
• transfer evidence.

Derived learner state is rebuildable.

5. Memory

FSRS (or replacement only if benchmark proves better) schedules exact retrieval abilities.

Memory state is not proficiency state.

6. Planner

Pure deterministic planner initially.

Priority:

• resume in-flight work;
• due retrieval;
• remediation;
• transfer/checkpoint;
• next capability/mission.

AI may later personalize variants inside planner constraints. AI never owns curriculum order.

7. Session engine

No hard-coded five-pane lesson template.

A session is generated from a capability/mission contract and can compose only the interactions actually needed.

8. Content system

Course-as-data / course-as-code.

Separate:

learning domain
content
session engine
UI
persistence
assessment
analytics

Content must pass automated checks for:

• unknown-language load;
• prerequisites;
• duplicate/ambiguous targets;
• evidence coverage;
• assessment alignment.

9. Vietnamese learner model

Research-driven layer for:

• L1 interference;
• likely listening contrasts;
• pronunciation/intelligibility issues;
• grammar transfer;
• common error patterns;
• Vietnamese explanations/examples when useful.

No stereotype becomes curriculum without evidence.

10. Assessment/profile

Keep separate:

• curriculum position;
• memory strength;
• observed task ability;
• transfer ability;
• proficiency profile.

No single fake progress percentage.

Build phases

Phase 0 — Rebuild spec

No feature coding.
Deliver:

• domain schema;
• event schema;
• capability graph schema;
• assessment contract;
• planner contract;
• session contract;
• content authoring format;
• migration/non-migration decision for old user data;
• test strategy.

Phase 1 — Headless learning engine

Build pure core with zero UI:

• 10–20 capability nodes;
• prerequisites;
• evidence projection;
• planner;
• FSRS integration;
• transfer state;
• deterministic replay;
• content validation.

All executable through tests/fixtures.

Phase 2 — One end-to-end learning slice

Build one real-world mission using the new engine.

Must prove:

baseline fail
→ teaching
→ unaided attempt
→ feedback
→ retry
→ delayed retrieval
→ changed-context transfer

No auth/AI/gamification required.

Phase 3 — Minimal learner UI

Build only:

• Today / next action;
• mission player;
• review/retrieval;
• capability profile.

Mobile-first. One primary action per screen.

Phase 4 — First coherent curriculum block

Build a small multi-session sequence from capability graph, not old lesson numbering.

Test:

• cognitive load;
• retention;
• transfer;
• support dependency;
• learner confusion.

Phase 5 — Persistence/account

Only after core learning behavior is stable:

• local durable store;
• cloud sync;
• multi-device replay;
• auth.

Phase 6 — Rich input + speaking

Add only where capability requirements justify:

• stories/audio;
• listening-only retrieval;
• conversation;
• pronunciation/intelligibility;
• AI partner.

Phase 7 — Engagement

Only after learning metrics exist:

• reminders;
• streak/habit tools if useful;
• social/gamification experiments.

Engagement cannot substitute for learning evidence.

Hard reset rules

Do NOT:

• port Lessons 2–30;
• rebuild old runner screen-for-screen;
• reproduce old CSS/design system first;
• add AI before the core engine needs it;
• preserve APIs solely because they already exist;
• optimize Firebase before learning architecture is stable;
• build a “Duolingo clone”;
• use streak/XP as primary progress.

What can be reused

Reuse only after review:

• task-level FSRS ideas;
• append-only evidence/replay concepts;
• deterministic planner lessons;
• useful tests;
• auth/cloud code later if still appropriate;
• research docs.

Everything else is replaceable.

Definition of vNext foundation done

Before product UI work begins, the repository must be able to answer in tests:

What capability is being trained?
What prior ability does it depend on?
What task produces evidence?
Was the attempt aided?
When should this exact ability return?
Has the learner retained it later?
Has it transferred to a changed context?
Why is this the next action?

If the headless engine cannot answer those questions, do not build the UI.