Study Tools
GospeLib provides a suite of personal study tools that work alongside the scripture reader. All annotation data is persisted to PostgreSQL (server-side) and available across devices when signed in.
Overview
| Tool | Description | Access |
|---|---|---|
| Highlights | Color-code verses with 12 colors | Long-press verse, select from color picker |
| Notes | Rich-text verse-anchored notes | Action ring or vertical toolbar |
| Bookmarks | Quick-save verses for later | Double-tap or toolbar action |
| Reading History | Chapter-level progress tracking | Automatic |
| Pinboard | Session-scoped workspace for accumulating connections | Pin from hover cards or Study Map |
| Journal | Chronological activity log with calendar heatmap | Core plugin |
Highlights
The highlight system uses 12 colors organized into two categories:
- 8 doctrinal colors -- Each mapped to a theological theme (e.g., Christ's attributes, covenants, prophecy, commandments), using the platform's doctrinal color taxonomy
- 4 personal colors -- User-assigned for custom categorization
Highlights are applied at the verse level. Long-pressing a verse opens the action ring (on touch devices) or the vertical toolbar activates (on desktop), presenting the color picker. Multiple highlights can overlap on the same verse.
Highlight data is stored in gl_highlights in PostgreSQL and rendered as colored background washes on the verse text. The Verse Map navigation strip shows highlight bars at the corresponding vertical position for quick visual scanning of an annotated chapter.
Notes
Notes are verse-anchored rich-text documents powered by Tiptap (a ProseMirror-based editor). Each note is linked to a specific verse or verse range and supports:
- Markdown-style formatting (headings, bold, italic, lists)
- Scripture reference auto-linking
- Cross-reference registration with the knowledge graph
Notes appear as dot markers in the Verse Map and Page Gutters. Tapping a note marker opens the note in the context panel or a dedicated pane.
Bookmarks
Bookmarks provide quick-save functionality without requiring any text input. Double-tapping a verse (or clicking the bookmark toolbar action) toggles a bookmark. Bookmarked verses show flag markers in the Verse Map.
A bookmark list view collects all bookmarks for browsing and navigation.
Reading History
The platform automatically tracks reading progress at the chapter level in gl_reading_progress. This powers:
- Resume reading -- Returning users are taken to their last reading position
- Progress visualization -- The breadcrumb minimap shows reading progress as tinted chapter segments
- Come Follow Me integration -- The weekly reading assignment surfaces in the home dashboard, tracking progress through the current week's passages
Pinboard
The Pinboard is a session-scoped workspace for accumulating connections during a study session. Inspired by Photoshop's Layers panel, it provides:
- Pinnable types -- Verses, verse ranges, phrases, lexicon/dictionary entries, cross-reference chains, notes, and AI responses
- Organization -- Folders, color-coded labels, sort/group options, drag-and-drop reorder
- Bidirectional Study Map sync -- Pinning an item adds it to both the Pinboard and the Study Map; unpinning removes from both
- Session persistence -- Stored in Dexie.js (IndexedDB) so the collection survives page refreshes
The Pinboard auto-opens on the first pin action and lives in the right sidebar as a dock zone widget.
Journal
The core.journal plugin provides a chronological activity log tracking passages read, annotations created, and searches performed. A calendar heatmap visualization shows study consistency over time, similar to GitHub's contribution graph.
Deep Dive: Data Model
All user annotation data lives in PostgreSQL, not the graph database. This separation keeps the knowledge graph focused on canonical scripture data while user-specific data lives in a traditional relational store:
| Table | Purpose |
|---|---|
gl_highlights | Verse highlight colors and metadata |
gl_notes | Rich-text note content with verse anchoring |
gl_bookmarks | Bookmarked verse references |
gl_reading_progress | Chapter-level reading tracking |
The auth service provides CRUD endpoints for all annotation types, with JWT authentication enforced at the gateway. Annotations sync to the client on login and are available offline through Dexie.js caching.
Hover Card Integration
The three-layer hover card system provides progressive disclosure of study tools:
- Layer 1 (Peek) -- 200ms delay, shows a quick preview of verse context
- Layer 2 (Detail) -- Tabbed panel with lexicon data, cross-references, notes, and commentary
- Layer 3 (Actions) -- Pin to Pinboard, open in pane, compare translations
Related Pages
- Scripture Reader -- The reading experience where study tools are used
- Knowledge Graph -- The graph that study tools interact with
- Architecture > Data > PostgreSQL -- Schema for annotation tables
- Subscriptions -- Which study tools are available on each plan tier