District Core for Rust

The shared Rust core of the District AI desktop apps: the data types, the HTTP client, sign-in, live updates, the application state and the call engine of District AI, the AI voice receptionist from Distronode, with no user interface toolkit in any of it.

Status: 7.0.1 is the current release (7.0.1). District AI for Linux 3.2.0 and District AI for Windows 3.2.0 are built on 7.0.0, and Linux's main branch has moved to 7.0.1. The core was extracted from District AI for Linux 2.1.0 with its history. See the CHANGELOG.

Links: project page, GitLab mirror (read-only mirror; issues and pull requests live on GitHub), CHANGELOG.

Who uses it

Two apps build on these crates, and each pins them by tag:

• District AI for Linux, a GTK 4 and libadwaita app.
• District AI for Windows, a WinUI 3 app that reaches the core through a UniFFI layer of its own.

The District AI service the crates talk to is not open source; signing in needs a District AI account. Without one you can still build the crates and run every test.

Without an account with us. Today the District AI apps need a District AI account to sign in. We want them to work without an account with us too. We have not worked out what that looks like or whether it can work, and the answer depends on what people would use them with, so we are asking before we build anything: tell us what you would connect them to.

The core is shaped so that an app decides nothing. Model::update takes an Event and returns the Effects to run next, plain data; an EffectRunner runs each effect against ten traits (the API, sign-in, settings, opening a link, the clock, live updates, notifications, presence, the call engine and the ring) and turns its result into the next event. The app renders the model, forwards what the user does as events, and implements the few traits only its system can (the secret store, notifications, the ring, opening a link). The crate documentation of district-core has the whole shape.

The crates

Crate	What it holds
district-model	Serde data types for the District AI API, mirroring the Android app's core model, and the live telemetry envelopes. Platform and ClientIdentity name the app on the wire. No IO.
district-api	The HTTP client and the endpoint table. A bearer token and an explicit workspace on every call, no cookie store, redirects never followed, rustls.
district-auth	Sign-in with OAuth 2.0 and PKCE through the system browser, the token exchange, single-flight refresh-token rotation, sign-out.
district-live	The live telemetry WebSocket client.
district-core	App state with no user interface toolkit and no IO of its own: the session, routes, role capabilities, a model per screen, and the effect runner with the traits an app implements.
district-host	What a desktop app keeps on the machine and how it hears the machine sleep, on any operating system: the device id, the refresh marker, the settings file and the sleep protocol.
district-l10n	Every sentence and label the crates write, in English and Canadian French: the catalogs in catalog/, the code generated from them, the labels of the values the service stores, and the date, number, money and duration formats, held to the service's own outputs in contracts/i18n/. The app chooses the language (CoreConfig::locale).
district-crash	Opt-in crash reports, sent only once the app passes a DSN and the user's consent. A report holds a panic or an error the app captures, its stack, the operating system and Rust version, the release, and the debug images of the app's own executable and library (ids, address, size, architecture) so a stripped build can be symbolicated; no other loaded library, no machine name, user or address, and every home directory path with the user's name replaced. Its own crate, so an app that does not offer crash reports builds no Sentry code.
district-call	The call engine: LiveKitCallEngine behind the optional livekit feature (it links libwebrtc), and UnavailableCallEngine without it, which joins nothing and says so.

contracts/ holds what the crates are tested against: the District AI server's recorded responses (vendored and sanitised), the Android app's endpoint list and the brand colours from the design tokens. CONTRIBUTING.md says where each comes from.

Using it from an app

None of the crates is published to crates.io. An app depends on them by git tag, with the exact version beside the tag so that Cargo refuses a tag that does not hold that version:

[workspace.dependencies]
district-model = { git = "https://github.com/distronode-corporation/district-core-rust", tag = "v7.0.1", version = "=7.0.1" }
district-core = { git = "https://github.com/distronode-corporation/district-core-rust", tag = "v7.0.1", version = "=7.0.1" }

and so on for each crate it uses, all at the same tag. Cargo.lock then records the commit the tag named, and --locked holds the build to it. A breaking change to anything an app calls or implements takes a new major version (CHANGELOG.md says what counts).

log is a dependency for its max_level_warn feature only, which compiles every log line below warn out of the whole build, the app's own crates included; see SECURITY.md for why.

Build and test

Requirements: Rust 1.92 or newer (via rustup; the repository pins the stable channel) and a C compiler and linker for the TLS library (build-essential on Debian and Ubuntu, the Visual Studio Build Tools on Windows). No OpenSSL is needed: HTTPS is rustls. No user interface toolkit, no display and no network are needed to run the tests.

git clone https://github.com/distronode-corporation/district-core-rust
cd district-core-rust
cargo test --workspace --locked

On Windows, set AWS_LC_SYS_PREBUILT_NASM=1 first, so the TLS library uses its prebuilt assembly rather than looking for NASM; CONTRIBUTING.md has the details. Building the call engine (--features district-call/livekit) links libwebrtc and needs more; CONTRIBUTING.md has the steps.

Contributing, security and conduct

• CONTRIBUTING.md: the layout, the local checks CI runs, the coverage floors, and the commit message rule.
• SECURITY.md: report vulnerabilities privately through GitHub's private vulnerability reporting, not in a public issue. It also describes what these crates guarantee about sign-in, tokens, requests and logging.
• CODE_OF_CONDUCT.md: everyone taking part is expected to follow it.
• SUPPORT.md: where questions, bugs and product support go.

License and trademarks

Apache License 2.0. See LICENSE and NOTICE. Third-party dependencies keep their own licences.

District AI, Distronode and the District AI and Distronode logos are trademarks of Distronode Corporation. They are not licensed under the Apache License 2.0.

This project is not affiliated with or endorsed by LiveKit.