libre-study/ROADMAP.md

Libre Study Roadmap

Libre Study is the study workspace that consumes LibreBible packages. The online experience is now the primary evolving product lane. The app should remain installable later, but current development should focus on getting the working interface online privately so Forrest can log in and use it from Christ Unscripted while local development continues on drive W:.

Current Code Baseline

• UI: React and TypeScript, served by Vite in browser development mode and wrapped by Tauri for desktop builds.
• Desktop shell: Tauri 2 with Rust commands and a local SQLite database at the app data path.
• Browser development data: static LibreBible JSON/JSONL packages loaded from a sibling libre-bible-data checkout.
• Current resource behavior: KJV and NET text, Strong's links, Strong's lexicon entries, KJV/NET footnotes and study notes, Matthew Henry Concise commentary, and Easton/Smith dictionary entries.
• Current user workspace behavior: browser sessions, settings, notes, exported session JSON, note drawer, and session timeline are stored in localStorage.
• Current gap: browser mode has the richest study-resource behavior, but it is not yet hosted, authenticated, or backed by server-side persistence.

Product Priority

Build the online experience first and let it keep evolving permanently. Desktop and mobile remain explicit future targets, but they should follow the online app after the study model, resource system, account model, and notes workflow are proven.

This does not require a permanent code fork right now. Prefer one shared app with a strong hosted-web lane and later desktop/mobile adapters. Create a separate Git branch only for normal development/release workflow reasons, not because the web app and desktop app are fundamentally different products yet.

Workflow Rule

Current active workflow note: while the app is being shaped interactively, use the local HotView/hot-reload setup as the primary test loop. Do not spend cycles on web builds, local builds, installer builds, or hosted deployment unless the user explicitly asks for a release/deploy pass. Hosted deployment remains a later/manual milestone, not the everyday development loop.

Keep the durable release workflow simple when it is time to publish:

1. Develop locally in W:\libre-study and W:\libre-bible-data.
2. Commit locally.
3. Push to Christ Unscripted Gitea.
4. Deploy the pushed state to the live/private web app.
5. Keep the hosted online app as the main evolving surface.
6. Later, build signed desktop installers only from clean pushed release commits.

The online app should reflect pushed work, not random uncommitted local state.

Architecture Rule

Keep one application, not separate apps. Split the code by adapters:

• Shared core: resource catalog reading, Bible page model, search model, session model, note/timeline model, and study-resource rendering rules.
• Local browser adapter: fast Vite preview, static package loading, and localStorage during development.
• Hosted web adapter: server API, login session, remote persistence, stable public/static resource package URLs, and optional collaboration services.
• Desktop adapter: Tauri commands, local SQLite, local resource packages, offline cache, import/update manager, and no required account.

The hosted web version is the lead product lane and may add login and collaboration. The desktop version must remain usable without accounts when that lane resumes.

Phase Index

• Phase 1: Private hosted preview.
• Phase 2: Server persistence and login.
• Phase 3: Deploy from Gitea.
• Phase 4: Shared app core.
• Phase 5: Storage and search foundation.
• Phase 6: Notes, exports, and Nextcloud.
• Phase 7: Study resource depth: maps, audio Bible, pronunciation audio, commentaries, dictionaries, lexicons, cross-references, and study notes.
• Phase 8: Collaboration.
• Phase 9: Desktop hardening.
• Phase 10: Public web release.
• Phase 11: Mobile and future platforms.

Phase 1: Private Hosted Preview

Goal: get the current working app online privately on Christ Unscripted as fast as possible and establish the hosted app as the main development target.

Recommended first hostname: study.christunscripted.com.

Tasks:

• Choose and create the Cloudflare DNS record for the private hosted app.
• Add a production web build/deploy path for the Vite app.
• Serve the app behind HTTPS through the Christ Unscripted server.
• Point the hosted app at stable LibreBible package URLs instead of the local W:\libre-bible-data Vite @fs path.
• Keep the hosted version private or obscured until login exists.
• Document the deployment command and server path.

Definition of done:

• A pushed commit can be deployed to a real HTTPS URL.
• Forrest can open the hosted interface and see the same Bible study surface as local dev mode.

Phase 2: Server Persistence And Login

Goal: make the hosted app personally usable without relying on browser localStorage.

Current foundation note: hosted mode now has username/password login, signed cookie sessions, and per-user SQLite workspace persistence. Account creation is intentionally bootstrap/manual-only for the private alpha.

Tasks:

• Add a minimal server API for sessions, notes, settings, timelines, and active workspace state. Started in server/libre-study-server.mjs.
• Add a simple login path, starting with manually created accounts or invite-only access. Started with bootstrap-created users.
• Store only necessary account data: username or email, password hash, sessions, notes, settings, timeline events, created/updated timestamps.
• Move hosted sessions from localStorage to server persistence. Started through the authenticated workspace snapshot endpoint.
• Keep local browser preview and Tauri desktop able to run without accounts.
• Add basic backup expectations for the server-side user database.

Definition of done:

• Forrest can log in, create a study session, write notes, reload from another browser, and continue the same session.

Phase 3: Deploy From Gitea

Goal: make local changes flow predictably to the live app through Git.

Current foundation note: the hosted deploy script now verifies that both Libre Study and LibreBible data are clean and equal to origin/main before it builds or publishes, and records both deployed commit hashes in deploy metadata.

Tasks:

• Keep Christ Unscripted Gitea as the remote source of truth for deployable code.
• Add a deployment script that pulls or receives the pushed commit, installs/builds as needed, and publishes the web build. Started with a manual script that only deploys clean origin/main state.
• Record the deployed commit hash somewhere visible or inspectable. Started with deploy-info.json, including both app and LibreBible data commits.
• Decide whether deploys are manual first, then later automatic after push. Manual deploy remains the current private-alpha default.
• Keep LibreBible package generation/deployment separate from Libre Study app deployment, but make the app consume the deployed package catalog.

Definition of done:

• Local edit, commit, push, deploy produces a live web change with an identifiable commit hash.

Phase 4: Shared App Core

Goal: stop treating local preview, hosted web, and Tauri as separate code paths.

Current foundation note: src/studyDataClient.ts now defines the app-level resource/query contract, and src/studyClient.ts routes existing UI calls through browser and Tauri adapters. src/workspace.ts also defines workspace/auth client contracts so local HotView storage and hosted persistence share the same app-facing boundary. The browser adapter still owns the HotView JSON/JSONL package loading path, but the UI no longer needs to know which adapter is active.

Tasks:

• Extract a client/service interface for translations, pages, Strong's links, notes, commentaries, dictionaries, maps, audio, sessions, settings, and timelines. Started with StudyDataClient for resource/query behavior.
• Keep UI components pointed at that interface instead of hardcoding browser static paths or direct Tauri commands. Started for resource/query and workspace persistence calls.
• Define the session schema once: active translation, page anchor, selected verse, enabled resources, visual settings, notes, timeline, and exports.
• Add a migration path from localStorage sessions to hosted persistence and Tauri SQLite persistence.

Definition of done:

• The same UI can run against local browser preview, hosted web API, or Tauri SQLite adapters.

Phase 5: Storage And Search Foundation

Goal: make hundreds of thousands or millions of entries feel normal.

Current foundation note: Storage And Search Foundation.

Tasks:

• Keep SQLite for desktop and private/single-user workflows.
• Use server-side SQLite only for private alpha or low-concurrency hosted use.
• Plan Postgres or another server database before public multi-user accounts and collaboration.
• Add proper indexes for translation id, book/chapter/verse, Strong's number, lemma, resource id, place id, and attachment relationships.
• Add full-text search through SQLite FTS5 or a compatible indexed search layer.
• Avoid loading entire large resources into the browser when a chapter, page, verse, Strong's entry, or search result can be loaded on demand.
• Keep the UI pointed at shared query/search interfaces so JSON packages, Tauri SQLite, hosted SQLite, and future server search can be swapped without rewriting the reader.

Definition of done:

• Search, page loads, note loads, and Strong's lookups use indexed or sharded access instead of whole-library reloads.

Phase 6: Notes, Exports, And Nextcloud

Goal: make study work portable without making Nextcloud the primary database.

Tasks:

• Save notes as structured session data first.
• Add export formats: JSON session, Markdown notes, HTML notes, and later sermon/study document formats.
• Add Nextcloud integration through WebDAV as an optional sync/export target.
• Support one-way export first, then explicit import, then optional sync.
• Keep Nextcloud credentials out of public resource packages and out of desktop builds unless the user configures them locally.

Definition of done:

• A session's notes can be exported and optionally synced to a Nextcloud folder without breaking normal local or web persistence.

Phase 7: Study Resource Depth

Goal: continue turning the page into a complete study workspace.

Tasks:

• Add map support from LibreBible place/gazetteer packages.
• Show map availability when a visible verse mentions a known place.
• Add audio Bible support at chapter granularity first, then verse granularity when sources provide timestamps or verse files.
• Add pronunciation audio tied to English terms, Strong's numbers, lemmas, Greek, and Hebrew where licensing permits.
• Add more commentaries, dictionaries, lexicons, cross-references, and study-note packages.
• Keep every resource optional, collapsible, session-aware, and license-attributed.

Definition of done:

• The study margin can show relevant maps, audio controls, pronunciations, notes, dictionary entries, lexicons, and commentaries dynamically for the selected verse or page.

Phase 8: Collaboration

Goal: add shared Bible study without turning the basic app into a social network.

Tasks:

• Start with shareable read-only session exports or links.
• Add shared sessions with explicit owners and invited participants.
• Add collaborative notes before collaborative whiteboards.
• Record session timeline events per participant when timeline recording is enabled.
• Consider WebSockets and a conflict-safe document model only after single-user web persistence works.

Definition of done:

• Two logged-in users can study the same passage and contribute to a shared note surface without losing individual session state.

Phase 9: Desktop Hardening

Goal: bring the installable app up to the same capability as the online study surface after the hosted lane proves the model.

Tasks:

• Move desktop persistence from prototype imports to the shared session/resource schema.
• Add resource package install/update management.
• Add offline package support for translations, notes, commentaries, dictionaries, maps, and audio where storage size allows.
• Keep account features optional and web-only unless a user explicitly signs into a sync service.
• Package signed Windows installers from clean, pushed release commits.

Definition of done:

• The Windows app can run offline with installed resources and preserve sessions locally.

Phase 10: Public Web Release

Goal: open the hosted app responsibly after private use proves the model.

Tasks:

• Add public account creation only after private login and persistence are stable.
• Add password reset, rate limiting, backups, and basic abuse protection.
• Add clear privacy, terms, license, and attribution pages.
• Separate public resource data from private user notes and collaboration data.
• Add admin controls for disabling accounts and reviewing operational health.
• Add monitoring for failed logins, storage growth, and resource loading failures.

Definition of done:

• The hosted app can accept public users without guessing about data responsibility or resource licensing.

Phase 11: Mobile And Future Platforms

Goal: adapt only after the desktop/web study model is proven.

Tasks:

• Evaluate responsive web and PWA behavior first.
• Consider mobile Tauri or native shells only if the PWA is insufficient.
• Preserve the page-first study model while changing layout for smaller screens.

Definition of done:

• Mobile use is designed from the proven study workflow instead of forcing the desktop interface onto a phone.

Database Decision

SQLite remains appropriate for the desktop app and for private/single-user testing. Hundreds of thousands of rows are not a problem when tables are indexed and large resources are loaded by chapter, verse, Strong's number, or search query.

For a public multi-user website, use SQLite only for a private alpha or low-concurrency service. Plan for Postgres or another server database once accounts, collaboration, and public user data become real.