nihonbuzz-academy/BLUEPRINT.md

Nihonbuzz Academy - Master Blueprint

1. Project Vision

To create a premier Japanese language learning platform that combines Spaced Repetition System (SRS), structured lessons, and gamification to help students master Japanese efficiently. The platform focuses on long-term retention through smart algorithms and engaging UI.

2. Core Architecture

• Backend: Laravel 11 (PHP 8.2+)
• Frontend: React + TypeScript (via Inertia.js)
• UI Framework: TailwindCSS + Shadcn/UI
• Database: MySQL/MariaDB
• Authentication: Laravel Breeze + Socialite (Google OAuth)

3. Feature Roadmap

Phase 1: Foundation (Current Focus)

• Authentication & Identity:
  • Complete Google OAuth integration.
  • Setup Role-Based Access Control (RBAC): Student, Instructor, Admin.
  • Profile management (Avatar, Timezone settings for SRS).
• Basic UI Layout:
  • Responsive Application Shell (Sidebar/Navbar).
  • Dark/Light mode support.

Phase 2: The SRS Engine (Core Value)

• Content Database:
  • vocabularies table: Kanji, Kana, Meaning, Audio, Example Sentences, JLPT Level.
• SRS Algorithm Logic:
  • Implementation of SuperMemo-2 or Anki-like algorithm.
  • srs_reviews table: Tracks user_id, vocabulary_id, interval, ease_factor, next_review_at.
• Study Interface:
  • Flashcard UI (Front/Back).
  • Self-grading buttons (Again, Hard, Good, Easy).
  • Keyboard shortcuts for rapid reviewing.

Phase 3: Student Dashboard & Analytics

• Dashboard Widgets:
  • "Reviews Due" counter.
  • "New Cards" available.
  • Heatmap of study activity (like GitHub contributions).
  • SRS distribution chart (Learning vs. Mature cards).
• Study Stats:
  • Retention rate graphs.
  • Forecast of future reviews.

Phase 4: Gamification & Engagement

• Streak System: Daily login/study tracking.
• XP & Levels: Points for every correct card.
• Leaderboards: Weekly/Monthly rankings among friends/global.
• Badges: Achievements for milestones (e.g., "1000 Words Learned").

Phase 5: Administration & Content Management

• Admin Dashboard:
  • CRUD interface for Vocabulary/Kanji (Mass import via CSV/JSON).
  • User management.
• Audio System: Text-to-Speech integration or hosted audio files.

4. Technical Specifications

Database Schema Overview

• users: Core user data
• social_accounts: OAuth links
• vocabularies: Dictionary data (kanji, kana, meaning, example_sentence)
• srs_reviews: Tracks user progress per item (next_review_date, interval, ease_factor)
• study_sessions: Logs of review activity

vocabularies table structure

Column	Type	Notes
id	bigint	Primary Key
word	string	The Kanji/Word (e.g., 猫)
reading	string	Kana reading (e.g., ねこ)
meaning	text	English/Indonesian meaning
parts_of_speech	string	Noun, Verb, etc.
level	integer	JLPT Level (5, 4, 3, 2, 1)

srs_reviews table structure

Column	Type	Notes
id	bigint	Primary Key
user_id	bigint	FK to users
vocabulary_id	bigint	FK to vocabularies
interval	integer	Days until next review
ease_factor	float	Multiplier (default 2.5)
streak	integer	Consecutive correct answers
next_review_at	datetime	When this card becomes due