nihonbuzz-academy/README.md

# LPK Nihonbuzz Academy Ecosystem Blueprint 🇯🇵

Dokumen ini merupakan cetak biru (blueprint) teknis mutakhir untuk seluruh ekosistem digital **LPK Nihonbuzz**, yang dirancang sebagai platform pelatihan kerja terintegrasi, manajemen administrasi kantor (Buku Kantor), dan validasi sertifikasi kompetensi Bahasa Jepang.

---

## 1. High-Level Architecture

Eksosistem LPK Nihonbuzz terbagi menjadi dua entitas utama yang saling terintegrasi namun berjalan di infrastruktur yang dioptimalkan untuk kebutuhan masing-masing.

```mermaid
graph TD
    User((User/Student))
    
    subgraph "Public Interface (nihonbuzz-org)"
        NextJS["Next.js 16 (React)"]
        Tailwind["Tailwind CSS"]
        CF_Pages["Cloudflare Pages + OpenNext"]
    end
    
    subgraph "Learning Engine (nihonbuzz-academy)"
        Laravel["Laravel 12 (PHP 8.3+)"]
        Inertia["Inertia.js (React Protocol)"]
        Shadcn["Shadcn UI (Design System)"]
        Filament["Filament v5 (Jimusho Admin)"]
    end
    
    subgraph "Shared Infrastructure"
        MySQL[("MySQL (UUID Based)")]
        R2[("Cloudflare R2 (Media Storage)")]
        OAuth["Google OAuth 2.0"]
    end
    
    User --> NextJS
    User --> Laravel
    NextJS -.-> OAuth
    Laravel -.-> OAuth
    Laravel --> MySQL
    Laravel --> R2
```

---

## 2. Technical Stack Detail

### A. nihonbuzz-org (Marketing & Landing)
- **Framework**: Next.js 16.1.4.
- **Styling**: Tailwind CSS dengan standar Modern Japanese Aesthetics.
- **Infrastructure**: Cloudflare Pages menggunakan adapter **OpenNext** untuk mendukung fitur Server-Side Rendering (SSR) dan API Routes di lingkungan Serverless/Workers.

### B. nihonbuzz-academy (Core LMS)
- **Backend Core**: Laravel 12.
- **Frontend Bridge**: Inertia.js (menghilangkan kebutuhan API terpisah untuk web, menjaga state tetap sinkron).
- **UI Architecture**: Shadcn UI yang distandarisasi untuk mencapai kualitas premium dan konsistensi antara Dashboard Siswa dan Panel Manajemen.
- **Admin Identity**: Jalur kustom `/jimusho` menggunakan Filament v5 dengan plugin tema Shadcn.

---

## 3. Security & Access Model (RBAC)

Sistem keamanan menggunakan UUID global untuk seluruh entitas dan manajemen peran berbasis **Spatie Permission**.

```mermaid
graph LR
    subgraph "Management Level (Jimusho Accessibility)"
        SA[Super Admin] --> A[Admin]
        A --> B[Bendahara]
        A --> E[Editor]
        A --> S[Sensei]
    end
    
    subgraph "User Level"
        ST[Student] --> KK[Ketua Kelas]
        ST --> AL[Alumni]
    end
    
    OAuth((OAuth Integration)) --> ST
    SA -- "Full Access" --> Laravel
```

---

## 4. Database Schema Blueprint

Arsitektur database dirancang untuk mendukung "Data Atomik" guna kebutuhan pembelajaran bahasa yang dinamis.

```mermaid
erDiagram
    Users ||--o{ Enrollments : has
    Users ||--o{ SRSReviews : tracks
    Courses ||--o{ Modules : contains
    Modules ||--o{ Lessons : contains
    Levels ||--o{ Courses : categorizes
    Levels ||--o{ Vocabularies : categorizes
    Vocabularies ||--o{ SRSReviews : "review_data"
    
    Users {
        uuid id PK
        string name
        string email
        timestamp last_activity_at
    }
    
    Vocabularies {
        uuid id PK
        string word "Kanji/Kana"
        string reading "Kana only"
        string meaning_id "Indonesian"
        string meaning_en "English"
        string audio_url "Stored in R2"
        json stroke_order "SVG Logic"
    }

    SRSReviews {
        uuid id PK
        timestamp next_review_at
        int interval
        float ease_factor
    }
```

---

## 5. Learning Core Engine

### A. Japanese Support System
- **Furigana Engine**: Implementasi tag HTML `<ruby>` di seluruh komponen React untuk manajemen cara baca Kanji otomatis.
- **Multi-lingual Context**: Setiap data kosa kata wajib memiliki konteks makna dalam Bahasa Indonesia dan Inggris.
- **Media Delivery (Supercharged R2)**:
    - **Asset Proxy**: Gambar static (`/storage`) dilayani via Cloudflare Worker dengan cache agresif 7 hari (`cdn.academy.nihonbuzz.org`).
    - **Video Proxy**: Video materi dialirkan via Worker khusus (`video.cdn.academy.nihonbuzz.org`) yang menangani *Cross-Origin Resource Sharing* (CORS), *Range Requests*, dan *Dark Theme Error Pages*.
    - **Storage Separation**: Menggunakan dua bucket terpisah: `academy` (aset umum) dan `academy-video` (materi kursus) untuk isolasi performa.

### B. SRS (Spaced Repetition System)
- Menggunakan algoritma pengulangan berjarak (SM-2 based) untuk menghitung `next_review_at` secara individual bagi setiap siswa pada setiap unit kosa kata.
- Dashboard siswa menampilkan statistik "Ready to Review" yang diambil secara real-time dari mesin SRS.

---

## 6. Advanced Technical Systems

### A. Gamification Mechanics (Engagement Engine)
Sistem dirancang untuk mempertahankan retensi pengguna menggunakan tiga pilar utama:
- **XP Ecosystem**: Setiap penyelesaian pelajaran, kuis, atau sesi SRS memberikan unit XP yang meningkatkan level profil siswa.
- **Streak System**: Logika harian yang melacak aktivitas beruntun. Absensi aktivitas selama 24 jam akan mereset streak (disertai fitur *Streak Freeze* via shop/metadata).
- **Milestone Badges**: Pencapaian otomatis (misal: "N5 Master", "100 Days Warrior") yang disimpan dalam tabel metadata user.

### B. Media & Asset Pipeline
Pengelolaan aset media premium dilakukan secara otomatis menggunakan **Spatie MediaLibrary**:
- **Storage**: Integrasi native dengan **Cloudflare R2** via driver S3.
- **Processing**: Konversi otomatis format audio ke `.mp3` atau `.ogg` untuk kompatibilitas browser lintas perangkat.
- **Security**: Folder `private/pdfs` di R2 digunakan khusus untuk materi berbayar (Paid Content) yang hanya bisa diakses via *Signed URLs* dengan validitas waktu terbatas.

### C. Monetization & Enrollment Flow
Sistem mendukung pembelian kursus secara individual atau berbasis langganan:
- **Price Engine**: Mendukung mata uang IDR dengan format desimal yang dioptimalkan untuk gateway pembayaran lokal.
- **Access Control**: Relasi `enrollments` menentukan masa aktif akses siswa ke `modules` dan `lessons`. Kursus gratis (Free Preview) dapat diakses tanpa entri di tabel enrollment.

---

## 7. Future-Proof & Cross-Platform Strategy

Arsitektur dikembangkan dengan prinsip **API-Ready** untuk mendukung ekspansi ke aplikasi mobile asli (Bukan Capacitor):

- **Headless Compatibility**: Meskipun saat ini menggunakan Inertia.js untuk web, seluruh Controller didesain agar mudah di-porting menjadi REST API atau GraphQL untuk konsumsi **React Native**.
- **Shared Logic (The Brain)**: Algoritma SRS dan logika validasi kosa kata dipisahkan ke dalam *Service Classes* di Laravel agar bisa melayani permintaan dari Web (Inertia) maupun Mobile App (API) dengan kode sumber yang sama.
- **Universal Aesthetics**: Desain sistem Shadcn di Web menjadi referensi utama (tokens) untuk implementasi **NativeWind** di aplikasi mobile guna menjaga visual branding yang identik.

---

> **Blueprint Status**: Phase 2 Finalized (Comprehensive).
> **Objective**: Membangun ekosistem belajar Bahasa Jepang yang tak tertandingi secara teknis dan estetika.