# atlas-framework-system

> The Rust crate for Atlas system apps, with opt-in crash reports, AtlasOS state \(bootc status, boot history, update events\), polkit checks for root helpers and desktop notifications.

`atlas-framework-system` is for apps that work with the AtlasOS system: Atlas Updater, Atlas Monitor and the root helper behind them. It holds opt-in crash reports (the only telemetry an Atlas app may have), the types and files that describe the AtlasOS image state, a polkit check for root D-Bus helpers, and desktop notifications.

A light app can use [`crash`](https://atlasos.eterneon.net/framework/atlas-framework-system/crash.md) alone: only the `polkit` and `notify` features bring in D-Bus. [atlas-framework-ui](https://atlasos.eterneon.net/framework/atlas-framework-ui.md) already depends on this crate (without the features) for the crash hooks, so a GUI app gets `crash` without adding anything.

## Add it

```toml
atlas-framework-system = { git = "https://github.com/EternalCoder454/atlas-framework", rev = "7a114a112bd1fff4fe3d6facc81b0a81e5d2db30", features = ["notify"] }
```

The commit is the one tagged `v1.4.0`. Pin apps to a commit or a release tag and build with `cargo build --locked`. Leave out `features` if the app needs neither feature.

## Features

| Feature | Default | What it adds |
|---|---|---|
| `polkit` | off | The [`polkit`](https://atlasos.eterneon.net/framework/atlas-framework-system/polkit.md) module: the authorization check for a root helper. Pulls in `zbus` and `tokio` |
| `notify` | off | The [`notify`](https://atlasos.eterneon.net/framework/atlas-framework-system/notify.md) module: desktop notifications over `org.freedesktop.Notifications`. Pulls in `zbus` and `tokio` |

## Pages

| Page | What it covers |
|---|---|
| [crash](https://atlasos.eterneon.net/framework/atlas-framework-system/crash.md) | Opt-in crash reports: settings, endpoint, scrubbing, collecting, sending |
| [history](https://atlasos.eterneon.net/framework/atlas-framework-system/history.md) | The versions this machine has booted |
| [bootc](https://atlasos.eterneon.net/framework/atlas-framework-system/bootc.md) | Types for `bootc status --json` and the channel tag rewrite |
| [events](https://atlasos.eterneon.net/framework/atlas-framework-system/events.md) | Update and rollback events the system helper records |
| [polkit](https://atlasos.eterneon.net/framework/atlas-framework-system/polkit.md) | The authorization check for a root D-Bus helper (feature `polkit`) |
| [notify](https://atlasos.eterneon.net/framework/atlas-framework-system/notify.md) | Desktop notifications the way KNotification sends them (feature `notify`) |
| [On-disk formats](https://atlasos.eterneon.net/framework/atlas-framework-system/formats.md) | Every file these modules read or write, with paths and fields |

## Crate root

| Name | Kind | Description |
|---|---|---|
| `bootc`, `crash`, `events`, `history` | modules | Always available |
| `notify` | module | Feature `notify` |
| `polkit` | module | Feature `polkit` |


## Pages

- [crash](https://atlasos.eterneon.net/framework/atlas-framework-system/crash.md): Opt-in crash reports, the only telemetry an Atlas app may have, with the per-user switch, the endpoint, scrubbing, the pending queue and sending after the user has seen the exact payload.
- [history](https://atlasos.eterneon.net/framework/atlas-framework-system/history.md): The record of AtlasOS versions this machine has booted, one JSON line each, and the helpers that read and append to it.
- [bootc](https://atlasos.eterneon.net/framework/atlas-framework-system/bootc.md): Typed views of bootc status --json for AtlasOS \(booted, staged and rollback images, the update channel and available updates\) and the channel tag rewrite.
- [events](https://atlasos.eterneon.net/framework/atlas-framework-system/events.md): The update and rollback events the AtlasOS system helper records, one JSON line each, and the functions that read and append them.
- [polkit](https://atlasos.eterneon.net/framework/atlas-framework-system/polkit.md): The polkit authorization check behind every admin action of an Atlas root D-Bus helper, failing closed, available with the polkit feature.
- [notify](https://atlasos.eterneon.net/framework/atlas-framework-system/notify.md): Desktop notifications over org.freedesktop.Notifications, sent the way KNotification sends them so Plasma groups them under the app and honours the user's per-event choice, with the notify feature.
- [On-disk formats](https://atlasos.eterneon.net/framework/atlas-framework-system/formats.md): Every file the system crate and the core crate read or write for other programs, with exact paths, keys, fields and permissions, and the format-version rule.