LinguaLoop is a full-stack, sentence-based language learning tool inspired by the spaced repetition principles of Anki. This application enables users to learn languages in context by creating and reviewing sentence pairs, with advanced audio features and an AI-powered chat for conversation practice.
The project is built with a modern microservices architecture using Node.js for the backend and React for the frontend, all containerised with Docker for easy setup and development.
Version v1.0 includes:
-
Full User Authentication
Secure user registration and login using JWT, with password reset functionality via email (simulated). -
Complete Deck & Sentence Management
Full CRUD (Create, Read, Update, Delete) functionality for both decks and the sentences within them, including language selection for native and target languages. -
AI-Powered Chat
Practice conversations with an AI-powered chat partner. Choose a scenario and the application will generate a character for you to interact with. -
Bulk JSON Import
Quickly populate your account by uploading a JSON file containing multiple decks and sentences. -
Spaced Repetition System (SRS)
A robust backend engine that schedules card reviews at optimal intervals based on user performance:Again,Hard,Good,Easy. Implements the SM-2 algorithm for intelligent review scheduling. -
Interactive Library
Clean UI with collapsible (accordion-style) decks and lazy-loaded sentences for performance. -
Advanced Audio Tools
- Text-to-Speech: Listen to sentence pronunciation using the Web Speech API.
- Voice & Speed Controls: Choose browser voices, adjust playback speed and volume.
- User Voice Recording: Record your own pronunciation using the MediaRecorder API.
-
Statistics & Progress Tracking
- A dedicated page that visualises learning progress with charts and metrics including new, learning, mature, and due sentences.
LinguaLoop follows a microservices architecture with the following services:
- React application built with Vite
- Uses React Router for navigation and Chart.js for visualizations
- Communicates with backend microservices via REST APIs
- Implements responsive UI with audio controls and spaced repetition interfaces
- Manages user registration, authentication, and profile updates
- Handles JWT token generation and validation
- Provides password reset functionality
- Uses bcrypt for secure password hashing
- Manages decks and sentences (sentence pairs)
- Handles creation, retrieval, updating, and deletion of decks and sentences
- Implements bulk import functionality for JSON data
- Supports native and target language specification
- Implements the SM-2 spaced repetition algorithm
- Processes user review grades (Again, Hard, Good, Easy) to calculate next review intervals
- Updates sentence intervals and ease factors based on user performance
- Stores review history for analytics
- Provides user statistics and learning analytics
- Calculates sentence states (new, learning, mature, due) based on SRS data
- Tracks review history over different time windows (week, month, 3 months)
- Provides data for the library charts
- Acts as a proxy to various Large Language Model (LLM) providers like Google Gemini or OpenRouter.
- Provides a unified interface for generating text-based responses.
- PostgreSQL database for persistent storage
- Relational schema with users, decks, sentences, and reviews tables
- Foreign key relationships for data integrity
- SRS parameters stored at the sentence level (interval, ease_factor, due_date)
| Component | Technology |
|---|---|
| Frontend | React (Vite), React Router, Axios, Chart.js, React-i18next |
| Backend Services | Node.js, Express.js (5.x) |
| Database | PostgreSQL |
| Architecture | Microservices |
| Containerization | Docker, Docker Compose |
| Authentication | JWT, bcrypt |
| AI Integration | Google Generative AI, OpenRouter |
| Testing | N/A (Unit tests would be added in future iterations) |
The application uses a PostgreSQL database with the following main tables:
- users: Stores user information (email, password hash, profile)
- decks: Contains language learning decks per user
- sentences: Sentence pairs with SRS parameters for spaced repetition
- reviews: Review history to track user progress and performance
The schema includes foreign key relationships to maintain data integrity and enable efficient queries across related entities.
Follow these steps to run the entire application locally.
- Node.js (v20 or later)
- Docker Desktop
- Docker Compose
- Google Gemini API key or OpenRouter API key (for AI chat feature)
git clone git@github.com:availlogic/lingualoop.git ./LinguaLoop
cd LinguaLoopCreate a .env file in the root directory (copy from .env.example):
cp .env.example .envFor the basic functionality, no external API keys are required. If you want to enable the AI chat features, add your Google Gemini or OpenRouter API key to the .env file and set the LLM_PROVIDER variable.
This single command will build and start the container for the frontend, all backend microservices, and the database.
docker compose up --buildWait for all the services to build and start.
Keep this terminal window open. You will see logs from the frontend and all backend services.
Once the frontend is running, open your browser and navigate to:
You can now register a new user and start using the LinguaLoop application.
Unit and integration tests are currently not implemented but would be added in future iterations. The architecture supports testing through its modular service design.
- Passwords are hashed using bcrypt
- JWT tokens with configurable expiration (7 days default)
- Input validation and sanitization on all endpoints
- Proper error handling to avoid information disclosure
- Rate limiting would be implemented in production (not included in MVP)
- Microservices architecture allows for independent scaling of services
- Database queries are optimized with proper indexing (would be implemented in production)
- Docker-based deployment enables horizontal scaling
- API design supports caching layers for improved performance
This project is licensed under the Apache 2.0 License.