📚 Nala Pustaka

AI untuk Demokratisasi Kearifan Naskah Kuno Jawa

Aplikasi web interaktif yang menggunakan AI (Google Gemini) dengan metodologi RAG (Retrieval-Augmented Generation) untuk membantu pengguna mengeksplorasi dan memahami naskah kuno Jawa. Dilengkapi dengan Admin Panel untuk manajemen naskah, Knowledge Graph untuk visualisasi konsep, dan dukungan Multi-bahasa.

🎯 Untuk Kiro IDE: Repository ini sudah fully compatible! Lihat QUICK_START.md untuk setup 2 menit. Semua config files sudah ada: jsconfig.json, ESLint, Prettier, Tailwind intellisense, dan debug config. ✅

🚀 Live Demo: nalapustaka.org

• ✅ Multi-Language Support (i18n): Dukungan penuh Bahasa Indonesia (ID) dan English (EN) di seluruh aplikasi.
• ✅ Gemini 2.5 Flash Lite: Upgrade model AI ke versi terbaru yang lebih cepat, hemat biaya, dan akurat.
• ✅ Advanced Catalog: Filter canggih dengan Multi-select Tags, Kategori (10+ jenis), dan Sorting (A-Z, Z-A, Terbaru, Terlama).
• ✅ Articles Section: Halaman wawasan mendalam tentang teknologi dan filologi ("Digital Silence", "Philology Revolution").

• ✅ Massive Scraper: Otomatis scrape 4,500+ naskah dari sastra.org
• ✅ Intelligent Clustering: Mengelompokkan 2,200+ naskah menjadi ~500 cluster bermakna
• ✅ Auto-Description: LLM membuat deskripsi otomatis untuk setiap cluster naskah
• ✅ Vector Ingestion: Pipeline otomatis ke Pinecone & Supabase

• ✅ Deep Chat Optimization: 77% hemat token dengan semantic chunking & caching
• ✅ Multi-Chat Optimization: 40% hemat context window
• ✅ Usage Tracking: Monitor penggunaan token & biaya per user
• ✅ Rate Limiting: Proteksi API dengan tiered limits (Free/Premium)
• ✅ Performance: Response time lebih cepat dengan caching

• ✅ Migrasi dari Supabase ke PostgreSQL: Hemat biaya, full control!
• ✅ Self-hosted Database: PostgreSQL lokal atau Docker
• ✅ Educational Content Table: Store AI-generated educational content
• ✅ Manuscript Relationships: Store knowledge graph relationships
• ✅ Zero Cloud Costs: Tidak perlu bayar Supabase Pro lagi!

📖 Migration Guide: Lihat POSTGRESQL_SETUP.md untuk setup dan MIGRATION_SUMMARY.md untuk detail migrasi.

Nala Pustaka menyediakan 5 mode eksplorasi canggih untuk kebutuhan berbeda:

• Diskusi mendalam dengan satu naskah spesifik.
• Context-Aware: AI memahami konteks penuh naskah yang sedang dibuka.
• History: Menyimpan riwayat percakapan per naskah.

• Tanyakan apa saja dan AI akan mencari jawaban dari seluruh database naskah.
• Cocok untuk mencari tema umum, pola sejarah, atau konsep yang tersebar di banyak karya.
• Menampilkan sumber referensi dengan tingkat relevansi.

• Pilih 2-3 naskah sekaligus untuk dianalisis bersamaan.
• Bandingkan versi cerita, gaya bahasa, atau perspektif antar naskah.
• Mode seleksi intuitif di sidebar kiri.

• Auto-Summary: Ringkasan isi naskah yang mudah dipahami.
• Kearifan Lokal: Ekstraksi nilai-nilai moral dan relevansinya dengan masa kini.
• Analisis Tokoh: Daftar tokoh dan peran mereka dalam cerita.
• Signifikansi: Penjelasan mengapa naskah ini penting.
• Kuis Interaktif: Uji pemahaman Anda dengan kuis pilihan ganda yang digenerate AI.

• Visualisasi interaktif hubungan antar konsep (Tokoh, Karya, Konsep, Struktur).
• Menggunakan D3.js untuk visualisasi yang dinamis (drag, zoom, pan).

• Smart Search: Pencarian real-time judul dan pengarang.
• Advanced Filtering: Filter berdasarkan Kategori (Sejarah, Sastra, Agama, dll) dan Tags.
• Quality Filter: Filter naskah berdasarkan kelengkapan konten (Lengkap 🟢, Cukup 🟡, Pendek 🟠).
• Pinning System: Menandai naskah unggulan agar selalu muncul di atas.
• Pagination & Sorting: Navigasi mudah untuk ribuan koleksi.
• Source Links: Tautan langsung ke sumber asli naskah digital.

• Bagian khusus yang membahas interseksi antara teknologi AI dan pelestarian budaya.
• Artikel mendalam seperti "Mengatasi Kebisuan Digital" dan "Revolusi Filologi".

• CRUD Operations: Manajemen naskah visual tanpa coding.
• Massive Ingestion: Pipeline otomatis untuk scraping dan clustering ribuan naskah.
• Vector Database: Integrasi Pinecone untuk pencarian semantik yang akurat.
• Supabase Integration: Database PostgreSQL yang aman dan scalable.

• Token Optimization: Hemat 77% token dengan semantic chunking & caching.
• Rate Limiting: Proteksi API berjenjang (Free/Premium).
• Usage Tracking: Monitoring penggunaan token dan biaya per user.

• Node.js 18+
• npm atau yarn
• Google Gemini API Key (gratis)
• Supabase Account (gratis)

1. Clone repository

git clone <repository-url>
cd nala-pustaka

2. Install dependencies

npm install

3. Setup Environment Variables

   • Copy file .env.example menjadi .env.local:

   cp .env.example .env.local

   • Edit file .env.local dan isi dengan credentials Anda:

   # Google Gemini API Key
   # Dapatkan di: https://aistudio.google.com/app/apikey
   VITE_GEMINI_API_KEY=your_gemini_api_key_here
   
   # Supabase Credentials
   # Dapatkan di: https://supabase.com → Project Settings → API
   VITE_SUPABASE_URL=https://your-project.supabase.co
   VITE_SUPABASE_ANON_KEY=your_anon_key_here

4. Setup Database (Opsional - untuk Admin Panel)

   • Buat project baru di Supabase
   • Jalankan migration SQL dari guide/PHASE1_DATABASE_MIGRATION.sql
   • Jalankan migration SQL dari guide/PIN_FEATURE_MIGRATION.sql
   • Lihat guide/SETUP_ADMIN_PANEL.md untuk panduan lengkap

5. Run development server

npm run dev

6. Buka aplikasi
   • Homepage: http://localhost:5173
   • Admin Panel: http://localhost:5173/admin

• Pilih Naskah: Klik naskah di sidebar kiri.
• Filter & Sort: Gunakan dropdown kategori, tags, dan sorting di halaman Katalog.
• Mode Chat: Klik tombol "💬 Chat" di panel kanan untuk diskusi mendalam.
• Mode Belajar: Klik tombol "🎓 Belajar" untuk ringkasan, analisis nilai, dan kuis.
• Mode Graph: Klik tombol "🔮 Graph" untuk visualisasi relasi.

• Klik tombol "🔍 Chat Semua Naskah" di bagian atas sidebar kiri.
• Ajukan pertanyaan umum seperti "Bagaimana konsep kepemimpinan dalam naskah Jawa?".
• AI akan mencari jawaban dari seluruh koleksi dan menyertakan sumbernya.

1. Klik tombol "💬 Pilih untuk Chat" di sidebar kiri.
2. Centang 2 sampai 3 naskah yang ingin dibandingkan.
3. Klik tombol hijau "💬 Chat dengan X Naskah" yang muncul.
4. Ajukan pertanyaan perbandingan, misal: "Apa perbedaan gaya bahasa kedua naskah ini?".

• Single Chat: "Apa pesan moral utama dalam Serat Wulangreh?"
• Global Chat: "Siapa tokoh Panji yang muncul di berbagai naskah?"
• Multi Chat: "Bandingkan watak tokoh utama di kedua cerita ini."
• Edu Mode: "Buatkan kuis untuk menguji pemahaman saya tentang naskah ini."

User Query → Retrieval (manuscript.fullText) → Augmented Prompt → Gemini API → Grounded Response

1. Retrieval: Mengambil full text naskah sebagai konteks

2. Augmentation: Menggabungkan konteks + user query + system instruction

3. Generation: Gemini 2.5 Flash Lite menghasilkan jawaban grounded

Anda adalah "Nala Pustaka", Pustakawan AI ahli filologi Jawa.
- Jawab HANYA berdasarkan konteks naskah
- JANGAN berhalusinasi
- Beri sitasi dari naskah
- Gunakan Bahasa Indonesia (atau Inggris sesuai preferensi user)

Scraping (Python) → Raw Text → Clustering (Node.js) → LLM Analysis → Supabase & Pinecone

1. Scraping: Mengambil 4,500+ naskah dari sastra.org
2. Clustering: Menggunakan K-Means & Embeddings untuk mengelompokkan varian
3. Ingestion: Upload metadata ke Supabase dan vectors ke Pinecone

• Frontend: React 19 + Vite (Rolldown)
• Styling: Tailwind CSS 4
• Routing: React Router DOM 7
• Database: PostgreSQL 16 (self-hosted atau Docker)
• Vector DB: Pinecone
• Authentication: Supabase Auth (optional) atau custom auth
• AI Model: Google Gemini 2.5 Flash Lite
• Visualization: D3.js 7
• Internationalization: i18next
• Markdown: Marked.js
• Metodologi: RAG (Retrieval-Augmented Generation)
• Backend Scripts: Python (Scraping) & Node.js (Clustering)

nala-pustaka/
├── src/
│   ├── pages/
│   │   ├── AdminLogin.jsx      # Halaman login admin
│   │   ├── AdminDashboard.jsx  # Dashboard manajemen naskah
│   │   ├── CatalogPage.jsx     # Halaman katalog dengan filter canggih
│   │   └── articles/           # Halaman artikel/blog
│   ├── lib/
│   │   └── supabase.js         # Supabase client & services
│   ├── i18n/                   # Konfigurasi multi-bahasa
│   ├── data/
│   │   └── manuscripts.js      # Fallback data (hardcoded)
│   ├── App.jsx                 # Main app + komponen utama
│   ├── index.css               # Tailwind imports
│   └── main.jsx                # Entry point + routing
├── backend/                    # Backend services & scripts
│   ├── src/
│   │   ├── services/           # Deep Chat, Multi Chat, RAG
│   │   ├── middleware/         # Usage Tracker, Rate Limiter
│   │   └── scripts/            # Clustering & Ingestion pipelines
├── guide/                      # Dokumentasi lengkap
│   ├── CARA_PAKAI_ADMIN_PANEL.md
│   ├── MASSIVE_SCRAPING_GUIDE.md
│   ├── PANDUAN_CLUSTERING_FULL.md
│   └── ... (30+ guide files)
├── scraper_multi_kategori_all.py # Main scraping script
├── analyze_scraping_results.py   # Scraping analysis tool
├── public/                     # Static assets
├── .env.example                # Template environment variables
├── README.md                   # Dokumentasi ini
├── tailwind.config.js          # Tailwind configuration
├── vite.config.js              # Vite configuration
└── package.json                # Dependencies

• Cream: #fdf8f0 - Warna kertas kuno
• Stone: #292524 - Warna tinta tradisional
• Amber: #d97706 - Aksen emas kerajaan

• Font: System fonts (optimized for readability)
• Serif font untuk konten naskah

⚠️ PENTING untuk Production:

1. Jangan commit .env.local ke repository (sudah ada di .gitignore)
2. Gunakan environment variables untuk semua credentials:

   VITE_GEMINI_API_KEY=...
   VITE_SUPABASE_URL=...
   VITE_SUPABASE_ANON_KEY=...

3. Untuk deployment (Vercel/Netlify), set env vars di dashboard

• Row Level Security (RLS): Aktif di Supabase untuk proteksi data
• Authentication: Supabase Auth dengan email/password
• API Keys: Anon key aman untuk client-side (public access terbatas)
• Admin Access: Hanya authenticated users dapat CRUD naskah

Retrieval-Augmented Generation adalah teknik menggabungkan:

1. Retrieval: Mengambil informasi relevan dari database/dokumen
2. Augmentation: Menambahkan informasi tersebut ke prompt
3. Generation: Model AI menghasilkan jawaban berdasarkan informasi tersebut

✅ Jawaban akurat berdasarkan naskah asli dari database ✅ Mencegah halusinasi AI dengan strict system prompt ✅ Transparansi melalui sitasi otomatis ✅ Konservasi pengetahuan lokal ✅ Demokratisasi akses ke naskah kuno

• Context Window: AI ingat 5 percakapan terakhir
• Follow-up Questions: Dapat menjawab pertanyaan lanjutan dengan referensi ke jawaban sebelumnya
• Token Optimization: Manuscript text hanya dikirim di query pertama
• Chat History: Riwayat tersimpan otomatis di localStorage browser

• Markdown Rendering: Code blocks, tables, blockquotes, lists
• Syntax Highlighting: Dark theme untuk code blocks
• Typography: Spacing dan font optimized untuk readability
• Loading Indicator: Animated dots saat AI berpikir

{
  model: "gemini-2.5-flash-lite",
  temperature: 0.3,      // Rendah = lebih faktual
  topP: 0.8,
  topK: 40,
  maxOutputTokens: 1024
}

• First Query: ~35,000 tokens (full manuscript text)
• Follow-up Queries: ~500-1,000 tokens (5 message context only)
• Savings: 97% token reduction per follow-up
• Context Window: 1 Million tokens (support naskah 30K+ kata)
• Rate Limits: 10 requests/minute, 1500 requests/day (gratis)

• Setup project dengan React + Vite
• Design UI dengan Tailwind CSS
• Implementasi state management
• Integrasi Gemini API
• Implementasi RAG methodology
• Chat interface dengan auto-scroll
• Error handling
• Knowledge Graph visualization (D3.js)
• Mobile responsive design

• Database integration (Supabase)
• Admin Panel dengan authentication
• CRUD operations untuk naskah
• Author dropdown (Custom/Tidak Diketahui/Banyak Penulis)
• Manuscript ordering system (▲▼)
• Search functionality
• Source link feature

• Chat history & memory (localStorage)
• Conversational AI dengan context window
• Pagination (5 naskah per halaman)
• Enhanced AI formatting (Markdown)
• Pin feature (5 naskah unggulan)
• Sort & filter di admin panel

• Scraper otomatis untuk 4,500+ naskah
• Clustering engine untuk pengelompokan varian
• Auto-description dengan LLM
• Vector ingestion pipeline

• Deep Chat optimization (77% savings)
• Multi-Chat optimization (40% savings)
• Usage tracking & cost monitoring
• Rate limiting & API protection

• Global RAG Chat (Chat Semua Naskah)
• Multi-Manuscript Chat (Studi Banding 2-3 Naskah)
• Educational Mode (Ringkasan, Nilai, Tokoh, Kuis)
• Quality Filters (Lengkap/Cukup/Pendek)
• Deep Chat dengan Full Context Loading

• Multi-language support (Jawa, Indonesia, English)
• Upgrade to Gemini 2.5 Flash Lite
• Advanced Catalog Filtering (Tags, Categories)
• Articles & Insights Section

• Auto-generate Knowledge Graph dari database
• Export chat history (PDF/TXT)
• Share conversation via URL
• Audio narration (TTS)
• Mobile app (React Native)
• Collaborative features
• Advanced analytics dashboard

• QUICK_START.md - Setup 2 menit untuk development
• CHECKLIST.md - Pre-flight checklist sebelum coding

• guide/USER_GUIDE.md - Panduan untuk pengguna akhir
• guide/CARA_PAKAI_ADMIN_PANEL.md - Panduan admin panel (non-technical)

• guide/SETUP_ADMIN_PANEL.md - Setup admin panel & database
• guide/INTEGRASI_DATABASE.md - Integrasi Supabase
• SETUP_GUIDE_KIRO.md - Setup untuk Kiro IDE

• guide/PHASE_1_FEATURES.md - Author dropdown, ordering, search, source link
• guide/PHASE_2_FEATURES.md - Chat history, conversational AI, pagination
• guide/PIN_FEATURE_GUIDE.md - Pin naskah unggulan
• guide/SORT_FILTER_FEATURE.md - Sort & filter di admin

• guide/TECHNICAL_DOC.md - Dokumentasi teknis arsitektur
• guide/PANDUAN_DATASET.md - Panduan dataset & workflow
• guide/GEMINI_MODEL_RECOMMENDATIONS.md - AI model specs

• KIRO_TROUBLESHOOT.md - 10 masalah umum & solusi
• guide/README_API.md - Troubleshooting API

• guide/PROJECT_SUMMARY.md - Ringkasan project lengkap
• guide/CHANGELOG.md - Riwayat perubahan
• CHANGES_SUMMARY.md - Summary of Kiro IDE fixes
• LAPORAN_UPDATE_NOVEMBER_2025.txt - Laporan update terbaru

• README_MASSIVE_SCRAPER.md - Panduan scraping masif
• PANDUAN_CLUSTERING_FULL.md - Panduan clustering pipeline
• URGENT_OPTIMIZATIONS_IMPLEMENTED.md - Detail optimasi token & biaya

Kontribusi sangat diterima! Silakan:

1. Fork repository
2. Buat branch fitur (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push ke branch (git push origin feature/AmazingFeature)
5. Buat Pull Request

Project ini dibuat untuk tujuan edukasi dan konservasi budaya.

• Naskah: Terinspirasi dari koleksi sastra.org
• AI Model: Google Gemini
• Konsep: Demokratisasi dan konservasi naskah kuno Jawa

• Desktop: Daftar naskah di kiri, chat/graph di kanan
• Mobile: Responsive dengan scroll horizontal untuk naskah
• Search: Real-time filtering dengan result counter
• Pagination: 5 naskah per halaman dengan page navigation

• Dashboard: CRUD operations dengan sort, filter, search
• Pin Feature: Badge untuk naskah unggulan
• Ordering: Tombol ▲▼ untuk mengatur urutan
• Author Dropdown: Custom, Tidak Diketahui, Banyak Penulis

• Conversational: Follow-up questions dengan context
• History Modal: Lihat semua percakapan sebelumnya
• Enhanced Formatting: Markdown dengan code blocks, tables
• Loading State: Animated indicator

• D3.js Visualization: Force-directed graph
• Interactive: Drag, zoom, pan
• Color-coded: 4 node types dengan legend
• Directed Edges: Arrows dengan labels

1. Push ke GitHub

   git add .
   git commit -m "Ready for deployment"
   git push origin main

2. Import di Vercel

   • Buka vercel.com
   • Import repository dari GitHub
   • Framework Preset: Vite
   • Build Command: npm run build
   • Output Directory: dist

3. Set Environment Variables

   VITE_GEMINI_API_KEY=your_key
   VITE_SUPABASE_URL=your_url
   VITE_SUPABASE_ANON_KEY=your_key
   

4. Deploy

   • Klik Deploy
   • Website live di your-project.vercel.app

1. Build Settings

   • Build command: npm run build
   • Publish directory: dist

2. Environment Variables

   • Sama seperti Vercel (di Site settings → Environment variables)

3. Deploy

   • Drag & drop folder dist atau connect GitHub

# Development server (hot reload)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# Format code with Prettier
npm run format

• Components: Semua komponen utama di src/App.jsx
• Pages: Admin pages di src/pages/
• Services: Supabase client & services di src/lib/
• Data: Fallback data di src/data/
• Guides: Dokumentasi lengkap di guide/

Via Admin Panel (Recommended):

1. Login ke /admin
2. Klik "➕ Tambah Naskah Baru"
3. Isi form dan submit
4. Naskah langsung muncul di homepage

Via Database (Advanced):

1. Buka Supabase Dashboard → Table Editor
2. Insert row baru di table manuscripts
3. Isi: slug, title, author, description, full_text
4. Refresh homepage

Lihat guide/CARA_PAKAI_ADMIN_PANEL.md untuk detail.

• Lighthouse Score: 90+ (Performance, Accessibility, Best Practices, SEO)
• First Contentful Paint: < 1.5s
• Time to Interactive: < 3s
• Bundle Size: ~500KB (gzipped)

• Code Splitting: React Router lazy loading
• Tree Shaking: Vite automatic optimization
• Image Optimization: SVG icons (no raster images)
• CSS Purging: Tailwind removes unused styles
• Database Indexing: Supabase indexes untuk fast queries
• Token Optimization: 97% reduction untuk follow-up queries

Homepage:

• Naskah load dari database
• Search filtering works
• Pagination navigation works
• Pin badge muncul untuk naskah pinned
• Source button muncul jika ada source_url
• Mobile responsive

Chat AI:

• Welcome message muncul
• First query: AI jawab based on manuscript
• Follow-up query: AI reference jawaban sebelumnya
• Chat history tersimpan di localStorage
• History modal menampilkan semua pesan
• Clear history works
• Markdown formatting render dengan benar

Knowledge Graph:

• Graph render dengan D3.js
• Drag nodes works
• Zoom in/out works
• Pan canvas works
• Legend menampilkan node types
• Responsive di mobile

Admin Panel:

• Login dengan Supabase Auth
• Tambah naskah baru
• Edit naskah existing
• Hapus naskah (dengan konfirmasi)
• Pin/unpin naskah (max 5)
• Reorder dengan tombol ▲▼
• Sort & filter works
• Search real-time works

• Quick Start: QUICK_START.md
• User Guide: guide/USER_GUIDE.md
• Admin Guide: guide/CARA_PAKAI_ADMIN_PANEL.md
• Troubleshooting: KIRO_TROUBLESHOOT.md

• Buka GitHub Issues
• Sertakan: Browser, OS, error message, steps to reproduce

• Diskusi di GitHub Discussions
• Atau buat issue dengan label enhancement

• Website: nalapustaka.org
• GitHub: github.com/Alcunii/nala-pustaka

November 2025 Update:

• ✅ Phase 1-3: Core Features, Database, Admin Panel
• ✅ Phase 4: Massive Data Pipeline (4,500+ naskah)
• ✅ Phase 5: Optimization (77% cost reduction)
• ✅ Phase 6: Multi-Mode Exploration (Global Chat, Multi-Chat, Edu Mode)
• ✅ Phase 7: Global Reach (i18n, Gemini 2.5, Advanced Catalog)
• ✅ Total: 25+ fitur baru ditambahkan dalam satu bulan!

Total Features:

• 🎯 5 Mode Eksplorasi: Single Chat, Global Chat, Multi-Chat, Edu Mode, Graph
• 📚 Database: 4,500+ naskah terindeks dengan vector search
• 🤖 Advanced AI: Gemini 2.5 Flash Lite dengan Deep Context & RAG
• 📊 Visualisasi: Knowledge Graph interaktif dengan D3.js
• 🔐 Keamanan: Rate limiting, RLS, & Authentication
• 📱 Responsive: Mobile-first design dengan horizontal scroll
• 🕷️ Pipeline: Automated scraping & clustering
• 💰 Efisien: Caching & semantic chunking
• 📖 Lengkap: 30+ file dokumentasi teknis & user guide
• 🌍 Global: Dukungan Bahasa Indonesia & Inggris

Nala Pustaka - Membuka hati dan pikiran untuk belajar dari leluhur 🙏

Made with ❤️ for preserving Javanese cultural heritage

Version: 3.1.0 (November 2025) Status: 🚀 Production Ready Live: nalapustaka.org