Skip to main content

Bella Keys

Bella Keys is a privacy-first desktop application combining a personal AI assistant with multi-period expense and budget tracking. Built on LangGraph, FastAPI, React, Electron, and the Model Context Protocol.

Deployment Architecture​

Bella Keys uses an inside-out architecture: application logic runs in Docker containers while all user data (PostgreSQL, Qdrant, Ollama models) stays on the host machine. The React UI is served by nginx in web mode and connects directly to services in Electron mode.

Core Components​

  1. Desktop Client React 19 interface inside Electron, compiled with Vite and styled with Material UI v6. Served by nginx in web/Docker mode; connects directly to services in Electron mode.

  2. Expense Manager Service (Technical Details) Clean Architecture FastAPI service for multi-period budgeting, savings envelopes, and account tracking. Backed by async SQLAlchemy and PostgreSQL.

  3. Bella Chat Service (Agent Details) LangGraph create_agent orchestrator with RAG knowledge search, MCP tool use, SSE streaming, and Arize Phoenix observability. Supports Ollama (local) and Google Gemini as the LLM backend.

  4. EMS MCP Server (Server Details) FastMCP service exposing EMS financial data as read-only LLM-callable tools over streamable HTTP.

  5. ETL Pipelines (Pipeline Details) Offline ingestion job that fetches wiki docs from GitHub and loads dense vector embeddings into Qdrant.

User Workspace Showcase​

Envelope Allocations and Period Parameters

Distribute active monthly income into customized spending and savings envelopes. The table updates balances in real-time as expense items are added.

Monthly Budget

Savings Envelopes Breakdown

Monitor target progress and transaction balances dynamically for savings objectives:

Savings Envelopes TopSavings Envelopes Bottom