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.

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.