Skip to content

System Architecture

Jump to bottom
DIIZZYFPS edited this page Mar 5, 2026 · 1 revision

System Architecture

sAIve is a local-first, privacy-focused desktop application built with a modern, decoupled Electron architecture. It consists of two main autonomous processes running on the user's local machine: the React Frontend and the FastAPI Backend.

High-Level Topology

graph TD
    %% User interacts with the UI
    User((User)) -->|Interacts| UI[React UI / Electron]
    
    %% UI interactions
    subgraph Frontend [Frontend Application]
        UI -->|Reads/Writes| RQ[React Query Cache]
        UI <-->|Messages| Worker[AI Web Worker]
        Worker <-->|Inference| WebGPU[WebGPU / Gemma 3 Model]
        RQ -.->|Subscribes| SSEClient[SSE Event Listener]
    end
    
    %% API and Real-Time Comms
    RQ -->|HTTP REST| API[FastAPI Server]
    Worker -->|FastMCP Tools| API
    API -->|SSE Events| SSEClient
    
    %% Backend Application
    subgraph Backend [Backend Service]
        API -->|Validates| Pydantic[Pydantic / Bleach]
        Pydantic -->|CRUD| DB[(SQLite Database)]
        DB -->|Returns Data| API
        
        %% Automated background worker
        BG[Background Auto-Processor] -->|Sleep 30s Loop| DB
        BG -->|Emit| API
    end
    
    %% Storage boundary
    DB -.->|Persists to| FS[OS User Data Directory]
Loading

Core Components

1. The Electron Shell (Distribution & OS Integration)

Electron serves as the host environment. Unlike older Electron apps that bundle Python inside Node.js, sAIve takes a decoupled approach:

  • Electron spawns the compiled Python executable (PyInstaller binary) as a completely separate child process.
  • The Python process binds to a random open port and communicates this to Electron via standard output (PORT:<number>).
  • Electron passes this port into the React application's environment, allowing Axios to know exactly where to send API requests without port conflicts.

2. The Frontend (React + Vite + TypeScript)

  • State & Caching: Managed almost entirely by TanStack Query (React Query).
  • Styling: TailwindCSS and Shadcn UI.
  • Real-Time Data Sync: Replaces deep optimistic UI updates with a Server-Sent Events (SSE) listener. When the backend fires an invalidation event (e.g. transactions_changed), React Query targetedly refetches only the necessary queries.
  • Local AI Engine: Hugging Face Transformers.js runs Google's Gemma 3 270M (Int4) inside a dedicated Web Worker. The Web Worker ensures intense calculations (token generation) never block the React main thread, keeping animations smooth. WebGPU is leveraged for hardware acceleration.

3. The Backend (FastAPI + Python)

  • API Engine: FastAPI handles RESTful routing and automatic OpenAPI documentation.
  • Security: All inputs are passed through Pydantic models. Strings representing user-input (like recipient) are sanitized with bleach to strip HTML/scripts, neutralizing stored XSS.
  • Database: SQLite is used for persistent local storage. The .db file is routed to the OS-native application data folder (e.g. %APPDATA% on Windows) so it survives application updates.
  • MCP Server: FastMCP is natively embedded and mounted directly to FastAPI. It exposes a suite of tools directly to the frontend's AI Worker, allowing the AI to request exact data or execute state changes without scraping HTML.
  • Background Processor: A continuously running async loop inside FastAPI evaluates recurring transactions every 30 seconds, inserting them into the ledger and issuing notifications automatically.

Clone this wiki locally