Start here: a map of the code¶

This page is for developers who know how to program but have not worked with Rust, Qt Quick (QML), CXX-Qt, Fluent or Android. It says what Sioul is made of, how a click in the window becomes a change on disk and a sentence on the screen, what runs in the background, where to start reading, and what Sioul's own words mean.

The guides after it go further, one subject each:

• Rust, as Sioul uses it: the workspace, the crates, errors, files, time, threads and tests.
• Qt Quick and QML, as Sioul uses them: the pages, their properties and bindings, how they are made, desktop and phone.
• The bridge: CXX-Qt: how QML calls Rust, and how Rust's results come back.
• Strings: Fluent: how every sentence is written, in English and French.
• Android, as Sioul uses it: the app, its processes, its services, and Java talking to Rust.
• A feature, end to end: one small feature followed through every layer, and the checklist for adding one.

How to build and run Sioul: Building and running. Why each part is as it is: the design notes beside these guides, starting with the design and architecture.

What Sioul is made of¶

Sioul is one Cargo workspace (Cargo is Rust's build tool; a workspace is a set of packages built together, declared in the root Cargo.toml). It holds five crates (Rust packages), and the files they build in or read.

How the crates depend on each other:

• sioul-core uses no other crate of Sioul's.
• sioul-sync uses sioul-core.
• sioul-learn uses sioul-core and sioul-sync.
• sioul-cli and sioul-app, the two programs, use the core and sync, and sioul-learn on computers only (Android's build never compiles it); the window also uses Qt, through CXX-Qt.

cargo build at the root builds the core, sync, the command line and sioul-learn; the window is built only when asked for (cargo build -p sioul-app), because it needs Qt's development files (building.md).

The rule of the layers¶

Rust decides and words; QML lays out. The rules, and the sentences, are written in Rust: in sioul-core above all (view.rs, taskview.rs and their neighbours), so that the command line, the window and AI agents see the same thing (architecture.md). The window's own Rust side (crates/sioul-app/src/) gathers what the pages need, starts the slow work, and words a few lines of its own with the same translator. The QML shows the text it is given, chooses what goes where on the screen, and calls Rust when you act. When you look for where something is decided, look in crates/sioul-core/src/ first.

Plain files hold the data. Mail is in Maildir folders; events, tasks and contacts are one .ics or .vcf file each; notes are Markdown; settings and Sioul's own state are TOML (architecture.md, "Storage"). There is no database: each module reads the files it needs, and writes them back whole, or edits them in place, keeping what it does not know (your comments, other programs' fields).

How a click becomes an action and a sentence¶

The Porch's Done for now button closes the Porch on what it showed. Followed through each layer:

1. QML (crates/sioul-app/qml/PorchPage.qml): the button's label is a sentence asked of the core by its name, and its click calls the bridge object, which every page receives as sioul:

   Button {
       visible: page.view.open && page.view.lanes.length > 0
       Layout.topMargin: page.theme.gap
       text: page.sioul.text("ui-done")
       onClicked: {
           page.openKey = ""
           page.sioul.done()
       }
   }
   

2. The bridge (crates/sioul-app/src/backend.rs): done is a Rust method that QML can call (an invokable, cxx-qt.md). It runs on the window's thread. It loads the Porch's memory, marks the newest message shown for each account, saves it, and puts a sentence in the status line:

   fn done(mut self: Pin<&mut Self>) {
       let shared = self.shared();
       let newest = shared.shown.lock().map(|s| s.clone()).unwrap_or_default();
       let path = PorchState::default_path();
       let mut state = PorchState::load(&path);
       state.close(&newest);
       let line = match state.save(&path) {
           Ok(()) => tr().text(if newest.is_empty() { "done-nothing" } else { "done-closed" }, None),
           Err(e) => e,
       };
       shared.opened_anyway.store(false, Ordering::Relaxed);
       self.as_mut().set_status(QString::from(&line));
       show(&self.qt_thread(), &shared);
   }
   

3. The core (crates/sioul-core/src/state.rs): PorchState is a plain Rust struct that serde turns into TOML. save writes porch.toml in Sioul's state folder (sioul_core::config::state_dir: $XDG_STATE_HOME/sioul, on Linux ~/.local/state/sioul when that variable is not set): beside it first, then renamed over it, so that a crash never leaves half a file.

4. The sentence (crates/sioul-core/locales/en/sioul.ftl): tr().text("done-closed", None) looks the message up in the language of the session, through Fluent (fluent.md): "Done. What comes next waits for the next window." in English, « C’est fait. Ce qui arrive maintenant attend la prochaine fenêtre. » in French. Setting the status property tells QML, and the status line shows it.
5. Back to the screen: show computes the Porch again on another thread (compute, which calls sioul_core::porch::gather and sioul_core::view::porch), turns the result into JSON, and hands it back to the window's thread, which sets the porch property. PorchPage.qml hears that the property changed (onPorchChanged), reads it, parses it with JSON.parse, and every binding that reads it draws again: what was shown has left the lanes, and only what came after it stays.

Every feature follows this path: QML calls an invokable; the invokable asks the core (and, for the network, sync); the core reads and writes plain files and returns facts already in words; the result comes back as a property (usually a JSON text) or as the invokable's return value; QML lays it out. A feature, end to end follows a whole feature this way, with its test and its documentation.

What runs in the background¶

• The window's thread draws, runs QML and runs every invokable. Nothing slow may run there: the window would freeze.
• Threads for the pages: each set of pages (the Porch and budgets, mail, the agenda and contacts, tasks and notes, health) is computed on a thread of its own, one computation at a time, then handed back to the window's thread (backend::coalesced, cxx-qt.md).
• One watcher per mail account: a thread that keeps the inbox open with IMAP IDLE and fetches what arrives (backend::start_watcher, sioul_sync::watch). Calendars and contacts have their own (pim::start_dav_watchers).
• The window's minute: qml/Clock.qml turns at each minute, and main.qml then calls sioul.refreshMode() (refresh_mode in backend.rs), which starts the minute's work: doses and errands to remind, the pauses, the exchange with your other devices, reminders before dates, new mail's notification at its time, the end of the work day, the weather.
• Without the window, on a computer: the window can hide in the system tray and go on. sioul remind --watch tells reminders with the window closed (started with the session when asked in Settings), and sioul watch keeps the inboxes open from a terminal (building.md, "First steps").
• Without the window, on a phone: Android freezes an app it does not show. Alarms given ahead to Android start receivers that load Sioul's Rust library without its window; a service in a process of its own keeps the phone in step with your other devices; calls and other apps' notifications are screened in processes of their own (android-basics.md, android.md).
• async only in the network code: IMAP, SMTP and DNS are asynchronous (tokio) inside sioul-sync, but its functions that reach a server make their own small runtime and wait for it, so their callers see ordinary blocking functions (rust.md).

Where to start reading¶

1. crates/sioul-core/src/lib.rs: the list of the core's modules. Each module begins with a comment (//!) that says what it does, often with the design note it follows.
2. crates/sioul-core/src/porch.rs and view.rs: how mail is judged and sorted, and how the Porch becomes words. The test crates/sioul-core/tests/porch.rs sorts a morning of invented mail and checks every lane.
3. crates/sioul-app/src/lib.rs: how the window starts (run).
4. The top of crates/sioul-app/src/backend.rs: the bridge, the list of what QML can read and call.
5. crates/sioul-app/qml/main.qml: the window, the places on the left, the pages made as they are first shown; then any page, such as PorchPage.qml.
6. crates/sioul-core/locales/en/sioul.ftl: a message's name in QML or Rust leads to its words here.
7. For the phone: android/main.cpp, then android/package/AndroidManifest.xml, then the Java class the manifest names for what you look at.

To find where something on the screen is made, search its words in en/sioul.ftl, take the message's name, and search that name in crates/ (grep -rn '"done-closed"' crates/).

Sioul's words¶

Sioul has its own names for its parts. The design notes use them without explaining them each time.