255 lines
14 KiB
Markdown
255 lines
14 KiB
Markdown
# 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 Discipline
|
|
|
|
Work one phase at a time. A helper, spike, or supporting infrastructure task for a later area does not make that later phase active or half-complete. A phase is complete only when its definition of done is met in the active HotView workflow and the work is committed and pushed.
|
|
|
|
## Phase Index
|
|
|
|
- Phase 1: App foundation and Bible page reader. Complete.
|
|
- Phase 2: LibreBible resource consumption. Complete for the first local study workspace.
|
|
- Phase 3: HotView development loop and Gitea sync discipline. Complete.
|
|
- Phase 4: Shared app core. Complete.
|
|
- Phase 5: Storage and search foundation. Complete.
|
|
- Phase 6: Notes, exports, and optional sync.
|
|
- Phase 7: Study resource depth and polish.
|
|
|
|
Supporting infrastructure already landed but not currently active as a phase: hosted web preview, hosted login, and deploy scripting. These remain parked until the user explicitly asks for a release/deploy pass.
|
|
|
|
## Phase 1: App Foundation And Bible Page Reader
|
|
|
|
Status: complete.
|
|
|
|
Goal: establish a usable local Bible study app with a real page-reader surface.
|
|
|
|
Tasks:
|
|
|
|
- Scaffold the React/Vite/Tauri app.
|
|
- Build the Bible page reader, study margin, notes drawer, session controls, and page navigation.
|
|
- Keep the local HotView workflow usable for interactive testing.
|
|
|
|
Definition of done:
|
|
|
|
- The app opens locally and shows a usable Bible page reader with session-aware navigation and notes.
|
|
|
|
## Phase 2: LibreBible Resource Consumption
|
|
|
|
Status: complete for the first local study workspace.
|
|
|
|
Goal: consume real LibreBible packages in the local study workspace.
|
|
|
|
Tasks:
|
|
|
|
- Load KJV and NET package data from `W:\libre-bible-data`.
|
|
- Show Strong's links, lexicon entries, translation notes, commentary, dictionary entries, maps, and KJV audio where packages exist.
|
|
- Keep every resource optional and license-attributed in the study surface.
|
|
|
|
Definition of done:
|
|
|
|
- The HotView app can read real LibreBible packages and render the first useful set of study resources.
|
|
|
|
## Phase 3: HotView Development Loop And Gitea Sync
|
|
|
|
Status: complete.
|
|
|
|
Goal: make local interactive work reliable and keep source history synced.
|
|
|
|
Tasks:
|
|
|
|
- Use HotView/hot reload as the primary test loop.
|
|
- Keep `libre-study` and `libre-bible-data` pushed to Gitea.
|
|
- Record project credentials and operating notes in KeePass.
|
|
- Defer builds and hosted deployment unless explicitly requested.
|
|
|
|
Definition of done:
|
|
|
|
- The HotView loop is available, Gitea push works, and the repos can be kept clean and synced.
|
|
|
|
## Phase 4: Shared App Core
|
|
|
|
Status: complete.
|
|
|
|
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 app shell now uses the auth client instead of reading the hosted environment flag directly. The local workspace now migrates from legacy `localStorage` keys into a versioned workspace snapshot. 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. Complete for the current workspace snapshot shape.
|
|
- Add a migration path from legacy `localStorage` sessions to the versioned workspace snapshot. Complete for HotView/local preview.
|
|
|
|
Definition of done:
|
|
|
|
- The same UI talks to app-core contracts for resource queries and workspace persistence.
|
|
- HotView/local preview runs against the browser adapters without direct UI knowledge of storage/package internals.
|
|
- Legacy local session/settings keys migrate into the versioned workspace snapshot.
|
|
|
|
## Phase 5: Storage And Search Foundation
|
|
|
|
Goal: make hundreds of thousands or millions of entries feel normal.
|
|
|
|
Current foundation note: [Storage And Search Foundation](docs/storage-search-foundation.md).
|
|
|
|
Current status: Complete for the active HotView workflow. Browser page loads now use a shared page-query method and hydrate visible KJV Strong's links from chapter shards. Strong's-number search uses a compact package index where available. The native SQLite path now has explicit reference/attachment indexes and an FTS5 verse-search table.
|
|
|
|
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.
|
|
|
|
## Future Backlog: 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.
|
|
|
|
## Future Backlog: 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.
|
|
|
|
## Future Backlog: 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.
|
|
|
|
## Future Backlog: 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.
|