Skip to content

Models

This section documents the data models used in the PhonoLab backend.

Phoneme Models

Vowel

Bases: Model

Database model representing a vowel phoneme in the PhonoLab system.

Attributes:

Name Type Description
id str

Unique identifier for the vowel.
phoneme str

The IPA symbol for the vowel.
name str

Human-readable name for the vowel.
audio_url str

URL to the audio file demonstrating the vowel sound.

Relationships: word_examples: One-to-many relationship with WordExample model. lesson: One-to-one relationship with Lesson model (via backref).

Source code in src/models/phoneme.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
class Vowel(db.Model):
    """
    Database model representing a vowel phoneme in the PhonoLab system.

    Attributes:
        id (str): Unique identifier for the vowel.
        phoneme (str): The IPA symbol for the vowel.
        name (str): Human-readable name for the vowel.
        audio_url (str): URL to the audio file demonstrating the vowel sound.
    Relationships:
        word_examples: One-to-many relationship with WordExample model.
        lesson: One-to-one relationship with Lesson model (via backref).
    """
    __tablename__ = "vowels"

    id = db.Column(db.String, primary_key=True)
    phoneme = db.Column(db.String, nullable=False)
    name = db.Column(db.String, nullable=False)
    ipa_example = db.Column(db.String, nullable=False)
    color_code = db.Column(db.String, nullable=False)
    audio_url = db.Column(db.String, nullable=False)
    description = db.Column(db.String, nullable=False)

    # New fields from vowel.json
    pronounced = db.Column(db.String, nullable=True)
    common_spellings = db.Column(db.JSON, nullable=True)
    lips = db.Column(db.String, nullable=True)
    tongue = db.Column(db.String, nullable=True)
    example_words = db.Column(db.JSON, nullable=True)
    mouth_image_url = db.Column(db.String, nullable=True)

    word_examples = db.relationship(
        "WordExample",
        backref="vowel",
        cascade="all, delete-orphan",
        lazy=True
    )

    def to_dict(self):
        return {
            "id": self.id,
            "phoneme": self.phoneme,
            "name": self.name,
            "ipa_example": self.ipa_example,
            "color_code": self.color_code,
            "audio_url": self.audio_url,
            "description": self.description,
            "pronounced": self.pronounced,
            "common_spellings": self.common_spellings,
            "lips": self.lips,
            "tongue": self.tongue,
            "example_words": self.example_words,
            "mouth_image_url": self.mouth_image_url,
            "word_examples": [we.to_dict() for we in self.word_examples]
        }

    def get_lesson_card(self):
        """
        Return a dictionary with the lesson card information.
        """
        return {
            "pronounced": self.pronounced,
            "common_spellings": self.common_spellings,
            "lips": self.lips,
            "tongue": self.tongue,
            "example_words": self.example_words
        }

    def __repr__(self):
        return f"<Vowel id={self.id} phoneme='{self.phoneme}' name='{self.name}'>"

get_lesson_card

Return a dictionary with the lesson card information.

Source code in src/models/phoneme.py 
61
62
63
64
65
66
67
68
69
70
71
def get_lesson_card(self):
    """
    Return a dictionary with the lesson card information.
    """
    return {
        "pronounced": self.pronounced,
        "common_spellings": self.common_spellings,
        "lips": self.lips,
        "tongue": self.tongue,
        "example_words": self.example_words
    }

WordExample

Bases: Model

Database model representing example words that contain specific vowel sounds.

Attributes:

Name Type Description
id int

Unique identifier for the word example.
word str

The example word containing the target vowel.
audio_url str

URL to the audio file of the word.
ipa str

IPA transcription of the word.
example_sentence str

Example sentence using the word.
vowel_id str

Foreign key to the associated vowel.
Relationships

vowel: Many-to-one relationship with the Vowel model.

Source code in src/models/phoneme.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
class WordExample(db.Model):
    """
    Database model representing example words that contain specific vowel sounds.

    Attributes:
        id (int): Unique identifier for the word example.
        word (str): The example word containing the target vowel.
        audio_url (str): URL to the audio file of the word.
        ipa (str): IPA transcription of the word.
        example_sentence (str): Example sentence using the word.
        vowel_id (str): Foreign key to the associated vowel.

    Relationships:
        vowel: Many-to-one relationship with the Vowel model.
    """
    __tablename__ = "word_examples"

    id = db.Column(db.Integer, primary_key=True)
    word = db.Column(db.String, nullable=False)
    audio_url = db.Column(db.String, nullable=False)
    ipa = db.Column(db.String, nullable=True)
    example_sentence = db.Column(db.String, nullable=True)
    vowel_id = db.Column(db.String, db.ForeignKey("vowels.id"), nullable=False)

    def to_dict(self):
        return {
            "word": self.word,
            "audio_url": self.audio_url,
            "ipa": self.ipa,
            "example_sentence": self.example_sentence
        }

    def __repr__(self):
        return f"<WordExample word='{self.word}' vowel_id='{self.vowel_id}'>"

Quiz Models

QuizItem

Bases: Model

Database model representing a quiz question in the PhonoLab system.

Attributes:

Name Type Description
id int

Unique identifier for the quiz item.
prompt_word str

The word presented as the quiz question.
prompt_audio_url str

URL to the audio file of the prompt word.
prompt_ipa str

IPA transcription of the prompt word.
feedback_correct str

Feedback for correct answers.
feedback_incorrect str

Feedback for incorrect answers.
vowel_id str

Foreign key to the associated vowel.
Relationships

vowel: Many-to-one relationship with the Vowel model. options: One-to-many relationship with QuizOption model.

Source code in src/models/quiz.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
class QuizItem(db.Model):
    """
    Database model representing a quiz question in the PhonoLab system.

    Attributes:
        id (int): Unique identifier for the quiz item.
        prompt_word (str): The word presented as the quiz question.
        prompt_audio_url (str): URL to the audio file of the prompt word.
        prompt_ipa (str): IPA transcription of the prompt word.
        feedback_correct (str): Feedback for correct answers.
        feedback_incorrect (str): Feedback for incorrect answers.
        vowel_id (str): Foreign key to the associated vowel.

    Relationships:
        vowel: Many-to-one relationship with the Vowel model.
        options: One-to-many relationship with QuizOption model.
    """
    __tablename__ = "quiz_items"

    id = db.Column(db.Integer, primary_key=True)
    prompt_word = db.Column(db.String, nullable=False)
    prompt_audio_url = db.Column(db.String, nullable=False)
    prompt_ipa = db.Column(db.String, nullable=False)

    # NEW FIELDS for feedback messages
    feedback_correct = db.Column(db.String, nullable=True)
    feedback_incorrect = db.Column(db.String, nullable=True)

    vowel_id = db.Column(db.String, db.ForeignKey("vowels.id"), nullable=True)
    vowel = db.relationship("Vowel", backref="quizzes")

    options = db.relationship("QuizOption", backref="quiz_item", cascade="all, delete-orphan", lazy=True)

    def to_dict(self):
        return {
            "id": self.id,
            "prompt_word": self.prompt_word,
            "prompt_ipa": self.prompt_ipa,
            "prompt_audio_url": self.prompt_audio_url,
            "feedback_correct": self.feedback_correct,
            "feedback_incorrect": self.feedback_incorrect,
            "options": [opt.to_dict() for opt in self.options],
        }

    def __repr__(self):
        return f"<QuizItem {self.prompt_word} ({self.prompt_ipa})>"

QuizOption

Bases: Model

Database model representing an answer option for a quiz question.

Attributes:

Name Type Description
id int

Unique identifier for the quiz option.
word str

The word presented as an answer option.
ipa str

IPA transcription of the option word.
audio_url str

URL to the audio file of the option word.
is_correct bool

Whether this option is the correct answer.
language str

Language identifier for the word.
quiz_item_id int

Foreign key to the associated quiz item.
Relationships

quiz_item: Many-to-one relationship with the QuizItem model.

Source code in src/models/quiz.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class QuizOption(db.Model):
    """
    Database model representing an answer option for a quiz question.

    Attributes:
        id (int): Unique identifier for the quiz option.
        word (str): The word presented as an answer option.
        ipa (str): IPA transcription of the option word.
        audio_url (str): URL to the audio file of the option word.
        is_correct (bool): Whether this option is the correct answer.
        language (str): Language identifier for the word.
        quiz_item_id (int): Foreign key to the associated quiz item.

    Relationships:
        quiz_item: Many-to-one relationship with the QuizItem model.
    """
    __tablename__ = "quiz_options"

    id = db.Column(db.Integer, primary_key=True)
    word = db.Column(db.String, nullable=False)
    ipa = db.Column(db.String, nullable=False)
    audio_url = db.Column(db.String, nullable=False)
    is_correct = db.Column(db.Boolean, default=False)
    language = db.Column(db.String, nullable=True)

    quiz_item_id = db.Column(db.Integer, db.ForeignKey("quiz_items.id"), nullable=False)

    def to_dict(self):
        return {
            "id": self.id,
            "word": self.word,
            "ipa": self.ipa,
            "audio_url": self.audio_url,
            "is_correct": self.is_correct,
            "language": self.language
        }

    def __repr__(self):
        return f"<QuizOption word='{self.word}' ipa='{self.ipa}' lang='{self.language}' correct={self.is_correct}>"

Lesson Model

Lesson

Bases: Model

Database model representing a lesson on a specific vowel phoneme.

Attributes:

Name Type Description
id int

Unique identifier for the lesson.
vowel_id str

Foreign key to the associated vowel.
Relationships

vowel: One-to-one relationship with the Vowel model.

Source code in src/models/lesson.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class Lesson(db.Model):
    """
    Database model representing a lesson on a specific vowel phoneme.

    Attributes:
        id (int): Unique identifier for the lesson.
        vowel_id (str): Foreign key to the associated vowel.

    Relationships:
        vowel: One-to-one relationship with the Vowel model.
    """
    __tablename__ = "lessons"

    id = db.Column(db.Integer, primary_key=True)
    vowel_id = db.Column(db.String, db.ForeignKey("vowels.id"), nullable=False, unique=True)

    vowel = db.relationship("Vowel", backref=db.backref("lesson", uselist=False, cascade="all, delete-orphan"))

    def to_dict(self):
        # lesson card
        lesson_card = {}
        if self.vowel:
            lesson_card = {
                "pronounced": self.vowel.pronounced,
                "common_spellings": self.vowel.common_spellings,
                "lips": self.vowel.lips,
                "tongue": self.vowel.tongue,
                "example_words": self.vowel.example_words
            }

        # filtered vowel
        vowel_dict = None
        if self.vowel:
            vowel_dict = {
                "id": self.vowel.id,
                "phoneme": self.vowel.phoneme,
                "name": self.vowel.name,
                "ipa_example": self.vowel.ipa_example,
                "color_code": self.vowel.color_code,
                "audio_url": self.vowel.audio_url,
                "description": self.vowel.description,
                "mouth_image_url": self.vowel.mouth_image_url,
                # "word_examples": [we.to_dict() for we in self.vowel.word_examples]
            }

        return {
            "id": self.id,
            "vowel": vowel_dict,
            "lesson_card": lesson_card
        }

    def __repr__(self):
        return f"<Lesson id={self.id} vowel_id={self.vowel_id}>"