SolfyQuest: Turning Solfeggio Into a Learning Quest

Solfeggio often feels fragmented to a student.

One day they study notes on the staff. The next day they work on rhythm. Then come keys, intervals, dictations, theory, and another batch of exercises. A good teacher keeps the structure in their head: which topic comes next, where the student is struggling, what should be repeated, and why a particular exercise belongs in a lesson.

But once the student starts practicing at home, that structure can disappear very quickly.

SolfyQuest started as an attempt to turn solfeggio into a more connected, interactive learning system: lessons, theory, exercises, repetition, progress, game rewards, audio tasks, teacher scenarios, and local learning analytics all working together.

It is not just a "pick the right note" trainer. It is a cross-platform .NET MAUI application where music curriculum is described through a unified content format, and game mechanics are tied to real learning actions.

In this article, I want to walk through the project from a high level:

• what problem SolfyQuest is trying to solve;
• why curriculum unification matters;
• how playbooks help teachers create and share lessons;
• what game mechanics are used;
• why those mechanics are useful for learning;
• what technologies are used;
• how the architecture is structured.

Why SolfyQuest Exists

The main idea behind SolfyQuest is simple: turn solfeggio practice from a set of disconnected exercises into a guided journey through musical skills.

The project includes a map, lessons, theory pages, practical tasks, ear-training tasks, rhythm tasks, progress tracking, in-game currency, a shop, parent reports, teacher-facing features, and local analytics. But these are not decorative layers on top of a textbook. They are part of the learning process.

SolfyQuest is designed so that a student can:

• see a clear path from simple topics to more complex ones;
• understand why they are doing a particular exercise;
• return to a topic through practice, not only through theory text;
• receive quick feedback;
• see progress through XP, stars, and opened sections;
• stay motivated during repetitive training.

For a teacher, this changes the way learning content can be organized. A lesson is no longer just a page of explanation. It becomes a structure: topic, theory, tasks, checks, mistakes, repetition, and progress.

The Unification Problem

One of the most important challenges in a music-learning app is unification.

The same musical concept can appear in many different places. For example, C major can be:

• a lesson topic;
• a theory block;
• a scale;
• a task about scale degrees;
• an ear-training exercise;
• part of a final check;
• a prerequisite for unlocking a later section.

If all of this is described separately, the project quickly becomes hard to maintain. In one place, "C major" is a line of text. In another, it is a topic name. Somewhere else, it is a set of possible answers. In another place, it is part of validation logic.

In SolfyQuest, curriculum is described through a shared format: SolfyBook.

It is a JSON-like content model that connects the main educational entities:

• Topics;
• TheoryBlocks;
• Lessons;
• Tasks;
• TaskTypeRules;
• GradePlans.

This format solves several problems at once.

First, theory and practice stop living separately. A lesson can reference a theory block and a set of tasks. A task can be connected to a topic, grade, type, audio notes, notation, and expected answer.

Second, the app can import, validate, and version content packs. The project uses .solfybook files: the built-in official first-grade package lives in Resources/Raw, while custom or editor-created packs can be installed separately.

Third, the architecture becomes extensible. To add new learning material, we do not have to rewrite the lesson screen. We can describe a playbook, validate it, and map it into runtime models such as LessonDefinition and TaskDefinition.

Playbooks as a Teacher Tool

The playbook approach is important not only from an engineering point of view.

It also creates a convenient path for teachers to add their own lessons. A teacher could create a playbook for a specific curriculum, class, age group, school program, or teaching method.

One teacher might create a rhythm review pack. Another might create interval exercises. Another might build a custom path through keys and scales for a particular group of students.

The natural next step is sharing playbooks between teachers. That would allow SolfyQuest to grow beyond a built-in course and become a platform for exchanging tested educational materials.

In other words, .solfybook is not just a file format. It can become the foundation for a teacher-authored curriculum ecosystem.

Game Mechanics: Not Decoration, but a Learning Loop

Gamification in educational apps is often reduced to points and badges.

In SolfyQuest, the goal is different: game mechanics are connected to the learning loop itself. They help the student move through the curriculum, repeat material, recover from mistakes, and keep practicing long enough for musical skills to become stable.

As the musical material becomes more complex, the game practices also need to become richer. Early lessons can rely on simple cycles: choose, repeat, assemble a sequence, move through the map. But once the curriculum introduces intervals, keys, two-voice exercises, dictations, and more advanced ear training, the game layer also needs more complex patterns: memory tasks, error search, guided challenges, combined tasks, and boss-style reviews.

Game Mechanics Used in SolfyQuest

SolfyQuest already uses several categories of game mechanics.

1. Progression Map

The main route is presented as the City of Sounds. The student opens sections, completes lessons, returns to the map, and sees how separate topics become part of a larger journey.

This is a progression-map mechanic. From a UX point of view, it helps the student understand where they are. From a pedagogical point of view, it groups topics into meaningful blocks.

2. Stars, XP, and Lesson Scores

After a lesson, the app calculates the result: correct answers, total tasks, stars, and score.

Stars are not just decorative. In ProgressService, they are based on the ratio of correct answers:

• 3 stars for a perfect result;
• 2 stars for a strong result;
• 1 star for partial mastery;
• 0 stars when the material needs more practice.

This encourages the student to improve, not just to tap through the lesson once.

3. In-Game Currency and Shop

Successful lessons reward the student with "notes", which work as in-game currency. Those notes can be spent in the shop on cosmetic items.

The key design point is that the shop does not replace learning. It supports learning by giving students a long-term reward loop.

4. Short Interactive Tasks

These are fast learning loops:

• note choice;
• staff reading;
• dragging notes to the staff;
• rhythm tapping;
• sequence assembly;
• rhythm building;
• ear-choice tasks;
• free-answer tasks.

They follow a compact cycle: see or hear the prompt, answer, receive feedback, continue.

5. Sorting and Classification

Some tasks focus on classification. In the playbook model, this includes task types such as:

• sort_bins;
• suitcase_sort;
• swipe_sort;
• odd_one_out;
• match_pairs.

These are useful when the student needs to distinguish groups: note durations, meters, accidentals, stable and unstable degrees, or similar musical concepts.

6. Memory and Attention

SolfyQuest also uses memory-oriented mechanics:

• memory_flash;
• memory_pairs;
• sample_copy;
• card_tape;
• note_hideout.

These tasks train not just recognition, but retention: the order of notes, a short audio fragment, a visual pattern, or a musical sequence.

7. Routes and Sequences

Some mechanics turn musical material into a path:

• snake_path;
• maze_path;
• music_puzzle;
• tower_build;
• rhythm_train;
• guided_dictation.

These patterns are especially useful for scales, scale degrees, intervals, rhythmic formulas, and guided dictations.

8. Error Search and Correction

Music learning is not only about choosing the right answer. Sometimes the student needs to find what is wrong.

SolfyQuest uses task types such as:

• find_mistake;
• fix_teacher;
• yes_no_blitz.

These mechanics ask the student to verify a statement, detect a mismatch, or correct an intentionally wrong example.

9. Boss Challenges and Final Checks

Finally, SolfyQuest uses boss-style and review mechanics such as boss_challenge and final check lessons.

This matters because musical skills rarely exist in isolation. Rhythm, notation, hearing, theory, and memory constantly interact. A final challenge can combine several skills in one task flow.

Why This Helps Learning

Solfeggio requires repetition.

You cannot read about intervals once and immediately hear them reliably. You need many small attempts: listen, answer, make a mistake, compare, try again.

The game structure helps make this cycle easier to sustain.

The map gives direction. Stars show mastery. XP and rewards support short-term motivation. The shop gives a longer-term reward loop. Mistake tracking helps the app preserve information about weak areas instead of only saying "wrong".

The project already has LearningAnalyticsService, which records mistakes with:

• lesson id;
• lesson title;
• topic;
• task prompt;
• expected answer;
• actual answer.

From that data, the app can build weak-topic reports and eventually drive adaptive repetition.

The next step is deeper analysis: not only incorrect answers, but also correct answers, trends over time, task types, difficulty, repetition intervals, and stability of results.

This is where statistics and mathematical analysis become useful:

• error frequency;
• answer trends;
• number of attempts;
• stability of mastery;
• topics that were technically passed but not really learned.

Based on this, SolfyQuest could suggest repeated topics and lessons according to the student's real learning profile.

AI analysis might also become useful later, but I would approach it carefully. First, we need reliable transparent analytics. Then AI can help summarize patterns, explain weak topics, or suggest teacher-friendly recommendations.

Tech Stack

SolfyQuest is built as a cross-platform .NET MAUI application.

The current project uses:

• .NET MAUI and Microsoft.Maui.Controls for UI;
• C# with nullable reference types;
• XAML pages for main screens;
• sqlite-net-pcl and SQLitePCLRaw.bundle_green for local storage;
• MAUI Resources for images, SVG files, fonts, and raw audio;
• platform-specific branches for Android, iOS, MacCatalyst, and Windows;
• offline mode by default, with an optional API backend.

The project targets Android, iOS, MacCatalyst, and Windows. For a music-learning app, this makes sense: students should be able to practice on their own device, launch the app quickly, and continue learning without a constant network connection.

MAUI also gives us a shared codebase for UI, local state, resources, navigation, and platform-specific behavior.

Audio is a good example. The AudioEngineService can use different implementations depending on the platform:

• on Windows, simple tones can be played with Console.Beep;
• on Android, the app can generate MIDI-like playback and use MediaPlayer;
• on other platforms, it can fall back to haptics and timed delays.

Offline-First Architecture

By default, the app runs in offline mode:

{
  "BackendMode": "Offline",
  "Api": {
    "BaseUrl": "https://dev-api.solfyquest.com"
  }
}

This is important for an educational app. A student should be able to practice without network access. Progress, mistakes, purchases, profile data, and installed playbooks are stored locally in SQLite.

At the same time, the architecture does not block future server synchronization.

The project has:

• IBackendClient;
• OfflineBackendClient;
• ApiBackendClient;
• BackendHub;
• SyncQueueService.

When something important happens locally, the app puts an event into the sync queue:

• profile save;
• lesson completion;
• playbook installation;
• shop purchase;
• student mistake recording.

If the backend is available, the queue sends events through the API. If not, the data remains local.

That gives the project a useful early-stage compromise: the app is already valuable without a server, but the architecture is ready for synchronization.

High-Level Architecture

At a high level, SolfyQuest can be split into several layers.

UI Layer

The UI lives in Views: start page, login, registration, quest map, theory, tasks, results, profile, shop, settings, parent reports, teacher dashboard, content editor, and notation editor.

The main student flow goes through:

• QuestMapPage;
• TheoryPage;
• TaskPage;
• ResultPage.

Content Domain

Content is described in PlaybookModels:

• SolfyBook;
• SolfyLesson;
• SolfyTask;
• SolfyTheoryBlock;
• SolfyTopic;
• SolfyAnswer;
• SolfyNotation.

Then PlaybookService validates a book, installs it into local storage, and maps it into runtime lessons. ContentService exposes those lessons to the app and can reorder them based on the student's goal.

This separation is important: the authoring model and the runtime display model are related, but not completely mixed together.

Game Progress

ProgressService manages user stats, stars, XP, currency, streaks, and completed lessons. Data is stored locally in UserStats and LocalUserLevel.

ShopService handles shop items and active cosmetics.

Audio

AudioEngineService plays notes, pauses, note sequences, and instrument samples.

This is intentionally separate from the task UI. A task should say: "play these notes". The audio service decides how to do that on the current platform.

Analytics and Teacher Layer

LearningAnalyticsService records mistakes and can collect weak topics. TeacherService and TeacherDashboardPage create the foundation for teacher scenarios: assignments, classes, students, and reports.

This moves SolfyQuest beyond a personal trainer and toward a tool that can support an actual learning process.

Local Database and Sync

LocalDatabase creates the local SQLite database and tables for:

• users;
• progress;
• pending sync events;
• shop items;
• drafts;
• reminders;
• notifications;
• mistakes;
• teacher entities;
• installed playbooks.

SyncQueueService adds offline-first behavior. The app does not need to send data immediately, but it does not lose events that should be synchronized later.

Two Product Directions

One interesting product question is whether SolfyQuest should evolve into two related surfaces.

The first direction is a game-first app: better graphics, richer UI, stronger visual storytelling, more expressive locations, and more polished reward loops. This would focus on independent learners and motivation.

The second direction is a learning platform: communication between teachers and students, assignments, reports, class management, shared playbooks, and teacher-authored curriculum packs.

I would not split the architecture too early. The better approach is to keep a shared learning core:

• playbooks;
• tasks;
• progress;
• audio;
• analytics;
• sync.

Then different product surfaces can grow on top of that core.

What Comes Next

SolfyQuest sits at the intersection of pedagogy, game design, and software architecture.

From the learning side, the goal is to unify solfeggio: topics, theory, lessons, tasks, mistakes, and repetition should work as one system.

From the game-design side, the app uses maps, stars, XP, currency, rewards, memory tasks, sorting, routes, correction tasks, and boss challenges to make repetition more natural.

From the technical side, the project is built around .NET MAUI, SQLite, offline-first architecture, playbook-based content, a separate audio layer, and a service-oriented app model.

*Future articles in this series *:

1. how the .solfybook format works;
2. how to design musical task types;
3. how to build an audio layer for a solfeggio trainer;
4. how to store progress and mistakes for adaptive repetition;
5. how to develop teacher dashboard scenarios;
6. how to analyze correct and incorrect answers statistically;
7. where AI analysis might be useful;
8. how to expand game mechanics as the curriculum becomes more complex;
9. whether SolfyQuest should become a more polished game-first app;
10. how the project could become a teacher-student learning platform.

The first version of SolfyQuest already shows the main idea: if we want to make music learning interactive, it is not enough to move a textbook onto a screen. We need a system where theory, practice, sound, progress, and motivation speak the same language.