These requirements define the agreed first release scope. The initial product design explains the agreed workflows; Decision 001 defines the concrete application and data design. Requirements are grouped by topic, with existing identifiers retained for reference. They describe intended behavior, not completed implementation or verified integration support. Status is Planned until implementation begins; requirements can then move to In progress and Implemented after verification. The first implementation increment covers accounts/church membership foundations and revisioned song metadata; In progress means only part of the complete requirement is available. See the implementation guide for exact coverage and remaining work.
Church workspaces and access🔗
| ID | Requirement | Status |
|---|---|---|
| SC-06 | Each church shall have a separate workspace with private service plans and internal materials. | In progress |
| SC-07 | One account shall support membership in multiple churches, workspace switching, and separate permissions per church. | In progress |
| SC-08 | Church roles shall be Administrator, Editor, and Viewer; administrators manage settings, members, and integrations, editors maintain songs and services, and viewers have read access. | In progress |
| SC-44 | Accounts shall support verified email/password sign-in, password recovery, and single-use church invitations with assigned roles; self-hosted administrators shall have a local recovery path. | In progress |
| SC-45 | Private APIs, events, and assets shall enforce church membership and role permissions; public reads shall expose only the public catalogue projection. | In progress |
| SC-46 | Services shall retain UTC start times and the church time zone for local display and scheduling. | Planned |
Song collection🔗
Content and organization🔗
| ID | Requirement | Status |
|---|---|---|
| SC-01 | SongCollect shall maintain a song collection containing lyrics, PDF sheet music, ChordPro, and audio. | In progress |
| SC-11 | Songs shall group language versions and musical arrangements, with materials attached to the appropriate version or arrangement. | Planned |
| SC-47 | Song metadata, lyric versions, musical arrangements, and presentation profiles shall have independent immutable revisions; services shall pin every selected revision and asset. | In progress |
| SC-12 | Lyrics shall support named sections and a default singing sequence; service sequences shall reference those sections. | Planned |
| SC-14 | Songs shall support multiple theme tags and songbook references, each reference identifying both the book and song number. | Implemented |
Search🔗
| ID | Requirement | Status |
|---|---|---|
| SC-03 | Song search shall return results quickly, meeting the measurable response-time targets in SC-68. | Planned |
| SC-13 | Search shall cover titles, lyrics, songbook references, and themes, grouping results by song and identifying matching versions or arrangements. | In progress |
| SC-68 | Warm search API responses shall meet p95 ≤300 ms and offline search p95 ≤150 ms under the reference conditions defined in Decision 001. | Planned |
Chord charts🔗
| ID | Requirement | Status |
|---|---|---|
| SC-15 | ChordPro shall transpose automatically to the service key and support preview and download without modifying source files; uploaded PDFs shall remain unchanged. | Planned |
| SC-49 | ChordPro transposition shall distinguish source key, sounding key, and capo; unsupported notation or unknown source keys shall require correction rather than guessed output. | Planned |
Service preparation🔗
Plans and materials🔗
| ID | Requirement | Status |
|---|---|---|
| SC-16 | SongCollect shall support complete ordered service plans independently of ChurchTools, including songs, Bible passages, announcements, sermon PDFs, images, videos, notes, and attachments. | Planned |
| SC-17 | Each service song shall select its version, arrangement, revision, key, and singing sequence, with the worship leader supplying the sequence before slide preparation. | Planned |
| SC-18 | Bible passages shall initially support manual entry of the reference, translation, and exact text; sermon slide uploads shall initially use PDF. | Planned |
| SC-19 | Service teams with edit access shall edit plans directly, including their order; technicians shall be able to mark items as prepared. | Planned |
Revisions and readiness🔗
| ID | Requirement | Status |
|---|---|---|
| SC-20 | Services shall retain selected song and layout revisions, show available updates, and require explicit acceptance before applying them. | Planned |
| SC-21 | Changes to lyrics, singing sequences, or attachments shall flag affected preparation for review; order changes shall flag previous service exports for update. | Planned |
| SC-22 | Ready for Sunday shall lock service editing and incoming updates until explicitly reopened, with locking enabled by default, a church-wide default setting, and per-service overrides. | Planned |
| SC-23 | Disabling the readiness lock shall retain preparation warnings and explicit song revision updates; locking a service shall not lock the shared song collection. | Planned |
| SC-50 | Ready for Sunday shall require valid references and order, current preparation markers, complete assets and bilingual alignment, and passing slide validation; available updates shall remain warnings. | Planned |
| SC-51 | Preparation markers shall identify the exact item content digest and be invalidated by material changes; readiness transitions shall be atomic with concurrent writes. | Planned |
Song slide layouts🔗
| ID | Requirement | Status |
|---|---|---|
| SC-24 | SongCollect shall prepare reusable song formatting and slide breaks using church defaults, per-song settings, and service-specific overrides. | Planned |
| SC-25 | Bilingual slides shall stack two languages, support adjustable language order and text sizes, and keep corresponding line pairs together across slide breaks. | Planned |
| SC-48 | Bilingual alignment shall support unequal line counts through paired line groups, preserve stable section and line identities, and flag missing references after accepted updates. | Planned |
| SC-52 | Each service shall pin resolved style defaults; later church-default changes shall require explicit acceptance and shall not silently alter prepared slides. | Planned |
| SC-53 | Bible and announcement slides shall support preview and editable breaks; rendering shall preserve safe margins, identify overflow, and use the same layout inputs for preview and export. | Planned |
Churchgoer access and requests🔗
Public catalogue🔗
| ID | Requirement | Status |
|---|---|---|
| SC-26 | The public catalogue shall initially expose the entire church song collection, including lyrics and PDFs, without login through a link or QR code; service plans and internal materials shall remain private. | In progress |
Request workflow🔗
| ID | Requirement | Status |
|---|---|---|
| SC-04 | Churchgoers shall be able to find songs and submit ad hoc requests to the service team. | Planned |
| SC-27 | Requests shall target a service or a general pool; the team shall open and close service requests, with an open service as the default destination and the general pool as the fallback. | Planned |
| SC-28 | The team shall review requests before adding songs; requests shall neither modify plans automatically nor bypass readiness locks. | Planned |
| SC-54 | A church shall select at most one default request service while allowing multiple services to accept requests; closing the default shall fall back to the general pool. | Planned |
| SC-55 | Requests shall support optional names and messages, team-only New/Added/Dismissed status, and a link to the resulting service item; closed destinations shall require explicit reselection. | Planned |
Collaboration🔗
Concurrent work🔗
| ID | Requirement | Status |
|---|---|---|
| SC-05 | The shared collection shall remain synchronized while team members maintain songs and prepare services concurrently. | Planned |
| SC-40 | Different songs and service items shall support concurrent independent edits, separating service item content from order changes. | Planned |
| SC-41 | Saved changes shall appear automatically for other users while preserving unsaved edits; competing writes to the same record shall be detected rather than silently overwrite data. | Planned |
| SC-56 | Writes shall check the edited record version; stale saves shall preserve drafts and offer comparison, reload, or version-checked reapplication without silent overwrites. | In progress |
| SC-57 | Live notifications shall support replay, deduplication, reconnect, and polling fallback without replacing unsaved drafts. | Planned |
| SC-69 | Saved changes shall reach connected observers within two seconds p95 under the reference load defined in Decision 001. | Planned |
Storage foundations🔗
| ID | Requirement | Status |
|---|---|---|
| SC-42 | Storage shall provide stable entity identifiers, immutable song and reusable layout revisions, explicit service revision references, and change and synchronization history. | In progress |
| SC-43 | Storage design shall accommodate future offline editing; the first release shall not require offline writes or live co-editing of the same lyrics. | Planned |
| SC-58 | Create, reorder, export, and background operations shall support safe retries through operation identities, atomic change history/outbox records, and idempotent processing. | In progress |
Integrations🔗
| ID | Requirement | Status |
|---|---|---|
| SC-02 | SongCollect shall integrate with OpenLP, ChurchTools, and FreeShow through the import, export, and synchronization capabilities below. | Planned |
Collection imports🔗
| ID | Requirement | Status |
|---|---|---|
| SC-31 | Initial imports shall support OpenLP, ChurchTools, and PDF folders, with review of titles, grouping, and possible duplicates. | Planned |
| SC-32 | PDF import shall retain each original file, use its filename as an initial title, extract selectable text for search, and require review of lyric sections before slide preparation. | Planned |
| SC-59 | Imports shall preserve originals and source identifiers, stage candidates for review, avoid duplicates on retries, and distinguish extracted text from reviewed slide lyrics. | Planned |
Presentation and musician exports🔗
| ID | Requirement | Status |
|---|---|---|
| SC-33 | FreeShow shall be the first complete service export target, using a manually downloaded and imported package containing prepared slides and required media for offline presentation. | Planned |
| SC-34 | FreeShow export shall initially be one-way; FreeShow edits shall remain local. OpenLP song export shall provide compatibility. | Planned |
| SC-35 | A downloadable musician pack shall include selected PDFs, transposed ChordPro files, and singing sequences in service order, using the same song revisions as the presentation export. | Planned |
| SC-60 | Presentation and musician exports shall use one immutable service snapshot containing all selected revisions, assets, order, sequences, and rendering inputs. | Planned |
| SC-61 | Exports shall include revision/checksum manifests, preserve prior completed artifacts, expose build failures, and flag outdated packages; regeneration shall be explicit. | Planned |
| SC-62 | Export adapters shall validate supported target versions and report format limitations; OpenLP export shall not promise complete layout or native service fidelity. | Planned |
| SC-75 | Uploaded assets shall be processed and checked before preparation; unsupported media, fonts, or corrupt files shall surface actionable errors rather than enter completed exports. | Planned |
ChurchTools synchronization🔗
| ID | Requirement | Status |
|---|---|---|
| SC-36 | ChurchTools synchronization shall be optional per church; after initial import, SongCollect shall be authoritative for songs and send song updates to ChurchTools. | Planned |
| SC-37 | Service plans shall support editing in both systems and automatic two-way synchronization, with Sync now and visible last-sync status. | Planned |
| SC-38 | Nonconflicting service edits shall merge automatically; ChurchTools shall initially win competing field, order, and edit-versus-delete changes, with configurable precedence and overridden states retained in history. | Planned |
| SC-39 | Incoming changes to locked services shall remain pending until reopening; synchronization shall preserve explicit acceptance of song revision updates. | Planned |
| SC-63 | ChurchTools merges shall compare current local and remote values against acknowledged shared baselines; deletion shall require confirmed absence and order merges shall preserve independent insertions. | Planned |
| SC-64 | Synchronization shall preserve remote-only fields and local-only presentation data, record supported mappings, and report unresolved references and unsupported capabilities. | Planned |
| SC-65 | Synchronization shall initially poll linked active services every 60 seconds and songs every five minutes, with coalesced manual runs and visible success/error status. | Planned |
| SC-66 | Synchronization shall serialize connection writes, back off transient failures, verify remote results before acknowledging them, and reconcile uncertain creates before retrying. | Planned |
| SC-67 | Integration credentials shall remain encrypted server-side and absent from browser caches, exports, and logs; restored installations shall pause synchronization until fresh comparison. | Planned |
Platforms and deployment🔗
Browser and hosting support🔗
| ID | Requirement | Status |
|---|---|---|
| SC-09 | Desktop browsers shall support the full preparation workflow; mobile shall initially support only song search, viewing, and requests. | Planned |
| SC-10 | Managed hosting and self-hosting shall provide the same core capabilities in the first release. | Planned |
| SC-72 | Managed and self-hosted deployments shall use the same versioned application and worker images, schema migrations, storage interface, and health reporting. | In progress |
Offline access🔗
| ID | Requirement | Status |
|---|---|---|
| SC-29 | Offline access shall initially be read-only, supporting local song search and viewing downloaded material, with a visible last-update status. | Planned |
| SC-30 | Song metadata, lyrics, and search data shall be available locally; attachments shall support download for selected songs or the whole collection. | Planned |
| SC-70 | Offline caches shall separate deployments, accounts, churches, and public/private data, switch complete generations atomically, and remove deleted records on refresh. | Planned |
| SC-71 | Offline downloads shall expose size and availability, quota/eviction failures, last completed refresh, and removal controls; sign-out shall clear private cached content. | Planned |
Backup and restoration🔗
| ID | Requirement | Status |
|---|---|---|
| SC-73 | Both hosting modes shall support nightly backups with 30-day retention, covering a consistent database snapshot, referenced assets, versions, and recoverable encrypted secrets; target RPO shall be 24 hours. | Planned |
| SC-74 | Restoration shall verify checksums, memberships, pinned services, search, and exports, rotate sessions, and pause integrations; target RTO shall be four hours for the reference workload. | Planned |
Validation and deferred scope🔗
Decision 001 resolves the initial data model, revision boundaries, sign-in and invitations, readiness checks, request defaults, slide formatting, export regeneration, synchronization intervals, offline cache management, performance targets, and recovery design.
Release validation must still establish FreeShow layout/package compatibility, OpenLP content fidelity and limitations, and ChurchTools API fields, permissions, and concurrency behavior against supported versions. The requirements do not assert that every service field maps to an external tool. Performance and recovery numbers are acceptance targets, not measured results; the reference workload is 1,000 songs per church, 25 active sessions, and a 2-core/4-GiB server. Full test conditions and integration gates are recorded in the decision document.
A dedicated presenter, direct FreeShow transfer, PowerPoint sermon uploads, automatic Bible lookup, finer permissions, cross-church sharing, offline editing, and live co-editing of the same lyrics remain deferred.