| 1 |
# Balanced Breakfast |
| 2 |
|
| 3 |
A desktop feed aggregator that unifies RSS, Hacker News, arXiv, and other sources into a single timeline. Built with Tauri 2, Rust, and a Rhai plugin system for extensible feed fetching. |
| 4 |
|
| 5 |
## Prerequisites |
| 6 |
|
| 7 |
- **Rust** (stable toolchain, 2021 edition) |
| 8 |
- **Tauri 2 CLI** (`cargo install tauri-cli --version '^2'`) |
| 9 |
- **Linux only:** system dependencies for WebKitGTK |
| 10 |
``` |
| 11 |
# Debian/Ubuntu |
| 12 |
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \ |
| 13 |
libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev |
| 14 |
|
| 15 |
# Arch |
| 16 |
sudo pacman -S webkit2gtk-4.1 base-devel curl wget file openssl \ |
| 17 |
appmenu-gtk-module libappindicator-gtk3 librsvg2-dev |
| 18 |
``` |
| 19 |
- **macOS / Windows:** no extra system dependencies beyond Rust and the Tauri CLI. |
| 20 |
|
| 21 |
## Build and Run |
| 22 |
|
| 23 |
```sh |
| 24 |
# Development (hot-reload frontend, debug backend) |
| 25 |
cargo tauri dev |
| 26 |
|
| 27 |
# Production build (macOS DMG, Windows installer, Linux AppImage) |
| 28 |
cargo tauri build |
| 29 |
|
| 30 |
# Run all workspace tests |
| 31 |
cargo test --workspace |
| 32 |
``` |
| 33 |
|
| 34 |
## Workspace Architecture |
| 35 |
|
| 36 |
The project is a Cargo workspace with four library crates and one application crate: |
| 37 |
|
| 38 |
|
| 39 |
|
| 40 |
| `bb-interface` | `crates/bb-interface/` | Shared types for the plugin system: `FeedItem`, `FetchResult`, `ConfigSchema`, `ConfigField`, `BusserCapabilities`. Defines the contract between plugins and the host. | |
| 41 |
| `bb-core` | `crates/bb-core/` | Orchestrator (feed refresh scheduling, lifecycle), Rhai plugin runtime (engine setup, script loading, host function registration), config encryption, URL tracker-stripping. | |
| 42 |
| `bb-feed` | `crates/bb-feed/` | Feed aggregation and ordering. Merges items from all active sources and applies sort modes (newest, scored, unread-first, starred-first). | |
| 43 |
| `bb-db` | `crates/bb-db/` | SQLite persistence via sqlx. Repositories for feeds, items, tags, and busser key-value state. FTS5 full-text search. | |
| 44 |
| `src-tauri` | `src-tauri/` | Tauri 2 desktop shell. Tauri commands (thin wrappers over the library crates), app state, background auto-fetch, frontend (vanilla HTML/CSS/JS). | |
| 45 |
|
| 46 |
Dependency flow: `bb-interface` is leaf (no internal deps) -> `bb-core` and `bb-feed` depend on `bb-interface` -> `bb-db` depends on `bb-interface` -> `src-tauri` depends on all four. |
| 47 |
|
| 48 |
Shared libraries from `../MNW/shared/`: [theme-common](../MNW/shared/theme-common/) (theme loading), [tagtree](../MNW/shared/tagtree/) (tag validation), [synckit-client](../MNW/shared/synckit-client/) (cloud sync SDK). |
| 49 |
|
| 50 |
## Features |
| 51 |
|
| 52 |
- **Unified timeline** -- RSS, Atom, JSON Feed, Hacker News, arXiv, and custom sources merged into one feed |
| 53 |
- **Plugin system** -- Rhai scripting for extensible feed fetching (write a plugin for any source) |
| 54 |
- **Reader view** -- clean article rendering with HTML sanitization via DocEngine |
| 55 |
- **Search** -- FTS5 full-text search across all items with sanitized indexing |
| 56 |
- **Organization** -- tags, starred items, read/unread tracking, query feeds (saved dynamic filters) |
| 57 |
- **Auto-fetch scheduling** -- configurable per-plugin fetch intervals, circuit breaker after consecutive failures |
| 58 |
- **Feed health tracking** -- visual status indicators (green/yellow/red) per source |
| 59 |
- **Cloud sync** -- SyncKit integration with E2E encryption (feeds, tags, read state, preferences) |
| 60 |
- **OTA updates** -- background update checker with consent dialog (Tauri updater v2) |
| 61 |
- **17 bundled themes** -- dark, light, and high-contrast variants in TOML format, system auto-detection |
| 62 |
- **Platforms** -- macOS, Windows, Linux (native via Tauri 2) |
| 63 |
|
| 64 |
## Plugin Authoring |
| 65 |
|
| 66 |
Plugins ("bussers") are `.rhai` script files. Drop one into the plugins directory and it loads on next launch. |
| 67 |
|
| 68 |
- **Dev:** `plugins/` at the project root |
| 69 |
- **Prod:** `<app_config_dir>/plugins/` (e.g. `~/Library/Application Support/com.balancedbreakfast.app/plugins/` on macOS) |
| 70 |
|
| 71 |
Every plugin defines four functions (`id`, `name`, `config_schema`, `fetch`) plus an optional `capabilities()`. Full authoring guide with field types, return shapes, host functions, and examples: [docs/plugin_authoring.md](docs/plugin_authoring.md). |
| 72 |
|
| 73 |
## Bundled Plugins |
| 74 |
|
| 75 |
Eleven plugins ship with the app: |
| 76 |
|
| 77 |
|
| 78 |
|
| 79 |
| `rss.rhai` | RSS, Atom, and JSON Feed | |
| 80 |
| `hackernews.rhai` | Hacker News stories | |
| 81 |
| `arxiv.rhai` | arXiv papers | |
| 82 |
| `reader.rhai` | Web page reader view | |
| 83 |
| `github_trending.rhai` | GitHub trending repositories | |
| 84 |
| `devto.rhai` | Dev.to articles | |
| 85 |
| `lobsters.rhai` | Lobsters community | |
| 86 |
| `xkcd.rhai` | XKCD comics | |
| 87 |
| `nasa_apod.rhai` | NASA Astronomy Picture of the Day | |
| 88 |
| `earthquakes.rhai` | USGS earthquake data | |
| 89 |
| `nws_alerts.rhai` | National Weather Service alerts | |
| 90 |
|
| 91 |
## Key Paths |
| 92 |
|
| 93 |
|
| 94 |
|
| 95 |
| Plugin contract types | `crates/bb-interface/src/` | |
| 96 |
| Plugin runtime + orchestrator | `crates/bb-core/src/` | |
| 97 |
| Feed aggregation | `crates/bb-feed/src/` | |
| 98 |
| Database layer | `crates/bb-db/src/` | |
| 99 |
| Tauri commands | `src-tauri/src/commands/` | |
| 100 |
| Frontend JS | `src-tauri/frontend/js/` | |
| 101 |
| Styles | `src-tauri/frontend/css/styles.css` | |
| 102 |
| Bundled plugins | `plugins/` | |
| 103 |
| Plugin authoring guide | `docs/plugin_authoring.md` | |
| 104 |
| Architecture | `docs/architecture.md` | |
| 105 |
|
| 106 |
## License |
| 107 |
|
| 108 |
PolyForm Noncommercial 1.0.0 |
| 109 |
|