Halkyon

Halkyon's apps and the packages they share, in one repository. Each app is a Flutter app for Linux, Windows, macOS, Android and iOS with a Serverpod server of its own, offline-first, and anyone may run an instance of it: the apps, the servers and everything needed to host an instance are published.

App	What it is	Where
Halkyon Learn	Creating, sharing and studying study material, flashcards scheduled with FSRS	apps/learn/, at learn.halkyon.eu
Halkyon Todo	To-dos; for now a shell on the shared packages: sign-in, instances, the account	apps/todo/
Halkyon Train	Running, cycling and rowing (ADR 0030); for now a shell on the shared packages	apps/train/

Halkyon Meditate is to follow.

Layout

• apps/<app>/: each app's server, generated client and Flutter app.
• packages/: what the apps share, taken by path: halkyon_ui (the look: theme, bundled Noto Sans, layout, shared widgets), halkyon_app (instances, signing in, each person's data and its sync), halkyon_base (what every server has, as a Serverpod module with its generated client halkyon_base_client: signing in, the account and its deletion, the pruning, the instance's basics), halkyon_core (low-level primitives) and halkyon_interop (contracts between apps).
• deploy/: what runs an instance (Docker Compose: Caddy, the server, PostgreSQL), learn.halkyon.eu's today.
• tool/: the checks, the pre-push hook and the release scripts. docs/adr/: the decisions and their reasons.

One pub workspace holds every package: one pubspec.lock, one version of each dependency. Melos runs scripts across them.

Getting started

• Flutter v3.47.8, the version CI uses (FLUTTER_VERSION in .forgejo/workflows/ci.yaml), with each platform you build for set up by Flutter's own guides; what an app needs beyond that is in its README.
• The Serverpod CLI v4.0.4: dart install serverpod_cli@4.0.4. Pass --no-analytics to every call; otherwise it reports the commands run to Serverpod.
• A C++ compiler, for flutter test too: a dependency of Learn's compiles MeCab as it builds.

flutter pub get                               # every package of the workspace
dart run melos list                           # the packages
ln -s ../../tool/pre-push .git/hooks/pre-push # the checks before every push
dart run tool/check.dart                      # format, analysis, every package's tests

dart run tool/check.dart --changed-since=origin/main tests only what changed since main and what depends on it; dart run melos run test:flutter --scope=<package> one package's Flutter tests. Each server's tests start an embedded PostgreSQL (no Docker) and need test passwords in the server's git-ignored config/passwords.yaml (the module's README and each app's say which). How the code is organised and the rules it follows are in AGENTS.md and each app's own.

Licences

The servers and the server module are under the Server Side Public License 1.0, the apps, the client packages and the other shared packages under the GNU Affero General Public License 3.0 or later. LICENSE.md says which covers what, CONTRIBUTING.md how to contribute.