Skip to content

For developers

Sioul is free software, under the GPL-3.0-or-later licence, written in Rust, with a Qt 6 window in QML. Its sources are at github.com/aurelienpierre/sioul.

This section holds the design notes of the repository's docs/ folder, as they are: what each part does, why, from which research, and where it stands. The user guide is for using Sioul; these notes are for working on it.

A few words in the notes are older than the window: a case is what the window calls a project; admin windows became working hours, hours for your admin and free time; Parameters is the Settings page.

Architecture, in brief

Part What it does
crates/sioul-core The library at the centre: reading and judging mail, the Porch, projects and their routes, areas and hours, tasks and the plan, notes, links between everything, time, budgets, the bank, papers, letters, health, reminders, translations. Everything the window shows is decided and worded here, so that the command line, the window and AI agents see the same thing.
crates/sioul-sync What talks to the world: finding servers, the keyring, IMAP sync and the actions on messages, sending, the IDLE watchers, notifications, CalDAV and CardDAV, Google, GitHub, Bitwarden, the antivirus, reading scans, sharing between computers.
crates/sioul-cli sioul, the command line, first because agents and scripts use it too; sioul mcp serves agents.
crates/sioul-app The window: Qt Quick (QML) through CXX-Qt. Its Rust side in src/, its pages in qml/, a little C++ in cpp/ (Qt WebEngine's set-up, the PDF writer, line spacing), the Breeze icons it bundles in icons/. The window holds no logic.

Storage is plain files wherever possible: Maildir for mail; one .ics or .vcf file per event, task or contact (vdir), tasks tied together as RFC 9253 says; Markdown for notes; TOML for the configuration, projects and budgets; sealed JSON lines for sharing. The whole picture, with each library and its licence: Architecture.

Every sentence goes through Fluent, in crates/sioul-core/locales/<language>/sioul.ftl, English and French; a test checks that every language has every message (Languages).

Building and testing

cargo build --release               # core, sync, command line (no Qt)
cargo test                          # their tests
cargo build --release -p sioul-app  # the window (Qt 6.9 or newer)
tools/lint-qml.sh                   # the QML, after the window
tools/check-messages.py             # every message, every language
  • What it needs, system by system: Install in the user guide, and Building and running.
  • Images of each page: SIOUL_GRAB=<folder> sioul-app shows each page in turn, saves it, and quits. With XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_STATE_HOME pointed at a test folder, it shows invented data instead of yours; without a screen, add QT_QPA_PLATFORM=offscreen QT_QUICK_BACKEND=software.
  • A demonstration, off the network: SIOUL_DEMO=1 keeps Sioul from fetching or sending anything by itself. tools/demo/make-demo.py --into <folder> writes an invented profile for it, and tools/demo/screenshots.sh takes this website's pictures from it.
  • Nothing is tested against real accounts. Writing to a mail server is tested against GreenMail, contacts and calendars against Radicale, Google Tasks and GitHub against stand-ins of their APIs (tools/), OpenPGP against GnuPG. How: Building and running.
  • Three systems: .github/workflows/build.yml builds and tests on Linux, Windows and macOS on each push to main that touches code; started by hand, it also makes a Windows folder and a macOS .dmg with Qt beside the program.

The rules of the code (Architecture): one task per function; comments give the reason and the reference (the RFC, the paper, the document); every rule the window applies has a test, on invented mail using reserved example domains (RFC 2606), and no personal data.

Where things are

Path What
crates/sioul-core/src/ the core: porch.rs, areas.rs, quiet.rs, plan.rs, tasks.rs, view.rs…
crates/sioul-core/locales/ the translations
crates/sioul-core/tests/fixtures/ invented mail, for the tests and the demonstration
crates/sioul-sync/src/ the network, the keyring, sync, sharing
crates/sioul-cli/src/ the command line; mcp/, the server for agents
crates/sioul-app/ the window: src/, qml/, cpp/, icons/
docs/ the design notes, shown in this section; docs/research/, the research behind them
examples/ a configuration, projects and budgets, and demo.toml for trying the command line on invented mail
presets/sites.json the usual sites; tools/check-presets.py checks every address
tools/ the QML linter, the messages' and the presets' checkers, the icon bundler, the API stand-ins, and demo/, the invented profile and this website's pictures
packaging/ a Flatpak manifest, a Windows installer script, the macOS steps: none built yet
data/sioul.desktop the desktop entry
website/ this website

The notes

How this website is built

  • Zensical 0.0.67. The configuration is website/zensical.toml. The user guide is written by hand in website/docs/ (index.md, guide/, privacy.md), and so is this page (website/docs/dev/index.md).
  • The notes are never copied by hand. website/build.sh copies docs/, with docs/research/, into website/docs/dev/ at each build (that folder is ignored by git, but for this page). On the copies only, links that leave docs/ (to ../examples/, ../packaging/) become their address on GitHub. It then says which notes are missing from the navigation, and builds.
  • A new note in docs/ is built with the rest; to show it in this section's sidebar, add it to the "For developers" part of nav in website/zensical.toml.

  • Locally:

    python3 -m venv <a folder outside the repository>
<that folder>/bin/pip install zensical==0.0.67
PATH=<that folder>/bin:$PATH website/build.sh          # into website/site/
PATH=<that folder>/bin:$PATH website/build.sh serve    # at http://localhost:8000/sioul/

  • Published by .github/workflows/pages.yml, on each push to main that changes website/, docs/ or the workflow, or by hand: the same build.sh --strict, then GitHub Pages.

  • Screenshots are in website/docs/assets/screens/, taken by tools/demo/screenshots.sh from an invented demonstration profile.
  • Page addresses end in .html, because docs/research.md and docs/research/README.md would otherwise both become research/index.html.

Talking about it

Questions, reports and ideas: GitHub issues. Sioul is made by one person, in the open: no support is promised.