flalingo/examples

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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "word": "der Vater",
  "translation": "father", 
  "audio": "/audio/vater.mp3",
  "example": "Mein Vater ist Arzt."
}

Multiple Choice Exercise

{
  "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

{
  "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

{
  "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)