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¶

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¶

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¶

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