Saga Reader Documentation

The Frontend Presentation Domain serves as the user interaction entry point for Saga Reader. It is responsible for presenting core system features—such as content aggregation, AI enhancement, local search, and theme switching—through an intuitive and responsive interface.

Technical Stack:

• SvelteKit
• TypeScript
• Tailwind CSS

Core Responsibilities:

• Rendering: Visualizing data provided by the state management domain.
• Interaction: Capturing user actions (clicks, inputs, toggles) to trigger backend services.
• Feedback: Providing immediate UI feedback via loading states, error messages, and empty states.
• Consistency: Ensuring visual and linguistic uniformity through internationalization (i18n) and theme systems.

Architecture & Data Flow: The frontend follows a component-based, reactive, and state-driven architecture featuring a three-column reading workspace. It is deeply coupled with the state management domain. All data changes are driven by Svelte Stores, and all user operations are executed via a bridge layer that calls backend Rust services.

The complete data loop is: UI → Store → Bridge → Rust → DB → Store → UI

Saga Reader is an AI-driven, lightweight, and fast internet reader. It automatically retrieves information from the web based on user-specified topics and preference keywords.

Key capabilities include:

• AI-Powered Summarization: Uses cloud or local Large Language Models (LLMs) to summarize content and provide guidance.
• Interactive Reading: An AI companion allows users to discuss and exchange ideas about the reading material in real-time.
• Privacy-First: All data is stored locally on the user's computer, ensuring security and independence from third-party providers.
• Smart Subscriptions: Users define interest keywords to trigger autonomous web searches without complex subscription management.
• Multi-language Support: Automatically translates hundreds of foreign language articles into the user's preferred language.
• High Performance: Built with Rust, Tauri, and Svelte, it is optimized for low resource usage (memory usage < 10MB), making it suitable for older hardware.

Saga Reader is a privacy-focused, AI-enhanced desktop reading application designed for knowledge workers, tech enthusiasts, and privacy-sensitive users. It uses a multi-layered heterogeneous architecture consisting of Svelte + Tauri + Rust to provide a fully localized experience.

Core Value Proposition

• Data Sovereignty: All content scraping, AI processing, and data storage are performed locally. No data is uploaded to the cloud.
• AI-Enhanced Reading: Uses local Large Language Models (LLMs) via Ollama to perform:
  • Purge: Removing noise like ads and navigation.
  • Optimizer: Refining language and professionalism.
  • Melt: Merging multiple articles into a single comprehensive summary.
• Interactive AI Assistant: Enables "reading as conversation" by allowing users to ask questions about the current article using a local LLM.
• Automated Workflows: A background daemon handles periodic content refreshes automatically.

Saga Reader is built using a multi-layered architecture designed for high performance and local-first privacy. The stack consists of:

• Frontend UI: SvelteKit, TypeScript, and Tailwind CSS for a responsive, componentized interface.
• Desktop Container: Tauri 2.x, which wraps the web frontend into a native desktop application with system-level API access.
• Backend Engine: Rust (1.78+) handles all core business logic, including web scraping, AI processing, database management, and background daemons.
• AI Inference: Local open-source Large Language Models (LLMs) like Llama 3, Mistral, or GLM-4, invoked via Ollama through HTTP APIs.
• Database: SQLite with SeaORM for lightweight, zero-configuration, ACID-compliant local storage.
• Configuration: TOML files managed via serde for structured, human-readable settings.
• Communication: Tauri IPC (JSON-RPC over WebSocket) provides type-safe communication between TypeScript (Frontend) and Rust (Backend).
• Build Tools: Bun and Vite for fast frontend bundling and Svelte hot-reloading.

The application uses a daemon mode to automate feed updates without a visible UI. This is implemented in app/src-tauri/src/daemon/feeds_update.rs.

Key Mechanisms:

• Process Mode Detection: The application checks for the --feeds-schedule-update command-line argument via env::is_daemon(). If present, the setup hook skips showing the main window and only runs background tasks.
• Concurrency & Safety:
  • Uses fslock (via LockFile) to create a lock file (feeds_schedule_update.lock), preventing multiple daemon instances from running simultaneously.
  • Uses async_runtime::spawn to run the schedule_loop in the background.
• Scheduled Loop:
  • Uses tokio::time::interval to trigger updates based on configuration (frequency_feeds_update).
  • Iterates through feeds_packages and calls features.update_feed_contents to trigger the scraping and AI processing pipeline.
• State Sharing: The daemon receives an Arc<HybridRuntimeState>, allowing it to access FeaturesAPI to perform business logic tasks.

// Check if running in daemon mode
pub fn is_daemon() -> bool {
    let launch_mode = std::env::args().nth(1).unwrap_or_default();
    launch_mode.eq(DAEMON_FEEDS_SCHEDULE_UPDATE)
}

// Background loop logic
async fn schedule_loop<R: Runtime>(app_handle: AppHandle, state: Arc<HybridRuntimeState>) -> anyhow::Result<()> {
    // ... interval setup
    loop {
        interval.tick().await;
        let feeds_packages = features.get_feeds_packages().await;
        for feed_package in feeds_packages {
            for feed in feed_package.feeds {
                features.update_feed_contents(&feed_package.id, &feed.id, Some(app_handle.clone())).await?;
            }
        }
    }
}

The Frontend Presentation Domain follows a strict layered architecture to ensure testability and clarity. The UI does not call backend services directly. Instead, all communication flows through a State Management Domain and a Bridge Layer.

Core Principle

• UI: Responsible only for rendering and event handling.
• State: Responsible for data flow.
• Bridge: Responsible for communication.

Common Interaction Chains