NihonBuzz Ecosystem Blueprint 🇯🇵

Dokumen ini merupakan cetak biru (blueprint) teknis mutakhir untuk seluruh ekosistem NihonBuzz, mencakup arsitektur sistem, infrastruktur, dan model data yang telah dikonsolidasikan.

---

1. High-Level Architecture

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

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.

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.

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: Seluruh aset audio (pronunciation) dan video materi dialirkan (streaming) melalui Cloudflare R2 untuk latensi rendah.

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.