The Zangbundel bibliotheek-manager (library manager; the Editor of the specification) lets scout leaders with average computer skills create, check, edit and sign song libraries for the Zangbundel app, without a command line, version numbers to keep by hand or folder structures to build.
The process it supports:
- Open an existing library ZIP, or start a new library.
- The manager checks the library's integrity and correctness, and lets the user maintain its sets and songs.
- Optionally sign the library with the author's key.
- Save it as a ZIP and publish it any way the user likes: e-mail, a messaging app, a website, a USB stick.
- The Zangbundel app imports the ZIP, checks it, and shows whether it is signed and by whom.
The manager is live at https://zangbundel.nl, version 0.2.1. That is its only address. Nobody connected with the project ever asks for your key file. Trial builds for testers run at test.zangbundel.nl.
- The specification: the functional design specification, design/FDS.md, is at draft 0.12.
- The design: the web app's design is in design/webappGUI.md and design/webappTDS.md, and its security in design/securityAssessment.md.
- Where it runs: the web app is in
webapp/src. Libraries and keys are processed in the browser and never sent to the server (webappTDS TD-06 to TD-08). - The server: its set-up and runbook are in
webapp/server/README.md. - Test libraries:
test-libraries/holds 60 shared test libraries, one invalid case for nearly every rule of FDS section 6, with a checker (O-04). - The import side of the specification (FDS section 8) is built in the Zangbundel app, not here.
- What is left before version 1 is in the implementation plan (milestone M7 and the completion plan).
The changelog lists what changed and when.
As specified in the FDS:
- New or open. Start a new library with a title, or open a library (
.zbl). A ZIP of folders and song files, or a release archive of a git library, is taken in as a new library; a folder per set becomes a set. - Check. Every rule of FDS section 6 (package, structure, manifest, signature, song) is applied while the user works. Messages are grouped by severity and lead to their location; errors block saving.
- Edit. Songs: add, edit, delete, as ChordPro text with live validation or through form fields that stay in step with the text. Sets: ordered setlists of the library's songs; a song can be in several sets.
- Save. The manager raises the version, asks for an optional note on what changed, writes the manifest with a SHA-256 hash of every file, and proposes the file name.
- Sign. Optional Ed25519 signing with a key file (
.zbkey). The manager shows a key's fingerprint wherever it shows the key. A signed library opens read-only until its key is loaded; Save as copy starts a new library under a new key. - Nothing stored. The manager keeps nothing between sessions: no libraries, no keys (FDS principle 5, EDT-02, EDT-64).
design/ the specification: FDS.md (what the manager does), webappGUI.md and webappTDS.md (the web app)
webapp/ mock/ (design reference), placeholder/ and test-holding/ (static pages),
tools/ (build, sign, header check), server/ (nginx, release scripts, runbook)
memory/ working memory for AI coding agents (index, gotcha log, to-do)
.claude/ review profile for AI coding agents
CLAUDE.md orientation file for AI coding agents
The manager is built as a web app that runs on nginx or Apache with PHP. Each screen is checked in a mock first, then deployed to a test server. Code and test libraries follow.
| Document | Read it when |
|---|---|
| design/FDS.md | You want to know what the manager must do: the library package format, the manifest, signing, the validation rules, the Editor's behaviour, the app's import, and every user message. Requirements are numbered (PF-nn, EDT-nn, APP-nn, …) and rules carry codes (PKG-nn, SNG-nn, …). |
| design/webappGUI.md | You design or review a screen of the web app: what it shows, what happens on each action, and its colours, buttons and icons, which come from the Zangbundel app. |
| design/webappTDS.md | You build, serve or deploy the web app: server (nginx or Apache with PHP), the mock, the test server. |
| design/securityAssessment.md | You touch keys, files, the network, a dependency, the server or the deployment: the threats, and the requirements and release checks the implementation must meet. |
| design/implementationPlan.md | You want to know how the manager is being built, in which order, and what has to pass before each step is done. |
The library format and the import rules in the FDS are shared with the Zangbundel app; the app and the manager must apply the same validation rules.
This repository contains no lyrics and will not accept any. Libraries are made by their authors with the manager, on their own device. If you want to contribute songs, contribute to a library, such as Zangbundel-bibliotheek, not here.
See contributing.md and the Code of Conduct. The most useful help right now is a review of the FDS, especially from people who maintain a song library or support scout leaders, and answers to its open items through GitHub issues.
If you use an AI coding agent, CLAUDE.md is its entry point; it follows the agent-ready-projects layout.
See license.md for details.
The code in this repository is licensed under the Apache License 2.0 (see LICENSE and NOTICE). The documentation and other non-code content are licensed under a Creative Commons Attribution-NonCommercial 4.0 International License (http://creativecommons.org/licenses/by-nc/4.0/) by Remko Welling, PE1MEW (https://github.com/pe1mew).
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.
This project is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
