.. _overview:

Project Overview
================

LinguaAI is a language-learning platform that combines an AI-powered conversational
tutor with real-time pronunciation feedback and OCR-based text recognition.

Key Features
------------

- **AI Tutor** — Conversational practice sessions powered by large language models
- **Pronunciation Feedback** — Real-time phoneme-level scoring via WebSocket audio streaming
- **OCR Scanner** — Capture text from the physical world using Google ML Kit
- **Onboarding** — Personalised learning paths based on proficiency level, goals, and focus areas
- **Progress Tracking** — Statistics, detailed analytics, and weak-area identification
- **Gamification** — XP points, streaks, and badges (planned)

Technology Stack
----------------

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - Layer
     - Technology
     - Notes
   * - Backend framework
     - FastAPI 0.128
     - Async, modular monolith
   * - ASGI server
     - Uvicorn 0.40
     - Development & production
   * - Database
     - PostgreSQL (via Supabase)
     - Relational + JSONB hybrid
   * - Authentication
     - Supabase Auth
     - Email/password + Google OAuth
   * - Token format
     - JWT (HS256, 24 h expiry)
     - Signed with ``JWT_SECRET_KEY``
   * - Password hashing
     - bcrypt
     - Via ``bcrypt`` 5.0
   * - Frontend
     - Flutter 3.9
     - iOS, Android, Web
   * - OCR
     - Google ML Kit
     - On-device text recognition
   * - Real-time audio
     - WebSocket
     - Whisper / HuggingFace ASR

Repository Layout
-----------------

.. code-block:: text

   LinguaAI/
   ├── backend/                  # Python FastAPI application
   │   ├── app/
   │   │   ├── main.py           # App entry point, CORS, router registration
   │   │   ├── core/             # Config, DB client, security, logging
   │   │   └── modules/          # Feature modules
   │   │       ├── auth/         # Email/password + Google OAuth (implemented)
   │   │       ├── dictionary/   # Personal vocabulary lookup and storage (implemented)
   │   │       ├── flashcards/   # Flashcard decks and AI generation (implemented)
   │   │       ├── gamification/ # Fluency points, streaks, badges (implemented)
   │   │       ├── lessons/      # Field-based lessons and submissions (implemented)
   │   │       ├── users/        # User profile and streak management (implemented)
   │   │       ├── learning/     # AI tutor, spaced repetition (planned)
   │   │       └── speaking/     # Pronunciation scoring WebSocket (planned)
   │   ├── tests/
   │   │   ├── conftest.py
   │   │   ├── unit/
   │   │   └── integration/
   │   └── supabase/
   │       └── migrations/
   ├── frontend/                 # Flutter application
   │   └── lib/
   │       ├── main.dart
   │       ├── screens/          # Full-page UI screens
   │       ├── services/         # HTTP and Supabase service classes
   │       └── widgets/          # Reusable UI components
   ├── ADRs/                     # Architecture Decision Records
   └── docs/                     # This documentation

Module Status
-------------

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - Module
     - Status
     - Description
   * - ``auth``
     - Implemented
     - Full email/password and Google OAuth flows
   * - ``users``
     - Implemented
     - User profile and streak management
   * - ``dictionary``
     - Implemented
     - Personal vocabulary lookup and local/remote sync
   * - ``flashcards``
     - Implemented
     - Flashcard decks built manually or from dictionary
   * - ``lessons``
     - Implemented
     - Field-based multiple choice assessment
   * - ``gamification``
     - Implemented
     - Fluency points, leaderboards, and badges
   * - ``learning``
     - Planned
     - AI tutor sessions, spaced repetition
   * - ``speaking``
     - Planned
     - WebSocket-based pronunciation scoring