word-match

Context and purpose

word-match turns English vocabulary practice for Turkish speakers from a collection of random questions into a structured learning flow. Rather than asking users to choose from many modes, it offers one Study surface: the system selects the next appropriate topic, while the user can still change that topic deliberately.

The goal is not only to count correct answers. A persistent model tracks when each word should be revisited in each skill dimension. Sessions, answers, and mastery data are retained with the user account.

How it works

The curriculum is structured as level, ordered topic, active learning group, and ordered word. The Study home either resumes an active session or presents the next suitable topic. A topic session balances recognising meaning and recalling the same words in writing.

After an answer, the API records the outcome and updates mastery for the relevant word. Users can temporarily defer writing questions that are not suitable at that moment; a deferral is not treated as an answer. Completed or interrupted sessions remain available with detailed results.

System design

The ASP.NET Core API organises authentication, Study planning, question generation, word catalogues, and persistence as feature-focused areas. The React client keeps session state and API interactions in separate features. PostgreSQL persists users, curriculum records, sessions, question snapshots, and mastery data.

Content starts from a CSV source. Its stable ImportKey is separate from the database-generated identity, so the idempotent bootstrap command can update words and curriculum placement without unnecessarily resetting user progress.

Key technical decisions

Questions are planned when a Study session is created, and question and answer snapshots are retained. Later catalogue edits therefore cannot rewrite the history of an active session. For multiple-choice questions, distractors are drawn from the session first, then the same level, and finally a wider catalogue if needed.

Mastery is tracked across skill dimensions rather than as one generic score. Correct answers move the review time forward, while wrong or unknown outcomes schedule an earlier return for the relevant skill. The planner selects only ready words and keeps reinforcement sessions deliberately small.

Session writes, answer records, and progress updates share a data-integrity boundary. Identity cookies and XSRF protection safeguard authentication and state-changing requests.

Validation and limits

The API includes tests for Study planning, question generation, bootstrap behaviour, and endpoints. The client includes tests for sessions, authentication, and the vocabulary interface. Docker and nginx configuration support running the application behind a production-like network boundary.

The current product focus is the curriculum-based Study flow. Richer content types, advanced pronunciation assessment, and social or points systems are outside this core. Vocabulary quality depends on the source CSV; the application provides a consistent practice system rather than replacing a language teacher.