DeutschFit — AI-Powered German Learning & TELC Exam Prep Platform 🇩🇪📱

DeutschFit is an intelligent, offline-first mobile application and language learning platform designed specifically for students preparing for standardized German proficiency exams (TELC & Goethe-Zertifikat A1, A2, and B1).

Combining a high-performance React Native / Expo mobile client with Google Gemini LLM pedagogical evaluation and local SQLite storage, DeutschFit provides real-time grammatical diagnostic feedback, interactive reading text analysis, audio comprehension tests, and spaced-repetition vocabulary training.

---

📱 Mobile Application Features (/mobile)

The mobile client is built on Expo SDK 57, utilizing React Native 0.86, React 19, and Expo Router with strict TypeScript type safety:

1. ⚡ Full TELC Exam Simulation ("Hızlı Sınav")

Simulates the actual examination environment across all 4 key sections in sequence:

1. Lesen (Reading): Multi-part reading comprehension passages.
2. Hören (Listening): Audio-based situational dialogues and comprehension questions.
3. Grammatik & Sprachbausteine (Language Elements): Fill-in-the-blank and syntax ordering.
4. Schreiben (Writing): Formal/informal letter and email composition.

2. 📖 Interactive Reading with Tap-to-Analyze (SelectableWord.tsx & StudyModal.tsx)

While reading German passages, users can tap on any single word to trigger instant on-screen morphological breakdown:

• Nouns (Substantive): Definite/indefinite article gender color-coding (der/die/das), plural forms (Pluralbildung), and case analysis.
• Verbs (Verben): Full present tense conjugation (Präsens), past tenses (Perfekt & Präteritum), regularity, and required prepositional valency (Kasus / Rektion).
• Prepositions (Präpositionen): Immediate case classification (Akkusativ, Dativ, or Wechselpräposition).

3. ✍️ Deterministic AI Essay Assessment (GeminiService.evaluateSchreiben)

A dedicated pedagogical evaluation engine that grades student-written texts according to strict CEFR criteria:

• Scoring Breakdown: Exactly 100 points: Aufgabenerfüllung (Task Completion - 40 pts) and Grammatik (Structural Accuracy - 60 pts).
• Automated Rule Checks:
  • Capitalization (Großschreibung): Identifies non-capitalized nouns.
  • V2 Topological Rule (Verb-Zweit-Stellung): Detects inversion errors when time or place adverbs start the clause (e.g., "Heute ich gehe" $\rightarrow$ "Heute gehe ich").
  • Separable Verbs (Trennbare Verben): Enforces correct base verb placement in Position 2 with separable prefixes pinned to the clause end.
  • Case & Agreement (Kasus-Kongruenz): Evaluates subject-verb agreement and object case requirements based on governing prepositions/verbs.
• Constructive Pedagogical Feedback: Explains why an error occurred in clear Turkish, provides targeted grammar tips, and outputs an improved native-level rewrite.

4. 🎧 Semantic Listening Comprehension (Hören)

• Powered by expo-audio for low-latency playback of native German audio dialogs.
• Features semantic answer evaluation via LLM: rather than failing students on rigid exact string matches, the evaluator tolerates minor typographical slips and recognizes equivalent semantic expressions (e.g., valid pronoun substitutions).

5. 📇 Themed Flashcards & Spaced Repetition (/flashcards)

• Categorized by CEFR level (A1, A2, B1) and grammatical categories (Verbs, Fixed Preposition Combinations, Key Adjectives).
• Features interactive flip animations (react-native-reanimated), progress persistence, and mistake-repetition queues.

6. 📊 Offline-First Local Storage (services/db.ts)

• Embedded SQLite database (expo-sqlite) stores vocabulary dictionaries, user attempt histories, and performance analytics locally, ensuring core functionality remains active offline.

---

🛠️ System Architecture

DeutschFit/
├── mobile/                        # Universal Mobile Application (React Native / Expo)
│   ├── src/
│   │   ├── app/                   # File-based routing (Expo Router)
│   │   │   ├── index.tsx          # Main dashboard & level selector (A1 / A2 / B1)
│   │   │   ├── stats.tsx          # Performance radar & study statistics
│   │   │   ├── exercises/         # Exam simulation modules (Lesen, Hören, Grammatik, Schreiben)
│   │   │   └── flashcards/        # Spaced-repetition flashcard deck runner
│   │   ├── components/            # UI components (StudyModal, SelectableWord, InterventionModal)
│   │   ├── services/
│   │   │   ├── gemini.ts          # LLM pedagogical assessment & morphology engine
│   │   │   ├── db.ts              # Local SQLite database client
│   │   │   ├── words.ts           # Vocabulary query helpers & dictionary
│   │   │   └── progress.ts        # Attempt tracking & stats calculator
│   │   └── constants/             # Design tokens, themes & color palettes
│   ├── assets/                    # Audio tracks, iconography & offline SQLite DB
│   └── package.json
│
├── data/                          # Seed datasets, CEFR vocabulary lists & question banks
├── scripts/                       # Python automated data extraction & textbook parsing pipelines
└── README.md                      # Platform documentation

---

🚀 Getting Started Locally

Mobile App (iOS / Android / Web)

# 1. Navigate to the mobile directory
cd mobile

# 2. Install dependencies
npm install

# 3. Configure Gemini API Key (Optional for AI evaluation)
cp .env.example .env
# Set EXPO_PUBLIC_GEMINI_API_KEY=your_key_here

# 4. Start the Expo development server
npx expo start

Press:

• a to open on Android Emulator or connected device.
• i to open on iOS Simulator.
• w to run in a web browser.

---

📄 License

This project is open-source under the MIT License.