libre-study/docs/app-architecture-boundaries.md

App Architecture Boundaries

Libre Study should remain one app with platform adapters, not a set of separate apps.

Shared Core

The UI should talk to stable app-level contracts:

• resource catalog queries
• translation and page loading
• search
• Strong's lookup
• notes/commentary/dictionary/map/audio lookup
• session state
• user workspace persistence
• import/export
• authentication where a platform supports it

Primary files today:

• src/studyDataClient.ts: resource/query interface.
• src/studyClient.ts: browser and Tauri resource adapters.
• src/workspace.ts: workspace, auth, session, settings, and timeline persistence contracts.
• src/sessionPortability.ts: session export/import and one-way Nextcloud export.

Resource Data Boundary

LibreBible owns public resources:

• translations
• Strong's links
• lexicons
• footnotes and study notes
• commentaries
• dictionaries
• places, routes, maps, and media
• audio metadata and packages
• license and attribution metadata

Libre Study consumes those packages. It should not become the canonical source for public Bible resources.

User Data Boundary

Libre Study owns user workspace data:

• sessions
• notes
• timeline events
• view settings
• resource toggles
• tags and future highlights
• saved searches
• exports
• future collaboration state

User data should never be mixed into public LibreBible packages.

Adapter Lanes

HotView / Browser

Current lead lane. Uses Vite, local package reads, browser storage, and the private Tailscale/local intranet dev URL.

Normal URL:

http://desktop:5174/

Vite HMR should use the detected Tailscale IPv4 address when available. VITE_HMR_HOST remains the override for other private addresses.

Hosted Web

Parked until explicitly resumed. It may use login, remote persistence, private hosted resource URLs, and later collaboration services. Hosted deployment is not part of the normal HotView loop.

Tauri Desktop

Future hardening lane. It should remain account-optional and offline-capable. Desktop storage can use SQLite and local package installation/update management.

PWA / Mobile

Future lane. Evaluate responsive web and PWA behavior before considering mobile Tauri or native shells.

Current Rule

When adding new features, first decide which shared contract owns the behavior. Only then wire platform-specific adapter details. This keeps browser, hosted web, desktop, and future mobile from drifting into separate products.