Random Sutta Reader

Created by Vijjo

A fast, focus-oriented reader for Early Buddhist Texts (EBT), designed for a seamless reading experience with robust offline capabilities. Data is sourced from SuttaCentral's Bilara project and Digital Pāḷi Dictionary (DPD).

🌟 Key Features

• Random Sutta: Instantly discover a random discourse from the Nikayas.
• SQLite Engine: Powered by wa-sqlite (SQLite compiled to WebAssembly) for high-performance searching and filtering in the browser.
• Smart PWA Offline:
  • Automatically caches core engine and UI.
  • Downloadable SQLite "DB Bundles" for 100% offline access to thousands of Suttas.
• Magic Navigation: Integrated Breadcrumbs, Table of Contents (TOC), and "Magic Nav" for seamless context awareness.
• Bilingual & Dictionary Support:
  • Parallel display of Pāli and English (Bhante Sujato's translation).
  • Integrated Pāḷi-English Dictionary (DPD) for instant word lookup.
• Cross-Platform: Available as a Web App (PWA), Android (Capacitor), and MacOS (Tauri) with deep-linking support (randomsutta://).
• Customization: Dark Mode, Sepia (Night Shift) mode, and adjustable font sizes.

🛠️ Tech Stack

• Frontend: Vanilla JS (ES6 Modules), CSS3, HTML5 (with custom Partial Compiler).
• Build Tool: Vite with Vite PWA.
• Database: SQLite (via wa-sqlite).
• Processing: Python 3.10+ for data ingestion and optimization.
• Native Wrappers: Capacitor (Android/iOS) and Tauri (MacOS).

🚀 Installation & Build Guide

1. Clone the repository

git clone https://github.com/vjjda/random-sutta.git
cd random-sutta

2. Environment Setup

We use direnv or manual virtual environment for Python tools.

# Install Node dependencies
npm install

# Setup Python environment & Git hooks
make setup

Note: Python dependencies are managed via pyproject.toml. The make setup command automatically installs all necessary packages using pip-tools.

If you add new imports to the code, you can update the dependency list automatically:

make requirements

3. Fetch & Process Data

The project requires raw data (Bilara texts, SC API metadata, and DPD dictionary). This step is essential for the first-time setup.

# 1. Sync ALL data sources from SuttaCentral & DPD (takes time)
make sync

# 2. Process Sutta JSON into optimized SQLite databases
make data

# 3. Build & Export Dictionary (Mini)
# This command builds the 'Mini' version of DPD and exports it to web assets.
# Note: ONLY the 'Mini' version is used for the web/mobile app to keep bundle size lean.
make de

Dictionary Versions:

• make de: (Standard) Builds and exports the Mini dictionary to the web application.
• make dt / make df: Builds Tiny or Full versions (Primarily for reference or local testing).
• make da: Builds all versions sequentially.

4. Development & Build

# Start Vite Dev Server (HMR)
make dev

# Full Production Build (Web)
make build

# Build Android APK
make apk

# Build iOS (IPA for AltStore)
make altstore
# See [iOS Installation Guide](docs/ios_installation.md) for details.

# Build MacOS App
make app

📂 Project Structure

• src/: Python source code (Build Tools).
  • data_fetcher/: Synchronizes raw data from Bilara & API.
  • sutta_processor/: Core logic to convert JSON -> SQLite Databases.
  • dict_builder/: Builds Digital Pāḷi Dictionary assets.
  • release_system/: Handles versioning and GitHub releases.
• web/: Frontend Application.
  • assets/modules/: Modularized JS logic (core, ui, services).
  • assets/libs/: Third-party libraries like wa-sqlite.
  • public/assets/db/: Generated SQLite databases (Ignored by Git).
  • partials/: HTML components used by the internal compiler.
• android/: Capacitor Android project.
• src-tauri/: Tauri MacOS/Desktop project.

🐞 Development & Debugging

Append ?debug=1 to the URL to enable verbose logging and performance metrics in the browser console.

Example: http://localhost:8000/?q=mn1&debug=1

• ⏱️ Render: UI rendering performance.
• 📥 Data Fetch: Cache vs. Network latency.
• [DEBUG]: Internal state transitions and repository queries.

📄 License

• Content: SuttaCentral (CC0), DPD (CC BY-NC-SA 4.0).
• Source Code: MIT License.