gracepress/libre-study
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate roadmap into product tracks

Browse Source
This commit is contained in:
Jason
2026-07-15 18:20:09 -05:00
parent 759a75f50e
commit 55f7014aea
10 changed files with 292 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ROADMAP.md
+73 -188
View File
@@ -1,264 +1,149 @@
# 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:`.
Libre Study is the study workspace that consumes LibreBible packages. The goal is a full-featured Bible study program that is open-source and free to use where licensing permits, with one shared app core and platform adapters for HotView/browser, hosted web, Tauri desktop, and later PWA/mobile surfaces.
LibreBible owns public Bible and study-resource packages. Libre Study owns the user workspace: sessions, notes, settings, timeline, tags, exports, and future collaboration state.
## 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.
- Active workflow: HotView/hot reload on the private Tailscale/local intranet.
- HotView URL: `http://desktop:5174/` from connected machines.
- Browser development data: static LibreBible JSON/JSONL packages loaded from sibling repo `W:\libre-bible-data`.
- Desktop shell: Tauri 2 with Rust commands and a local SQLite database path.
- Current resource behavior: KJV and NET text, Strong's links, Strong's lexicon entries, KJV/NET footnotes and study notes, Matthew Henry Concise commentary, Easton/Smith dictionary entries, contextual maps/routes, and KJV audio controls.
- Current user workspace behavior: sessions, settings, structured notes, exported session JSON, note drawer, and session timeline are stored in the versioned local workspace snapshot.
## 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.
While the app is being shaped interactively, use HotView as the primary test loop. Do not spend cycles on web builds, local builds, installer builds, or hosted deployments unless the user explicitly asks for a release/deploy pass.
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.
4. Deploy the pushed state to the live/private web app only when explicitly requested.
5. Later, build signed desktop installers only from clean pushed release commits.
## 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.
- Shared app core: resource/query contracts, 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 local workspace snapshot during development.
- Hosted web adapter: server API, login session, remote persistence, stable 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.
Detailed architecture notes: [App Architecture Boundaries](docs/app-architecture-boundaries.md).
## 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
## Foundation Phase Archive
The first seven phases established the working foundation:
- Phase 1: App foundation and Bible page reader. Complete.
- Phase 2: LibreBible resource consumption. Complete for the first local study workspace.
- Phase 2: LibreBible resource consumption. Complete.
- 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. Complete.
- Phase 7: Study resource depth and polish. Complete.
- Phase 6: Notes, exports, and optional Nextcloud export/import. Complete.
- Phase 7: Study resource depth and polish. Complete for currently packaged LibreBible resources.
The next planned step is a consolidation pass that converts the completed foundation phases into durable product tracks. See [Project State - 2026-07-15](docs/project-state-2026-07-15.md).
Current project-state snapshot: [Project State - 2026-07-15](docs/project-state-2026-07-15.md).
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
## Phase 8: Consolidation And Product Tracks
Status: complete.
Goal: establish a usable local Bible study app with a real page-reader surface.
Goal: convert the completed foundation phases into durable product tracks so future work does not sprawl.
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.
Current result: the roadmap now tracks long-term work by product area instead of treating every future task as another foundation phase. Product-track details live in [Product Tracks](docs/product-tracks.md).
Definition of done:
- The app opens locally and shows a usable Bible page reader with session-aware navigation and notes.
- Completed foundation phases are preserved as an archive.
- Current app-core boundaries are documented.
- HotView/local, hosted web, Tauri desktop, and future PWA/mobile lanes are separated.
- Resource-data and user-data ownership are documented.
- Feature backlog is reorganized by product track.
- Work is committed and pushed.
## Phase 2: LibreBible Resource Consumption
## Active Product Tracks
Status: complete for the first local study workspace.
Use these tracks for future planning. Pick one active implementation phase at a time from these tracks.
Goal: consume real LibreBible packages in the local study workspace.
### Study Experience
Tasks:
Goal: make the reader, study margin, notes, search, and resource layout feel like a serious Bible study workspace.
- 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.
Near candidates:
Definition of done:
- Improve search result navigation and saved searches.
- Add cross-reference display once a LibreBible package exists.
- Improve note clipping, highlights, tags, and sermon/study workflows.
- Polish page layout, responsive behavior, and accessibility.
- The HotView app can read real LibreBible packages and render the first useful set of study resources.
### Resource Ecosystem
## Phase 3: HotView Development Loop And Gitea Sync
Goal: make LibreBible resources easy to add, attribute, query, and eventually install/update offline.
Status: complete.
Near candidates:
Goal: make local interactive work reliable and keep source history synced.
- Add cross-reference packages.
- Add more commentaries, dictionaries, lexicons, and atlas/media packages.
- Add licensed pronunciation-audio packages when available.
- Define package install/update metadata for desktop and hosted lanes.
Tasks:
### Persistence And Sync
- 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.
Goal: keep study work portable without making any single sync backend mandatory.
Definition of done:
Near candidates:
- The HotView loop is available, Gitea push works, and the repos can be kept clean and synced.
- Strengthen local workspace migrations.
- Improve import/export validation.
- Keep Nextcloud as explicit one-way export until a safe sync model exists.
- Resume hosted persistence only when a release/deploy pass is requested.
## Phase 4: Shared App Core
### Platform Adapters
Status: complete.
Goal: preserve one shared app core while letting each platform do the right local thing.
Goal: stop treating local preview, hosted web, and Tauri as separate code paths.
Near candidates:
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.
- Keep HotView as the lead development loop.
- Harden hosted web only after private deployment is explicitly resumed.
- Harden Tauri desktop after the browser study model stabilizes.
- Evaluate PWA/mobile after responsive behavior is proven.
Tasks:
### Public Responsibility
- 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.
Goal: prepare for public use without guessing about data responsibility, licensing, privacy, or abuse controls.
Definition of done:
Near candidates:
- 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.
- License and attribution pages.
- Privacy and terms pages.
- Account lifecycle, password reset, backups, and monitoring before public signup.
- Clear split between public resource data and private user workspace data.
## 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
Status: complete for one-way export/import in HotView.
Goal: make study work portable without making Nextcloud the primary database.
Current status: session notes are stored as structured note records while preserving the legacy draft field for compatibility. The session modal can export JSON, Markdown, HTML, and CSV, import JSON session exports as new sessions, and send a one-way export to a user-configured Nextcloud WebDAV folder. Nextcloud password input is not saved to the workspace snapshot.
Tasks:
- Save notes as structured session data first.
- Add export formats: JSON session, Markdown notes, HTML notes, CSV notes, and later sermon/study document formats.
- Add Nextcloud integration through WebDAV as an optional export target.
- Support one-way export first, then explicit import, then optional sync. Complete through one-way export and explicit JSON import.
- 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, imported from JSON, and optionally sent to a Nextcloud folder without breaking normal local or web persistence.
## Phase 7: Study Resource Depth
Status: complete for the currently packaged LibreBible resources.
Goal: continue turning the page into a complete study workspace.
Current status: the study margin dynamically shows Strong's definitions, translation notes, Matthew Henry commentary, Easton/Smith dictionary entries, contextual place maps, related UBS route labels, KJV audio controls, and Strong's pronunciation text when the active packages provide it. Maps and audio are now optional, collapsible, session-aware resources. Licensed pronunciation audio clips are not packaged yet, so the app does not present a fake playback control for them.
Tasks:
- Add map support from LibreBible place/gazetteer packages. Complete.
- Show map availability when a visible verse mentions a known place. Complete.
- Add audio Bible support at chapter granularity first, then verse granularity when sources provide timestamps or verse files. Complete for KJV chapter and verse-entry playback from the packaged source.
- Add pronunciation audio tied to English terms, Strong's numbers, lemmas, Greek, and Hebrew where licensing permits. Complete for available Strong's pronunciation text; playable clips remain blocked until a licensed pronunciation-audio package exists.
- Add more commentaries, dictionaries, lexicons, cross-references, and study-note packages.
- Keep every resource optional, collapsible, session-aware, and license-attributed. Complete for currently visible resource panels.
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
### Collaboration
Goal: add shared Bible study without turning the basic app into a social network.
Tasks:
Near candidates:
- 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.
- Consider WebSockets and conflict-safe document models only after single-user persistence works.
## 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.
SQLite remains appropriate for desktop, local, and private/single-user workflows. 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.