added examples

2025-11-06 21:22:28 +01:00
parent fdf335b346
commit e5b9bb1b69
5 changed files with 1028 additions and 0 deletions
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,175 @@
+# Flalingo Path JSON Structure Documentation
+
+This directory contains example JSON files that demonstrate the structure of learning paths in the Flalingo language learning application.
+
+## Overview
+
+A learning path in Flalingo is a structured sequence of educational content organized into nodes, where each node contains multiple exercises. The JSON structure mirrors the Rust data models used in the application.
+
+## File Examples
+
+- **`example_path.json`** - Comprehensive example showing a complete German family vocabulary path
+- **`simple_path.json`** - Basic example for beginners (German greetings)
+- **`advanced_path.json`** - Complex business German communication path
+
+## JSON Structure
+
+### Root Path Object
+
+```json
+{
+  "id": "string",           // Unique identifier for the path
+  "title": "string",        // Human-readable path title
+  "description": "string",  // Detailed description of the path content
+  "metadata": [...],        // Array of metadata objects
+  "nodes": [...]           // Array of node objects
+}
+```
+
+### Metadata Object
+
+```json
+{
+  "path_id": "string",      // Reference to parent path ID
+  "version": "string",      // Semantic version (e.g., "1.2.0")
+  "created_at": "string",   // ISO 8601 UTC timestamp
+  "updated_at": "string"    // ISO 8601 UTC timestamp
+}
+```
+
+### Node Object
+
+```json
+{
+  "id": number,             // Unique numeric identifier
+  "title": "string",        // Node title/name
+  "description": "string",  // Node description
+  "path_id": "string",      // Reference to parent path ID
+  "exercises": [...]        // Array of exercise objects
+}
+```
+
+### Exercise Object
+
+```json
+{
+  "id": number,             // Unique numeric identifier
+  "ex_type": "string",      // Exercise type (see types below)
+  "content": "string",      // JSON-encoded exercise content
+  "node_id": number         // Reference to parent node ID
+}
+```
+
+## Exercise Types
+
+The `ex_type` field defines the type of exercise. Common types include:
+
+### Basic Types
+- **`vocabulary`** - Single word/phrase learning
+- **`multiple_choice`** - Question with multiple answer options
+- **`fill_blank`** - Complete sentences with missing words
+- **`translation`** - Translate between languages
+- **`listening`** - Audio comprehension exercises
+
+### Interactive Types
+- **`drag_drop`** - Match items by dragging and dropping
+- **`conversation`** - Simulated dialogue practice
+- **`speaking`** - Voice recording and pronunciation
+- **`role_play`** - Interactive scenario-based exercises
+
+### Advanced Types
+- **`grammar_explanation`** - Detailed grammar lessons
+- **`story_completion`** - Complete narrative texts
+- **`comprehensive_quiz`** - Multi-format assessment
+- **`case_study_comprehensive`** - Complex real-world scenarios
+
+## Exercise Content Structure
+
+The `content` field contains a JSON-encoded string with exercise-specific data:
+
+### Vocabulary Exercise
+```json
+{
+  "word": "der Vater",
+  "translation": "father", 
+  "audio": "/audio/vater.mp3",
+  "example": "Mein Vater ist Arzt."
+}
+```
+
+### Multiple Choice Exercise
+```json
+{
+  "question": "How do you say 'sister' in German?",
+  "options": ["die Schwester", "der Schwester", "das Schwester", "die Schwestern"],
+  "correct": 0,
+  "explanation": "'Die Schwester' is feminine, so it uses the article 'die'."
+}
+```
+
+### Conversation Exercise
+```json
+{
+  "scenario": "Family introduction at a party",
+  "dialogue": [
+    {"speaker": "A", "text": "Ist das deine Familie?"},
+    {"speaker": "B", "text": "Ja, das sind meine Eltern und mein Bruder."}
+  ],
+  "vocabulary_focus": ["Familie", "Eltern", "Alter", "Beruf"]
+}
+```
+
+### Listening Exercise
+```json
+{
+  "audio_file": "/audio/family_description.mp3",
+  "transcript": "Hallo, ich heiße Anna...",
+  "questions": [
+    {"question": "Wie heißt die Frau?", "answer": "Anna"},
+    {"question": "Ist sie verheiratet?", "answer": "Ja"}
+  ]
+}
+```
+
+## Design Principles
+
+### Progressive Difficulty
+Paths are structured with increasing complexity:
+1. **Simple vocabulary introduction**
+2. **Basic grammar concepts** 
+3. **Practical application**
+4. **Comprehensive review**
+
+### Content Organization
+- **Logical grouping**: Related concepts are grouped within nodes
+- **Sequential learning**: Nodes build upon previous knowledge
+- **Mixed exercise types**: Various formats maintain engagement
+- **Real-world context**: Practical scenarios and authentic language use
+
+### Metadata Usage
+- **Version control**: Track content updates and revisions
+- **Timestamps**: Monitor content freshness and usage patterns
+- **Path relationships**: Enable content dependencies and prerequisites
+
+## File Naming Convention
+
+- `simple_*.json` - Beginner level (A1-A2)
+- `example_*.json` - Intermediate level (B1-B2) 
+- `advanced_*.json` - Advanced level (C1-C2)
+- `specialized_*.json` - Domain-specific content (business, academic, etc.)
+
+## Integration Notes
+
+These JSON files can be:
+- **Imported** into the SQLite database using migration scripts
+- **Exported** from the database for backup or sharing
+- **Used as templates** for creating new learning paths
+- **Validated** against the Rust type system for consistency
+
+## Validation
+
+All JSON files should be validated for:
+- **Structure compliance** with the documented schema
+- **Content consistency** (valid references, proper formatting)
+- **Educational quality** (appropriate difficulty progression, clear instructions)
+- **Technical accuracy** (valid audio paths, properly encoded JSON strings)