wordpecker-app

# WordPecker App **Every word has a story.** A personalized language-learning app that brings the magic of Duolingo-style lessons to your own curated vocabulary lists and contexts. ## Looking for Mobile App Testers! We’ve started developing the mobile version of our web project Right now, we’re in the beta testing phase and looking for testers to try the app and share their feedback. If you’d like to become a tester: Send an email to [[email protected]] with the subject "Tester Application". In your email, please include: Your name / username A short note about yourself Your feedback will help us make the app even better Thank you for your support! ❤️ ## Table of Contents - [ Quick Start](#-quick-start) - [The Idea](#the-idea) - [How It Works](#how-it-works) - [Demo](#demo) - [Roadmap](#roadmap) - [Getting Started](#getting-started) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Database Setup](#database-setup) - [Configuration](#configuration) - [Development](#development) - [Docker Setup (Recommended)](#docker-setup-recommended) - [Quick Start with Docker](#quick-start-with-docker) - [Docker Commands](#docker-commands) - [MongoDB Access](#mongodb-access) - [Running Only MongoDB with Docker](#running-only-mongodb-with-docker) - [Easy Startup Script](#easy-startup-script) - [Troubleshooting](#troubleshooting) - [Architecture](#architecture) - [Contributing](#contributing) - [License](#license) ## Quick Start - ** Docker (Recommended):** [Quick Start with Docker](#quick-start-with-docker) - ** Local Development:** [Manual Installation](#installation) - **️ MongoDB Only:** [Running Only MongoDB](#running-only-mongodb-with-docker) ---

Watch on YouTube

## The Idea Learning a new language can be straightforward, but mastering it is the real challenge. While it's relatively easy to grasp the basics, developing strong communication or reading skills depends on having a solid vocabulary. To build this, you must learn words and phrases at various levels, yet exposure is key. For instance, if you've studied English but don't live in an English-speaking country, advancing your skills becomes significantly harder. You can read books, watch movies, or browse blogs, but fully immersing yourself in the language is still difficult. Real progress often requires extra effort—studying and revisiting words and phrases encountered in your daily life. However, this process can be inconvenient. You have to pause whatever you're doing to note new words, search their meanings, record them, and then review them later. This is time-consuming and tiring. As a result, although you might improve, the learning process can feel painfully slow and inefficient. To solve this, I had an idea for an app that merges personalized learning with the efficiency of flashcards—a blend of Duolingo-like lessons and custom study lists. In the previous version, you'd read your book, encounter new words, create a list, manually add each word, and then practice. You'd open the app, create a new list with details like "Harry Potter Book," add the words you found, and the app would provide meanings so you could continue reading without interruption. Later you'd practice with exercises and quizzes. This worked great when you were actively reading or consuming content, but what about when you just wanted to expand your vocabulary anytime, anywhere? But here's where it gets exciting – **we've added a new feature to discover and encounter new words**. Instead of manually hunting down vocabulary, you can now encounter words naturally with much less effort: ### Vision Garden (My Personal Favorite!) Imagine looking at images and describing them to discover new vocabulary. You can use LLM-generated images or real stock photos, describe what you see, and agent analyzes your description to suggest contextual vocabulary words you might not know. It's like having a personal tutor who shows you pictures and helps you expand your vocabulary naturally. The agent considers your current vocabulary and suggests words that fit your learning level and context.

Watch on YouTube

### Get New Words - Smart Vocabulary Discovery Choose any context or topic you're interested in (like "space exploration" or "cooking techniques"), select your difficulty level, and let agent generate vocabulary words you don't already have. Then dive into interactive learning sessions where you can: - **Know/Don't Know Interface**: Simple binary choice for each word - **Progressive Disclosure**: Reveals definitions, examples, and visuals when you don't know the word - **Context-Aware Generation**: Excludes words you already know, focuses on your chosen difficulty level - **Visual Integration**: Generate images for words you're learning to create stronger memory connections - **List Building**: Add learned words to existing lists or create new context-specific collections No more manually searching for words – just pick a theme and difficulty, and get learning experience that adapts to your knowledge.

Watch on YouTube

### ️ Voice Chat This is where things get really interactive. Using OpenAI's voice agents you can have actual spoken conversations with an LLM tutor about your vocabulary words. Practice pronunciation, ask questions, and get instant feedback through natural speech. It's like having a language exchange partner available 24/7 who knows exactly what words you're learning. The voice agent has access to your list and help you learn the words you already have and it can add new words to your lists by using the tool.

Watch on YouTube

Once you've discovered words through these methods, you can: - **Learn**: Practice with 5 different question types (multiple choice, fill-in-the-blank, matching, true/false, and sentence completion) - all configurable in your settings - **Quiz**: Test your knowledge and track your progress with learned points - **Voice Practice**: Have conversations about your vocabulary with the LLM voice tutor - **Light Reading**: Generate reading passages that highlight your vocabulary words in context

Watch on YouTube

Watch on YouTube

### Word Detail Pages - Deep Dive Into Every Word Each word in your vocabulary gets its own comprehensive page where you can: - **Context Explorer**: See how the same word appears across different lists with different meanings and track your progress in each context - **Example Generator**: Create contextual example sentences with translations and detailed usage notes - **Visual Learning**: Generate LLM images or find stock photos that represent the word in its specific context - **Similar Words Discovery**: Find synonyms and interchangeable words with examples and usage notes - **Smart Collection**: Add discovered similar words to your existing lists or create new context-specific lists

Watch on YouTube

### Audio Pronunciation System - Every Word Has A Voice Pronunciation for immersive learning. ### Multi-Language The app now supports learning **any language using any language**. Want to learn Japanese using Turkish? Or practice advanced English while getting explanations in Spanish? Just configure your native language (base) and target language in settings. The LLM even validates specific language variants like "Japanese with Hiragana" or "Brazilian Portuguese".

Watch on YouTube

### Template Library Jump-start your learning with curated vocabulary lists. Browse templates by category, difficulty, and tags, then clone them to create your own customized lists. ### Classic Word Lists - The Original Power Of course, the original way still works! Create your own context-aware lists the traditional way: - **Create Custom Lists**: Make lists with any name, description, and context (like "Harry Potter Book," "Business Meeting Vocabulary," etc.) - **Add Words Instantly**: Just type a word and - it's automatically defined in your chosen context - **Context-Aware Definitions**: Each word gets its meaning based on your list's context, so "bank" means something different in "Financial Terms" vs "Geography Vocabulary" - **Manual Control**: Perfect for when you encounter specific words while reading, watching movies, or in conversations - **Flexible Organization**: Organize your vocabulary exactly how you want it This is still the most direct way to build your vocabulary when you know exactly what words you want to learn!

Watch on YouTube

The key advantage is that the app keeps your learning tied to the context in which you originally saw the words. By returning to them in their original setting, you strengthen those specific neural pathways, speeding up retention and making learning significantly more effective. **In short, it's like having a personalized Duolingo where you can create and learn from your own lists, but with the added ehancements of natural word discovery and voice interaction. It's a powerful way to immerse yourself in the language and make steady progress.**

## How It Works ### Recommended Learning Flow Choose the approach that fits your learning style and situation: ## **The Discovery Path** - For Explorers Who Want Effortless Learning Perfect when you want to expand your vocabulary without the effort of hunting for words: 1. **Discover Words Naturally**: - **Vision Garden**: Look at images in generated context, describe what you see, and get vocabulary suggestions based on what you missed or could express better - **Get New Words**: Create a session with any context you're interested in, then go through interactive know/don't know sessions with LLM-generated vocabulary that fits your learning level 2. **Build Your Collection**: - Add discovered words to your existing lists or create new context-specific ones - Use the **Template Library** to quickly start with professionally curated lists 3. **Explore & Expand**: - Click on any word to access its **Word Detail Page** for deep exploration - Generate example sentences, find similar words, and create visual associations - Add discovered similar words to expand your vocabulary further 4. **Practice & Reinforce**: - Use **Voice Chat** to have real conversations about your vocabulary - Generate **Light Reading** passages that highlight your vocabulary words - Go to **Learn Mode** and practice with various question types - Take **Quizzes** to assess your retention and collect learned points ## **The Traditional Path** - For Focused Learners Who Know What They Want Perfect when you encounter specific words and want to learn them immediately: 1. **Create Context-Aware Lists**: - Make **Word Lists