max / balanced_breakfast
git clone https://makenot.work/git/max/balanced_breakfast.git
git clone git@ssh.makenot.work:max/balanced_breakfast.git
| Name | Size | |
|---|---|---|
| crates/ | ||
| docs/ | ||
| migrations/ | ||
| plugins/ | ||
| scripts/ | ||
| src-tauri/ | ||
| .env.example | 177 B | |
| .gitignore | 303 B | |
| app-icon.png | 51.4 KB | |
| BalancedBreakfast-Pitch.pdf | 8.6 KB | |
| Cargo.lock | 172.1 KB | |
| Cargo.toml | 1.6 KB | |
| CHANGELOG.md | 933 B | |
| CONTRIBUTING.md | 8.7 KB | |
| generate_pitch_pdf.py | 16.1 KB | |
| LICENSE | 4.3 KB | |
| logo.svg | 1.5 KB | |
| README.md | 5.1 KB | |
| synckit.toml | 504 B |
README
Balanced Breakfast
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.
Prerequisites
- Rust (stable toolchain, 2021 edition)
- Tauri 2 CLI (
cargo install tauri-cli --version '^2') - Linux only: system dependencies for WebKitGTK
# Debian/Ubuntu sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \ libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev # Arch sudo pacman -S webkit2gtk-4.1 base-devel curl wget file openssl \ appmenu-gtk-module libappindicator-gtk3 librsvg2-dev - macOS / Windows: no extra system dependencies beyond Rust and the Tauri CLI.
Build and Run
# Development (hot-reload frontend, debug backend)
cargo tauri dev
# Production build (macOS DMG, Windows installer, Linux AppImage)
cargo tauri build
# Run all workspace tests
cargo test --workspace
Workspace Architecture
The project is a Cargo workspace with four library crates and one application crate:
| Crate | Path | Role |
|---|---|---|
bb-interface | crates/bb-interface/ | Shared types for the plugin system: FeedItem, FetchResult, ConfigSchema, ConfigField, BusserCapabilities. Defines the contract between plugins and the host. |
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. |
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). |
bb-db | crates/bb-db/ | SQLite persistence via sqlx. Repositories for feeds, items, tags, and busser key-value state. FTS5 full-text search. |
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). |
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.
Shared libraries from ../MNW/shared/: theme-common (theme loading), tagtree (tag validation), synckit-client (cloud sync SDK).
Features
- Unified timeline – RSS, Atom, JSON Feed, Hacker News, arXiv, and custom sources merged into one feed
- Plugin system – Rhai scripting for extensible feed fetching (write a plugin for any source)
- Reader view – clean article rendering with HTML sanitization via DocEngine
- Search – FTS5 full-text search across all items with sanitized indexing
- Organization – tags, starred items, read/unread tracking, query feeds (saved dynamic filters)
- Auto-fetch scheduling – configurable per-plugin fetch intervals, circuit breaker after consecutive failures
- Feed health tracking – visual status indicators (green/yellow/red) per source
- Cloud sync – SyncKit integration with E2E encryption (feeds, tags, read state, preferences)
- OTA updates – background update checker with consent dialog (Tauri updater v2)
- 17 bundled themes – dark, light, and high-contrast variants in TOML format, system auto-detection
- Platforms – macOS, Windows, Linux (native via Tauri 2)
Plugin Authoring
Plugins (“bussers”) are .rhai script files. Drop one into the plugins directory and it loads on next launch.
- Dev:
plugins/at the project root - Prod:
<app_config_dir>/plugins/(e.g.~/Library/Application Support/com.balancedbreakfast.app/plugins/on macOS)
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.
Bundled Plugins
Eleven plugins ship with the app:
| Plugin | Source |
|---|---|
rss.rhai | RSS, Atom, and JSON Feed |
hackernews.rhai | Hacker News stories |
arxiv.rhai | arXiv papers |
reader.rhai | Web page reader view |
github_trending.rhai | GitHub trending repositories |
devto.rhai | Dev.to articles |
lobsters.rhai | Lobsters community |
xkcd.rhai | XKCD comics |
nasa_apod.rhai | NASA Astronomy Picture of the Day |
earthquakes.rhai | USGS earthquake data |
nws_alerts.rhai | National Weather Service alerts |
Key Paths
| What | Where |
|---|---|
| Plugin contract types | crates/bb-interface/src/ |
| Plugin runtime + orchestrator | crates/bb-core/src/ |
| Feed aggregation | crates/bb-feed/src/ |
| Database layer | crates/bb-db/src/ |
| Tauri commands | src-tauri/src/commands/ |
| Frontend JS | src-tauri/frontend/js/ |
| Styles | src-tauri/frontend/css/styles.css |
| Bundled plugins | plugins/ |
| Plugin authoring guide | docs/plugin_authoring.md |
| Architecture | docs/architecture.md |
License
PolyForm Noncommercial 1.0.0