Architecture¶

Layers¶

• sioul-core, a Rust library: reading and judging mail, projects, the Porch, admin windows, contacts and calendars, tasks (tasks) and their plan (plan), notes (notes), links between everything (links), time spent (timelog), budgets, health, the spam filter every device runs (spam: its tokenizer, the messages' features, the table that scores them), translations. Everything the interface shows is decided and worded here (view, taskview), so the command line, the Qt interface and AI agents see the same thing.
• sioul (crates/sioul-cli): the command line, first because agents and scripts use it too.
• The Qt 6 interface (QML) through CXX-Qt (KDAB; bridge API stable since 0.7, 0.10 in 2026). The sites (once called portals) use Qt WebEngine, on computers. The interface holds no logic. It is a library (crates/sioul-app/src/lib.rs), which the desktop program and Android's both run.
• sioul-sync, the background service's library: finding servers, the keyring, IMAP sync and what you do to messages on the server, sending through SMTP, IDLE watchers, the notifications, CalDAV and CardDAV, Google, GitHub, Bitwarden, the sharing between your devices (share). The window runs its watchers; without it, sioul watch keeps the inboxes open and sioul remind --watch tells reminders; on Android, a service of its own keeps the phone in step (android.md).
• sioul-learn, on computers only: the spam filter's training, on your own mail; it writes the table every device reads. Still being built.
• Android (android/): Qt for Android builds the window into an app; Java classes run what Android starts while the window is away (alarms, a background service, call screening, other apps' notifications), and ask Rust through android/main.cpp (android-basics.md, android.md).
• An MCP server for agents (ai.md).

New to Rust, Qt Quick, CXX-Qt, Fluent or Android? Start here maps the code, and the guides beside it explain each tool as Sioul uses it, up to a feature followed end to end.

Storage: plain files wherever possible¶

• Mail: Maildir, readable by notmuch and mutt.
• Calendars and contacts: vdir, one .ics or .vcf per item, as pimsync and khal use.
• Tasks: VTODO files in the calendars' vdir; their links inside them (RFC 9253). Links between things that cannot hold them: links.toml. Time spent: one TOML file per month. Today's choices (weather, "not now"): today.toml in the state folder. SQLite and tantivy wait until plain files are too slow.
• History: a file another device changes is kept as it was, on this device, to be put back (database.md).
• Between your devices: what only Sioul keeps (settings, senders, time, health…) travels as sealed records, one file per device, through a folder your sync app carries (database.md).
• Projects: your own Markdown files, and one file that names them (notes-folder.md).

Protocols¶

• Mail: IMAP (RFC 9051, IDLE, CONDSTORE/QRESYNC), JMAP (RFC 8620/8621), SMTP submission.
• Calendars and contacts: CalDAV (RFC 4791) and CardDAV (RFC 6352), through a small client of Sioul's own (sioul_sync::dav). Tasks are VTODO with RFC 9253 relationships.
• Discovery: Mozilla ISPDB and providers' autoconfig, SRV records (RFC 6186), DAV well-known URLs (RFC 6764).
• What is built of these, what each feature needs from a server or another program, and how far each was tried: compatibility.md. Not built yet: CONDSTORE and QRESYNC to keep folders in step (CONDSTORE serves only the filters' claim on a message), JMAP, SRV records.

Crates, and their licences¶

Qt is LGPL-3.0. Every licence above is compatible with Sioul's, GPL-3.0-or-later.

Platforms¶

• Linux first: a Flatpak and an AppImage, made for each version by .github/workflows/release.yml.
• Windows: an installer, Qt beside the program. Maildir puts : in file names, which Windows forbids: there Sioul writes ! instead, as mbsync does, and reads both (sioul_core::maildir::INFO).
• macOS: one .dmg for Apple silicon and Intel, signed ad hoc, not notarised.
• Android, an experiment, packaged since version 0.0.2: an APK for 64-bit phones, Android 9 and later. Qt for Android, with the same window; sites open in the browser and PDFs in another app, since Qt WebEngine and Qt PDF do not exist there; Java for what Android starts without the window (android-basics.md, android.md).
• Built on each push to main that changes the code: .github/workflows/build.yml builds and tests on Linux, Windows and macOS (and checks the code's rustdoc on Linux), .github/workflows/android.yml builds the APK.

Known hurdles¶

• Gmail: full IMAP through OAuth is a restricted scope. Sioul's own key needs Google's restricted-scope review before it can ask for it; an unverified app lets 100 people in at most. Meanwhile, app passwords work, and so does signing in with Google with a key of your own (google.md, "Mail").
• Proton: IMAP needs Bridge, a paid feature. On the free plan Proton is a portal.
• Spamhaus: queries through public DNS resolvers are refused; the free Data Query Service key works.

Code style¶

• One task per function; early exits only for "nothing to do".
• Comments give the reason and the reference: the RFC, the paper, the document.
• Every rule the interface applies has a test, on invented mail using reserved example domains (RFC 2606) and no personal data.