# 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 |