flalingo/examples/README.md

# 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)