Lingua-Learn (Next.js Frontend Integration)

This repository contains the standalone Next.js frontend for the Lingua-Learn language engine. It has been stripped of local backends and is ready to be connected to a production database (like PostgreSQL via FastAPI).

Features Included

• Multi-language Support: Dynamic routing (/[language]) for French, Spanish, German, Japanese, English.
• 9-Stage Learning Loop: Vocabulary, Dialogues, Meaning Match, Word Match, Listening, Speaking, Typing, Fill-in-the-blanks, Sentence Building.
• Offline PDF Generation: Uses html2pdf.js to generate beautiful printable notes for any completed lesson directly on the client.
• Spaced Repetition Engine (Intelligence Engine): Client-side algorithms to track mistakes and calculate mastery per concept.
• Native Browser TTS & STT: Uses Web Speech API for Text-to-Speech (native accents) and Speech Recognition (grading user pronunciation).
• Gamification: Confetti, progress bars, audio feedback (correct/incorrect sounds), and locked/unlocked state tracking.

---

🛠 Integration Requirements

Currently, the engine uses localStorage for testing purposes to maintain sessions and mistakes. To integrate this into the Samidha-E-Guru backend (FastAPI + PostgreSQL + SQLAlchemy), you need to create the following database architecture.

1. Database Schema (SQLAlchemy Models)

You will need three main tables to replace the local storage logic:

from sqlalchemy import Column, Integer, String, Boolean, JSON, ForeignKey, DateTime
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class UserProgress(Base):
    """Tracks overall completion of units and lessons"""
    __tablename__ = 'user_progress'
    
    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, index=True) # Link to your existing User table
    language_code = Column(String) # e.g., 'french'
    unit_id = Column(String)       # e.g., 'unit-01'
    lesson_id = Column(String)     # e.g., 'lesson-01'
    completed = Column(Boolean, default=False)
    score = Column(Integer, default=0)
    completed_at = Column(DateTime)

class LessonSession(Base):
    """Replaces localStorage(`lingua_session_{lang}_{lesson_id}`)"""
    __tablename__ = 'lesson_sessions'
    
    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, index=True)
    language_code = Column(String)
    lesson_id = Column(String)
    current_module_index = Column(Integer, default=0)
    finished = Column(Boolean, default=False)
    updated_at = Column(DateTime)

class MistakeLog(Base):
    """Replaces IntelligenceEngine localStorage mistakes array"""
    __tablename__ = 'mistake_logs'
    
    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, index=True)
    language_code = Column(String)
    concept_id = Column(String)    # e.g., 'vocab_bonjour'
    module_type = Column(String)   # e.g., 'typing', 'speaking'
    mistake_count = Column(Integer, default=1)
    last_mistake_at = Column(DateTime)

---

2. Replacing Frontend LocalStorage

A. Session State (lingua_session_...)

In components/engine/LessonEngine.tsx, there are two useEffect hooks handling session recovery and saving:

• Current Logic: Reads/Writes to localStorage.getItem(sessionKey).
• Action Required:
  1. Create a FastAPI endpoint GET /api/progress/session?lang={lang}&lesson={id}.
  2. Create a FastAPI endpoint POST /api/progress/session.
  3. Swap the localStorage calls in LessonEngine.tsx with standard fetch or axios calls to your API.

B. Mistakes & Mastery (intelligence-engine.ts)

In lib/intelligence-engine.ts, the system logs mistakes when the user gets a question wrong.

• Current Logic: Pushes to localStorage.getItem('lingua_mistakes').
• Action Required:
  1. Create a FastAPI endpoint POST /api/progress/mistake that accepts { conceptId, moduleType, languageCode }.
  2. Update the addMistake() method in intelligence-engine.ts to push to your API asynchronously.
  3. Create a GET /api/progress/mistakes?lang={lang} to populate the "Mistakes to Review" page.

---

🚀 Deployment (Vercel)

This repository is pre-configured for Vercel.

1. Push this repository to GitHub.
2. Import the repository in Vercel.
3. Framework Preset: Next.js.
4. Root Directory: ./
5. Vercel will automatically detect next build and deploy the application.

No environment variables are required out of the box unless you add your backend API URL (e.g., NEXT_PUBLIC_API_URL=https://your-fastapi-backend.com).

Current deployment link 🔗: https://lingua-learn-silk.vercel.app/