Bella Assist

Bella Assist is a local-first desktop application that integrates an AI personal assistant with multi-period budgeting, asset and liability tracking, and semantic search. The application is built using a clean-architecture backend in FastAPI, a React interface packaged inside Electron, and custom Model Context Protocol (MCP) servers.

---

Live User Journey Showcase

Explore the interactive application showcase rendered directly below, featuring full screen navigation, light/dark theme switching, budget visualizations, net worth trajectories, and AI chat capabilities.

• Open Showcase in Fullscreen — Open the live showcase in a dedicated browser tab.
• GitHub Repository — Access source code, issue tracker, and releases.

---

Deployed Documentation

To ensure smooth documentation reuse and prevent content duplication across repositories, technical specifications, user manuals, and developer guidelines are maintained and deployed directly alongside the application source code.

User Guides & Manuals

• User Setup & Installation Guide — Native host prerequisites, PostgreSQL/Ollama initialization, and Docker deployment scripts.
• Authentication & Security Guide — SSO identity management, JWT access tokens, HttpOnly refresh cookies, and token rotation.
• Wealth Manager Guide — Asset trackers, interest-bearing liabilities, EMI projections, and net worth trajectory models.

Developer & Architecture Specifications

• System Architecture & Coding Standards — Layered Clean Architecture rules, stateless containers, and backend standards.
• Developer Workflow — Monorepo layout, local execution scripts, dependency management, and linting standards.
• MCP Authorization Specification — Security boundaries, bearer token verification, and FastMCP integration design.
• Frontend & UI Guidelines — React 18/19, Material UI v6 design system, accessibility, and UI Guidelines.
• Testing Guidelines — Async unit testing, integration test suits, and pytest conventions.

---

Deployment Architecture

Bella Assist uses a hybrid local architecture: stateless application logic runs within containerized Docker environments while all stateful user data (PostgreSQL databases, Qdrant vector store, and Ollama model inference) is maintained directly on the host machine to ensure privacy and data sovereignty.

---

Core Components

1. Desktop Client (Codebase) 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 (Codebase) Clean Architecture FastAPI service for budgeting, savings envelopes, and account tracking. Backed by async SQLAlchemy and PostgreSQL.

3. Authentication Service (Codebase | Guide) FastAPI identity manager handling registration, login, and secure sessions via token rotation and HttpOnly cookies.

4. Bella Chat Service (Codebase) 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.

5. EMS MCP Server (Codebase | Specification) FastMCP service exposing EMS financial data as read-only LLM-callable tools over streamable HTTP.

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