> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meet SAFIA: Your AI-Powered Personal Finance Assistant

> SAFIA is a self-hosted Telegram bot that tracks expenses, manages portfolios, and delivers financial insights through natural conversation on your machine.

SAFIA is an AI-powered personal finance assistant that lives inside Telegram. Instead of filling out spreadsheets or navigating complex apps, you simply chat — in whatever language feels natural — and SAFIA handles the rest. It records transactions, monitors your investments, answers financial questions, and even processes receipts from photos or voice messages. Because it runs locally on your own hardware, your financial data never leaves your machine.

## What SAFIA Can Do

<CardGroup cols={2}>
  <Card title="Expense & Income Tracking" icon="wallet">
    Record, filter, and review transactions through natural conversation. Send a receipt photo and SAFIA extracts the amount automatically.
  </Card>

  <Card title="Investment Portfolio" icon="chart-line">
    Track stocks, crypto, gold, and other assets. Get real-time pricing, portfolio summaries, and rebalancing suggestions based on your target allocations.
  </Card>

  <Card title="Debt Management" icon="handshake">
    Keep tabs on money you've lent or borrowed, with settlement tracking so nothing slips through the cracks.
  </Card>

  <Card title="Market Data" icon="globe">
    Fetch live gold, silver, crypto, and currency exchange rates on demand, sourced from multiple real-time feeds.
  </Card>

  <Card title="Auto Reminders" icon="bell">
    Schedule price alerts, daily news digests, and portfolio summaries. SAFIA can also infer reminder patterns from your habits.
  </Card>

  <Card title="Voice Messages" icon="microphone">
    Speak instead of type. SAFIA transcribes your voice messages using Whisper (via Groq) and processes them like any other message.
  </Card>

  <Card title="Knowledge Base (RAG)" icon="database">
    Upload PDF, TXT, or DOCX files to the admin dashboard. SAFIA uses those documents to ground its responses with your own reference material.
  </Card>

  <Card title="Financial News" icon="newspaper">
    Search and summarize relevant Indonesian financial news to keep you up to date with the market.
  </Card>
</CardGroup>

## Architecture: Local-First by Design

SAFIA is built around a local-first principle. The only network calls it makes are to LLM and speech-to-text APIs — every other component runs on your machine.

| Component             | Technology                               | Where It Runs                       |
| --------------------- | ---------------------------------------- | ----------------------------------- |
| LLM chat              | Lunos / Groq / OpenAI / Custom           | Remote API                          |
| Speech-to-text        | Whisper (Groq)                           | Remote API                          |
| Embeddings            | fastembed + ONNX (384-dim, multilingual) | **Local**                           |
| Vector storage        | Qdrant on-disk                           | **Local** — `data/qdrant/`          |
| Database              | SQLite (default) or PostgreSQL           | **Local**                           |
| Cache & rate limiting | In-memory + SQLite (persistent)          | **Local**                           |
| Admin UI              | Flask + Chart.js                         | **Local** — `http://127.0.0.1:5454` |
| Bot daemon            | systemd / launchd / Scheduled Tasks      | **Local** — auto-starts on boot     |

The embedding model (\~120 MB) downloads once and runs on CPU via ONNX Runtime. Qdrant writes vectors directly to disk with no separate server or Docker container needed.

<Note>
  SAFIA defaults to Bahasa Indonesia for its persona and system prompts, but it detects and replies in the language you write in. You can chat in English, Indonesian, or any other language the underlying model supports.
</Note>

## Telegram Commands

SAFIA is primarily conversational — you interact through natural language rather than slash commands. Two built-in commands are available:

| Command  | Description                                                  |
| -------- | ------------------------------------------------------------ |
| `/start` | Start the bot and reset the current chat session.            |
| `/help`  | Show the help message with an overview of what SAFIA can do. |

All other interactions happen through normal conversation. Just chat as you would with a person.

## Who SAFIA Is For

SAFIA is a good fit if you:

* Want a personal finance assistant that keeps your data on your own hardware
* Prefer managing money through conversation rather than form-based apps
* Already use Telegram daily and don't want to switch to another app
* Are comfortable running a small self-hosted service on a Linux, macOS, or Windows machine
* Want to customise the LLM provider, database backend, or knowledge base to suit your setup

<Tip>
  SAFIA requires a Telegram bot token (free, from [@BotFather](https://t.me/BotFather)) and an API key for your chosen LLM provider. No external cache server is needed — chat history and rate limits use an in-memory cache backed by SQLite, so state survives restarts.
</Tip>