SchedPlus technical overview

SchedPlus separates user interfaces from the scheduling core. Startup selects Tkinter, PyQt, or the CLI; each works through logic.scheduler.Scheduler, which validates tasks and delegates persistence to the SQLite storage module.

Tkinter / PyQt / CLI
        │
   Scheduler + validation
        │
 SQLite storage (tasks.db)

Application and package identity

Every interface uses the shared application identity provider. It loads the immutable schedplus/build-info.json embedded by release packaging and falls back to installed Python package metadata for the version when embedded build information is unavailable. User interfaces do not read pyproject.toml at runtime.

The identity includes version, edition, update channel, package format, platform, and architecture. PyQt, Tkinter, the Full-edition selector, and the CLI therefore report the same installed version, while desktop About details expose the package fields useful for support and update troubleshooting.

Storage and recovery

SQLite is the sole persistence backend. The entries table contains id, date, time, text, createdAt, and updatedAt. IDs are UUIDs; date and time values use normalized ISO formats.

The schema version is recorded in PRAGMA user_version. Missing migrations run in numeric order inside one transaction. Before changing an existing database, SchedPlus creates a consistent timestamped tasks_pre_migration_v<old>_to_v<new>_*.db backup beside it. A failed migration rolls back without discarding the original rows. Databases from v0.7.3 and v0.8.0 are adopted as schema version 1; subsequent migrations are added to the end of the migration registry rather than rewriting released steps.

Downgrades are intentionally refused. If an older application encounters a database with a newer schema version, it leaves the file unchanged and asks the user to install a compatible newer SchedPlus build.

Initialization runs a SQLite quick check before migration. If confirmed corruption is detected, SchedPlus preserves the damaged database as a timestamped tasks_corrupted_*.db file, creates a new current-schema database, and reports the backup location.

Storage writes use transactions, foreign keys are enabled, and SQLite waits up to three seconds for a busy database. Storage logs rotate in the application data directory as schedplus.log (up to three 1 MB backups).

Local data portability

The shared data-transfer service gives PyQt, Lite, and CLI identical offline operations. A schedplus-backup version 1 JSON document contains a consistent task snapshot and relevant local preferences. Restore parses and validates the entire document before writing, creates a second backup of current data, then replaces tasks transactionally through the current schema.

A schedplus-task-export version 1 document contains only tasks. Import runs in one database transaction. New IDs are inserted; identical existing IDs are duplicates; existing IDs with different values are conflicts. Duplicates and conflicts are skipped and reported. Files are read from or written to paths the user chooses and are never transmitted by SchedPlus.

Dependency profiles

Frozen build profiles

Release packaging starts with four reproducible PyInstaller onedir builds: Standard (PyQt), Lite (Tkinter), Full (the interface selector), and CLI. Each build uses its dedicated launcher, bundles the application icons, package metadata, license files, and NOTICE, and explicitly excludes frameworks that do not belong to that edition. The frozen directory is then wrapped by a platform package or installer.

All frozen profiles explicitly collect the shared updater modules required by startup and package identity. Whether updating is enabled remains controlled by the embedded package-format policy rather than by omitting updater imports.

Because SchedPlus desktop distributions are GPL-3.0-only, every binary release must provide corresponding source and retain its GPL license and NOTICE. The project repository and matching source tag or archive are the source location.

Debian packages

The initial Debian packages are schedplus (Standard), schedplus-lite, and schedplus-cli. Each installs its frozen application under /usr/lib, its launcher under /usr/bin, and licensing documents under /usr/share/doc. Standard and Lite also install their desktop entry, hicolor icons, and AppStream metadata. All three are mutually exclusive alternative bundles of the same application rather than add-on packages. Standard launches PyQt by default and also exposes CLI command handling; Lite restricts the desktop bundle to Tkinter, while CLI omits the graphical interfaces. No package owns task data, so ~/.local/share/ZFordDev/SchedPlus/tasks.db survives switching editions, upgrades, and package removal.

AppImage

SchedPlus Standard is also available as a portable AppImage. It contains a read-only frozen application and keeps task data at ~/.local/share/ZFordDev/SchedPlus/tasks.db, outside the image and its directory. Run the AppImage directly with FUSE available; if FUSE is missing, use --appimage-extract and launch squashfs-root/AppRun. Each release ships an architecture- and versioned filename with a SHA-256 checksum.

Windows and Microsoft Store

Windows releases provide portable ZIPs for all four editions and a per-user Standard installer at %LocalAppData%\\Programs\\SchedPlus. These formats, and the Standard MSIX package, always store tasks at %APPDATA%\\ZFordDev\\SchedPlus\\tasks.db, outside their installation folders. The MSIX package contains only the Standard PyQt application, has no command execution alias, requests only runFullTrust, and receives Store-managed updates. Its listing is not public until the Store release is approved.

Snap

The Standard Snap uses strict confinement. Its data path is $SNAP_USER_COMMON/SchedPlus/tasks.db, not the revision-specific Snap home directory, so Snap refreshes preserve tasks. Snap publication is pending.

Update policy

The updater only operates when packaging embeds schedplus/build-info.json that enables the installed package format. Build identity covers version, edition, platform, architecture, format, stable or preview channel, manifest URL, and Ed25519 public verification key. Release automation creates the matching signed feed from final artifact hashes; the private key exists only in a masked protected secret and is never written to artifacts or logs.

SchedPlus verifies the signed HTTPS manifest, exact artifact selection, SHA-256, and byte size before handoff. Windows portable packages use an independent updater for atomic swaps, startup health confirmation, and rollback. Debian and AppImage packages expose the verified download for normal platform installation. Standalone Windows installers remain opted out until public Authenticode signing is configured. Source checkouts cannot overwrite their working tree, while Snap and Microsoft Store formats always defer updates to their provider.

The complete desktop distribution is GPL-3.0-only. The reusable src/logic scheduler, validation, task model, and storage layer are separately available under Apache-2.0. See the project NOTICE for licensing transition details.