Vocamon

WordSoul — A web application for learning and reviewing English vocabulary with gamification (collecting pets, earning XP), incorporating scientific memory principles (spaced repetition + retrieval practice) for engaging and long-lasting learning.

Project Overview • Key Features • Architecture & Design Principles • Main Interface • Installation Requirements • How to Run the Project • Credits

---

Project Overview

Vocamon is a web application aimed at:

• Combining scientific memory principles (SRS — spaced repetition; retrieval practice) with gamification to boost learning motivation.
• Users learn through vocabulary sets, with each word progressing through a sequence of question types (Flashcard → Fill-in-Blank → MultipleChoice → Listening) and is considered mastered upon completing the sequence in a single session.
• The system includes a pet mechanism: collect, upgrade, and evolve pets using XP/AP to enhance user engagement.

---

Key Features

• 📚 Smart Learning & Review: SRS-based scheduling, automatic review calendar.
• 🔁 4 Question Types in a Session: Flashcard, Fill-in-Blank, MultipleChoice, Listening.
• 🧠 State Machine for Each Word: Words transition between states based on correct/incorrect answers.
• 🎮 Gamification: XP, pet collection and upgrades, reward animations.
• 🗂 Vocabulary Set Management: Create, edit, add/remove words, permissions (owned/public).
• 📊 Dashboard & Statistics: Proficiency charts, words due for review, learning progress.
• 🏆 Leaderboard: Player ranking based on points.
• 🔔 Realtime Notifications: SignalR for pushing event notifications (learning sessions, pet upgrades, etc.).
• 🔒 Authentication & Authorization: JWT-based authentication, Admin/User roles.

---

Architecture & Design Principles

• Architecture: Modular Monolith (modules by function: User, Vocabulary, LearningSession, Pet, Reward, Notification).
• Backend: ASP.NET Core (.NET 9 / .NET 8 compatible), Entity Framework Core (Code First), SQL Server.
• Frontend: React (Vite + TypeScript), TailwindCSS.
• Realtime: SignalR.
• Storage Media: Cloudinary (images / audio pronunciation).
• Patterns & Principles: Repository + Service, DTO, Dependency Injection, Unit of Work (DbContext), SOLID.

---

Main Interface

---

Installation Requirements

Before running the project, install:

• Node.js >= 18
• npm or yarn
• .NET SDK >= 8.0
• SQL Server

How To Use

From the command line:

# Clone this repository
$ git clone https://github.com/your-username/wordsoul

# Go into the repository
$ cd wordsoul

# Backend
$ cd wordsoulapi
$ dotnet restore
$ dotnet ef database update   # create database
$ dotnet run

# Frontend
$ cd wordsoul-app
$ npm install
$ npm run dev

Credit

The project was built with the following technologies and libraries:

• Backend: ASP.NET Core, Entity Framework Core, SQL Server, SignalR, Cloudinary
• Frontend: React, Vite, TypeScript, TailwindCSS
• Tools: Git, Visual Studio, VS Code