Initial product design

SongCollect helps a worship leader prepare a Sunday service and a projection technician prepare its slides. This document records the initial decisions developed from the requirements. It defines intended behavior, not an implemented system or a verified integration contract. Decision 001 supplies the concrete application and data design and resolves the follow-up choices below.

Church workspaces and access🔗

Each church has its own song collection and private service plans. One account can belong to multiple churches, switch workspaces, and have different permissions in each. Initial collections contain approximately 300–400 songs per church; concurrent user counts remain unspecified.

The public request catalogue initially includes the entire church collection, with lyrics and PDFs available through a link or QR code without an account. Service plans, internal notes, and service attachments remain private. Cross-church collection sharing and finer permissions are future options.

Desktop browsers support editing, planning, and slide preparation. Mobile initially supports song search, viewing, and requests only.

Song collection🔗

A song groups its language versions and musical arrangements. Lyrics, PDF sheet music, ChordPro, and audio belong to the appropriate version or arrangement. Language versions and arrangements are distinct from service choices such as key and singing sequence.

Lyrics use named sections such as verse 1, chorus, and bridge, with an optional default singing sequence. A service selects a specific version, arrangement, and revision and supplies its own sequence. Search covers titles, lyrics, songbook numbers, and themes. Songbook references include the book name; a song can have multiple references and theme tags. Search results group related versions and arrangements under the song.

SongCollect previews ChordPro charts and automatically transposes them to the key selected for the service. Original source files remain unchanged. Uploaded PDFs do not transpose.

Service preparation🔗

SongCollect owns the complete ordered service plan and works independently of ChurchTools. The plan contains songs, Bible passages, announcements, sermon presentations, images, videos, notes, and attached materials.

1. The worship leader selects songs and supplies their singing sequences ahead of time.
2. Contributors attach materials. Bible passages are entered manually with reference, translation, and exact text. Sermon slides are uploaded as PDFs initially.
3. The technician prepares song layouts in SongCollect and marks service items as prepared.
4. The team marks the service Ready for Sunday and downloads the presentation package and musician pack.

The service team edits directly, with change history. The worship leader coordinates the order; editing the order is not restricted to that role.

Selected song revisions remain stable when the collection changes. Later lyric or reusable layout updates appear as available updates for explicit review and acceptance. A changed lyric, singing sequence, or attachment marks affected preparation as needing review. Changing the service order marks a previously exported service as needing an update.

Ready for Sunday locks the plan and its service materials by default. The team explicitly reopens it before making changes or accepting incoming updates. A church can disable the lock by default, and individual services can override that setting. Disabling the lock keeps editing available and retains preparation warnings. The lock does not prevent edits to the shared song collection.

Song slide layouts🔗

SongCollect owns language pairing, slide breaks, and song-specific formatting. Two languages appear stacked on the same slide. Corresponding lines are paired and stay together across slide breaks. Language order and text sizes are adjustable.

A church-wide layout supplies defaults, with settings saved for individual songs. Slide breaks and formatting are reusable across services, with service-specific overrides. Reusable presentation changes follow the explicit song revision update process so an existing service remains stable.

The presentation application receives prepared slides and handles live playback. A dedicated SongCollect presenter is deferred.

Requests from churchgoers🔗

Requests can target a service or a general pool. The team explicitly opens and closes requests for a service. The selected open default service is the default destination; otherwise the general pool is the default. The team reviews requests before adding songs to the plan. Requests do not automatically change the plan or bypass its readiness lock.

Multiple services may accept requests, with at most one explicit church-wide default. Closing that default falls back to the general pool. Names and messages are optional; the team tracks requests as New, Added, or Dismissed. See request decisions.

Offline access and hosting🔗

The first release supports both managed hosting and self-hosting, with the same core capabilities. The concrete deployment uses shared application and worker images, PostgreSQL, and a common asset storage interface; see deployment and recovery.

Offline access is read-only initially. Users can search the locally available collection and view downloaded song material. Lyrics, metadata, and search data are intended to be available locally; large attachments can be downloaded for selected songs or the whole collection. The interface shows when the local collection was last updated. Offline editing is a future possibility and should be considered in storage design.

The prepared presentation and its required media can be downloaded in advance for offline use in the presentation application. Collaborative editing, synchronization, and incoming public requests require a connection.

Imports and presentation exports🔗

Initial onboarding supports churches coming from OpenLP, PDF folders, and ChurchTools. Imports should provide a review step for titles, grouping, and possible duplicates.

The PDF collection has one song per PDF and selectable lyric text. Each PDF can create a draft song entry with its original file attached and its filename as an initial title. Extracted text supports lyric search; section structure must be reviewed before creating slides. OCR is not initially required for this collection.

FreeShow is the first target for complete service export. The technician downloads a package containing the prepared FreeShow project and required media, then imports it manually. Export is one-way: changes made in FreeShow remain local; reusable corrections belong in SongCollect. Direct transfer to a running FreeShow instance can follow later.

OpenLP import and song export provide compatibility for the church already using it. The extent to which OpenLP export preserves SongCollect layouts remains to be established.

Musicians receive a separate downloadable service pack with the selected PDFs and transposed ChordPro files in service order, plus the agreed singing sequences. These reflect the same selected song revisions as the presentation package.

FreeShow documents slide and arrangement data and project packages with media. These interfaces make it a promising target; faithful rendering and reliable import are not yet validated. Test a representative service with stacked bilingual lyrics, repeated choruses, sermon PDFs, and video before finalizing the export contract.

ChurchTools synchronization🔗

ChurchTools synchronization is optional per church. Churches using it continue to use both systems:

• Songs are maintained in SongCollect, which is authoritative for song content. Updates flow to ChurchTools after initial import.
• Service plans are editable in either system and synchronize both ways.
• Synchronization runs automatically, with a Sync now control and visible last-sync status.
• Linked records retain identifiers for their corresponding records in the other system.

Changes to different service items or fields merge automatically. Competing changes to the same field or service order follow a fixed policy: ChurchTools wins initially. It also wins edit-versus-delete conflicts: a ChurchTools deletion removes the item; a ChurchTools edit preserves an item deleted in SongCollect. Overridden states remain in change history. Precedence must be configurable so it can change later.

The readiness lock takes precedence over automatic application: incoming changes to a locked service remain pending until it is reopened. Reopening does not bypass the explicit acceptance required for song revision updates.

The synchronization design defines baseline comparison, intended mappings, unsupported-field preservation, retries, and polling intervals. API capabilities and exact writable field mappings still require verification against a test installation; not every SongCollect service field has a ChurchTools equivalent.

Collaboration and storage foundations🔗

People work on different songs and service items concurrently. Live co-editing of the same lyrics is outside the initial scope, but collaboration must shape storage from the start.

The initial storage design should include:

• Stable identifiers for songs, versions, arrangements, lyric sections, service items, and attachments. Singing sequences refer to section identifiers.
• Immutable revisions for song content and reusable presentation settings, with explicit revision references from services.
• Independent saves for songs and service items, separating item content from service order changes.
• Version-checked writes that prevent silent overwrites when two editors touch the same record.
• Change history and synchronization records sufficient to compare local and external edits and apply the configured merge policy.
• Consistent readiness and reopening rules across ordinary edits and synchronization.

Saved changes appear automatically for other users without refreshing. Incoming updates preserve unsaved edits; changing the same item underneath an editor produces a conflict warning. Accidental same-item edits preserve the draft and offer comparison, reload, or version-checked reapplication, as defined in revision and collaboration decisions. This is separate from the fixed ChurchTools synchronization policy.

Concrete design decisions🔗

Decision 001 defines the application architecture, data model, independent revision boundaries, accounts and invitations, readiness validation, export snapshots, Bible and announcement formatting, synchronization algorithm, offline cache management, measurable performance targets, and backup/restoration design. The corresponding additions are grouped into the requirements.

Remaining validation work🔗

The product and architecture choices are recorded. Implementation must still validate FreeShow and OpenLP compatibility against pinned releases and ChurchTools mappings against an authorized test installation. Collaboration, offline behavior, performance, and restoration require the release checks. These checks are not claims of implemented behavior.