2026-10-19 20:39:09 +02:00
# Halkyon
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
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 ](https://serverpod.dev )
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.
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
| App | What it is | Where |
2026-09-30 15:13:34 +02:00
|---|---|---|
2026-10-19 20:39:09 +02:00
| Halkyon Learn | Creating, sharing and studying study material, flashcards scheduled with FSRS | [`apps/learn/` ](apps/learn/README.md ), at learn.halkyon.eu |
2026-10-19 21:56:12 +02:00
| Halkyon Todo | To-dos; for now a shell on the shared packages: sign-in, instances, the account | [`apps/todo/` ](apps/todo/ ) |
feat(train): Halkyon Train's shell, Todo's copied and renamed (ADR 0030, D12)
apps/train with halkyon_train_server, _client and _flutter, as Todo's:
halkyon_base configured by trainBase(), its own register alone and a
member of the instance's where the operator names one, the app on
halkyon_app's gates with Train's frame, account sheet and About, texts
in British English and German that speak of workouts, app.halkyon.train
on Android, iOS, Linux, macOS and Windows.
Where it differs from Todo: development ports of its own (8180 to 8190),
so it runs beside Learn's server; one initial migration with the schema
Todo's migrations end at (the same tables, compared line by line), not
Todo's seventeen; and Todo's icon as a placeholder until the icon tool
of ADR 0031 draws Train's bike. The workspace, the licences, the READMEs
and AGENTS.md name it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-28 10:26:49 +01:00
| Halkyon Train | Running, cycling and rowing (ADR 0030); for now a shell on the shared packages | [`apps/train/` ](apps/train/ ) |
docs: the README's aims, developer setup and releases
The README opens with what the app aims at: creating, sharing and
collaborating on study material, FSRS for retention, study material
organised with its external references, offline-first, and a transparent
stack anyone can host.
"Setting up" lists what developers need: Flutter as CI pins it, with
Flutter's own guide per platform; the Serverpod CLI; the Linux packages,
with what each plugin needs them for; Developer Mode on Windows, and why;
no Docker for development; Python for the scripts in tool/.
"Releases" says where releases are published, how to check a download
(the signed checksums, the APK certificate's fingerprint), how versions
are numbered, and how a maintainer makes one with tool/release.sh.
AGENTS.md: Windows needs Developer Mode for Flutter's plugin links too,
not only for pdfrx's build.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-05 17:00:27 +02:00
feat(train): Halkyon Train's shell, Todo's copied and renamed (ADR 0030, D12)
apps/train with halkyon_train_server, _client and _flutter, as Todo's:
halkyon_base configured by trainBase(), its own register alone and a
member of the instance's where the operator names one, the app on
halkyon_app's gates with Train's frame, account sheet and About, texts
in British English and German that speak of workouts, app.halkyon.train
on Android, iOS, Linux, macOS and Windows.
Where it differs from Todo: development ports of its own (8180 to 8190),
so it runs beside Learn's server; one initial migration with the schema
Todo's migrations end at (the same tables, compared line by line), not
Todo's seventeen; and Todo's icon as a placeholder until the icon tool
of ADR 0031 draws Train's bike. The workspace, the licences, the READMEs
and AGENTS.md name it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-28 10:26:49 +01:00
Halkyon Meditate is to follow.
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
## Layout
docs: the README's aims, developer setup and releases
The README opens with what the app aims at: creating, sharing and
collaborating on study material, FSRS for retention, study material
organised with its external references, offline-first, and a transparent
stack anyone can host.
"Setting up" lists what developers need: Flutter as CI pins it, with
Flutter's own guide per platform; the Serverpod CLI; the Linux packages,
with what each plugin needs them for; Developer Mode on Windows, and why;
no Docker for development; Python for the scripts in tool/.
"Releases" says where releases are published, how to check a download
(the signed checksums, the APK certificate's fingerprint), how versions
are numbered, and how a maintainer makes one with tool/release.sh.
AGENTS.md: Windows needs Developer Mode for Flutter's plugin links too,
not only for pdfrx's build.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-05 17:00:27 +02:00
2026-10-19 20:39:09 +02:00
- `apps/<app>/` : each app's server, generated client and Flutter app.
- `packages/` : what the apps share, taken by path:
[`halkyon_ui` ](packages/halkyon_ui/README.md ) (the look: theme, bundled Noto Sans,
layout, shared widgets), [`halkyon_app` ](packages/halkyon_app/README.md ) (instances,
signing in, each person's data and its sync),
[`halkyon_base` ](packages/halkyon_base_server/README.md ) (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),
refactor(learn): the editor's general parts move to halkyon_editor (ADR 0033, D37)
Todo stores editor documents too, so the document, the editor, its view,
the format bar, links, the clipboard, scripts and EditorBlocks move, with
their strings and tests, to a shared package on the same appflowy_editor
fork. What is Learn's alone stays in Learn on top of it, and what the
editor took from it directly is inverted: EditorBlocks gains textMarks,
formatActions and onEditorClosed, RichContentEditor a wrapEditor, and an
InsertableBlock's name takes the BuildContext. Learn's screens use
LearnContentEditor and LearnContentView, which add Learn's blocks and the
grammar check. Learn behaves as before.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-11-06 21:25:44 +01:00
[`halkyon_editor` ](packages/halkyon_editor/README.md ) (rich text: the editor, its view
and the document they keep),
2026-10-19 20:39:09 +02:00
[`halkyon_core` ](packages/halkyon_core/README.md ) (low-level primitives) and
[`halkyon_interop` ](packages/halkyon_interop/README.md ) (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.
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
One pub workspace holds every package: one `pubspec.lock` , one version of each dependency.
[Melos ](https://melos.invertase.dev ) runs scripts across them.
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
## Getting started
2026-09-30 15:13:34 +02:00
2026-10-30 17:43:24 +01:00
- **Flutter v3.47.8**, the version CI uses (`FLUTTER_VERSION` in
2026-10-19 20:39:09 +02:00
`.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.
2026-09-30 15:13:34 +02:00
```sh
2026-10-19 20:39:09 +02:00
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
2026-09-30 15:13:34 +02:00
```
2026-10-19 20:39:09 +02:00
`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` ](AGENTS.md ) and each app's own.
docs: the README's aims, developer setup and releases
The README opens with what the app aims at: creating, sharing and
collaborating on study material, FSRS for retention, study material
organised with its external references, offline-first, and a transparent
stack anyone can host.
"Setting up" lists what developers need: Flutter as CI pins it, with
Flutter's own guide per platform; the Serverpod CLI; the Linux packages,
with what each plugin needs them for; Developer Mode on Windows, and why;
no Docker for development; Python for the scripts in tool/.
"Releases" says where releases are published, how to check a download
(the signed checksums, the APK certificate's fingerprint), how versions
are numbered, and how a maintainer makes one with tool/release.sh.
AGENTS.md: Windows needs Developer Mode for Flutter's plugin links too,
not only for pdfrx's build.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Tizian 「ティツィアーン」 <raisondetredev@pm.me>
2026-10-05 17:00:27 +02:00
2026-10-19 20:39:09 +02:00
## Licences
2026-09-30 15:13:34 +02:00
2026-10-19 20:39:09 +02:00
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
2026-10-19 21:56:12 +02:00
License 3.0 or later. [`LICENSE.md` ](LICENSE.md ) says
2026-10-19 20:39:09 +02:00
which covers what, [`CONTRIBUTING.md` ](CONTRIBUTING.md ) how to contribute.
