# anto-sujin/ai-financial-chatbot architecture

> Architecture diagram of the GitHub repository anto-sujin/ai-financial-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anto-sujin/ai-financial-chatbot
- Repository: https://github.com/anto-sujin/ai-financial-chatbot

## Overview

Personal Finance Assistant serves authenticated browser and Android users: sign in, manage transactions and financial plans, review insights, or ask the assistant to perform natural-language actions. The Flask application routes requests to domain services backed by Firestore; chat interprets requests with Groq and dispatches tools. The browser provides feature pages and SMS parsing, while Android hosts the site and forwards SMS. README documents reports and analytics alongside budgets, bills, goals, and transactions. Connections for unsampled feature pages are shown only where documented or indexed; the legacy Node backend is excluded as superseded.

Main entry points: [`finance_app/app.py`](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/app.py) (Flask routes), [`finance_app/firebase_client.py`](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/firebase_client.py) (Firebase client), [`finance_app/expense_service.py`](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/expense_service.py) (Transactions), [`finance_app/tools.py`](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/tools.py) (Assistant tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interfaces"]
  node_browser["Finance web UI<br/>[shared.js]"]
  node_feature_pages["Finance pages"]
  node_sms_flow["SMS parsing<br/>[sms_parser.js]"]
  node_android["Android WebView<br/>[MainActivity.kt]"]
  node_settings["Mobile settings<br/>[SettingsStore.kt]"]
  node_sms_bridge["SMS bridge"]
  node_sms_receiver["SMS receiver<br/>[SmsReceiver.kt]"]
end

subgraph group_api["Flask application"]
  node_flask["Flask routes<br/>[app.py]"]
  node_auth["Token verification<br/>[auth.py]"]
end

subgraph group_domains["Finance domains"]
  node_transactions["Transactions<br/>[expense_service.py]"]
  node_analytics["Analytics"]
  node_reports["Reports<br/>[report_service.py]"]
  node_budgets["Budgets<br/>[budget_service.py]"]
  node_bills["Bills<br/>[bill_service.py]"]
  node_goals["Savings goals<br/>[goal_service.py]"]
  node_dates["Date utilities<br/>[date_utils.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_chat["Chat orchestration<br/>[chat_service.py]"]
  node_tools["Assistant tools<br/>[tools.py]"]
  node_chat_state["Conversation state"]
  node_prompts["Assistant prompt<br/>[system_prompt.py]"]
  node_groq["Groq API"]
end

subgraph group_platform["Identity and storage"]
  node_firebase["Firebase client<br/>[firebase_client.py]"]
  node_firestore[("Firestore")]
  node_firebase_auth["Firebase Authentication"]
end

node_user(("Finance user"))
node_backend["Flask service"]

node_user -->|"uses"| node_browser
node_user -->|"uses"| node_android
node_android -->|"loads settings"| node_settings
node_android -->|"exposes bridge"| node_sms_bridge
node_sms_receiver -->|"forwards SMS"| node_android
node_sms_bridge -->|"delivers SMS"| node_sms_flow
node_browser -.->|"supports pages"| node_feature_pages
node_feature_pages -.->|"calls API"| node_flask
node_sms_flow -.->|"posts transactions"| node_flask
node_android -->|"loads web app"| node_backend
node_backend -->|"serves app"| node_flask
node_flask -->|"protects routes"| node_auth
node_auth -->|"verifies token"| node_firebase
node_firebase -->|"uses Admin SDK"| node_firebase_auth
node_flask -->|"routes chat"| node_chat
node_flask -->|"routes transactions"| node_transactions
node_flask -->|"routes analytics"| node_analytics
node_flask -->|"routes reports"| node_reports
node_flask -->|"routes budgets"| node_budgets
node_flask -->|"routes bills"| node_bills
node_flask -->|"routes goals"| node_goals
node_chat -->|"dispatches tools"| node_tools
node_chat -->|"reads state"| node_chat_state
node_chat -->|"uses prompt"| node_prompts
node_chat -->|"requests completion"| node_groq
node_tools -->|"calls transaction actions"| node_transactions
node_tools -->|"calls analytics"| node_analytics
node_tools -->|"calls budget actions"| node_budgets
node_tools -->|"calls bill actions"| node_bills
node_tools -->|"calls goal actions"| node_goals
node_analytics -->|"reads transactions"| node_transactions
node_reports -->|"uses analytics"| node_analytics
node_reports -->|"uses budgets"| node_budgets
node_budgets -->|"reads transactions"| node_transactions
node_bills -->|"creates transaction"| node_transactions
node_transactions -->|"resolves dates"| node_dates
node_bills -->|"resolves dates"| node_dates
node_budgets -->|"uses date windows"| node_dates
node_goals -->|"resolves dates"| node_dates
node_transactions -->|"gets database"| node_firebase
node_budgets -->|"gets database"| node_firebase
node_bills -->|"gets database"| node_firebase
node_goals -->|"gets database"| node_firebase
node_chat_state -->|"gets database"| node_firebase
node_firebase -->|"opens client"| node_firestore

click node_browser "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/public/shared.js"
click node_feature_pages "https://github.com/anto-sujin/ai-financial-chatbot/tree/main/public"
click node_sms_flow "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/public/sms_parser.js"
click node_android "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/MainActivity.kt"
click node_settings "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/SettingsStore.kt"
click node_sms_bridge "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/FinanceAiJavascriptBridge.kt"
click node_sms_receiver "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/SmsReceiver.kt"
click node_flask "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/app.py"
click node_auth "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/auth.py"
click node_transactions "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/expense_service.py"
click node_analytics "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/analytics_service.py"
click node_reports "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/report_service.py"
click node_budgets "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/budget_service.py"
click node_bills "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/bill_service.py"
click node_goals "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/goal_service.py"
click node_chat "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/chat_service.py"
click node_tools "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/tools.py"
click node_chat_state "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/chat_state_service.py"
click node_prompts "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/system_prompt.py"
click node_dates "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/date_utils.py"
click node_firebase "https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/firebase_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_feature_pages,node_sms_flow,node_android,node_settings,node_sms_bridge,node_sms_receiver,node_user toneBlue
class node_flask,node_auth toneAmber
class node_transactions,node_analytics,node_reports,node_budgets,node_bills,node_goals,node_dates toneMint
class node_chat,node_tools,node_chat_state,node_prompts,node_groq toneRose
class node_firebase,node_firestore,node_firebase_auth,node_backend toneIndigo
```

## Components

### User interfaces

- [Finance web UI](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/public/shared.js): `public/shared.js`
- [Finance pages](https://github.com/anto-sujin/ai-financial-chatbot/tree/main/public): `public`
- [SMS parsing](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/public/sms_parser.js): `public/sms_parser.js`
- [Android WebView](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/MainActivity.kt): `ai_mobile/app/src/main/java/com/financeai/mobile/MainActivity.kt`
- [Mobile settings](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/SettingsStore.kt): `ai_mobile/app/src/main/java/com/financeai/mobile/SettingsStore.kt`
- [SMS bridge](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/FinanceAiJavascriptBridge.kt): `ai_mobile/app/src/main/java/com/financeai/mobile/FinanceAiJavascriptBridge.kt`
- [SMS receiver](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/ai_mobile/app/src/main/java/com/financeai/mobile/SmsReceiver.kt): `ai_mobile/app/src/main/java/com/financeai/mobile/SmsReceiver.kt`

### Flask application

- [Flask routes](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/app.py): `finance_app/app.py`
- [Token verification](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/auth.py): `finance_app/auth.py`

### Finance domains

- [Transactions](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/expense_service.py): `finance_app/expense_service.py`
- [Analytics](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/analytics_service.py): `finance_app/analytics_service.py`
- [Reports](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/report_service.py): `finance_app/report_service.py`
- [Budgets](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/budget_service.py): `finance_app/budget_service.py`
- [Bills](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/bill_service.py): `finance_app/bill_service.py`
- [Savings goals](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/goal_service.py): `finance_app/goal_service.py`
- [Date utilities](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/date_utils.py): `finance_app/date_utils.py`

### Assistant runtime

- [Chat orchestration](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/chat_service.py): `finance_app/chat_service.py`
- [Assistant tools](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/tools.py): `finance_app/tools.py`
- [Conversation state](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/chat_state_service.py): `finance_app/chat_state_service.py`
- [Assistant prompt](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/system_prompt.py): `finance_app/system_prompt.py`
- **Groq API**

### Identity and storage

- [Firebase client](https://github.com/anto-sujin/ai-financial-chatbot/blob/main/finance_app/firebase_client.py): `finance_app/firebase_client.py`
- **Firestore**
- **Firebase Authentication**

### Other components

- **Finance user**
- **Flask service**

## Connections

- Finance user → Finance web UI: uses (evidence: `README.md`)
- Finance user → Android WebView: uses (evidence: `README.md`)
- Android WebView → Mobile settings: loads settings (evidence: `ai_mobile/app/src/main/java/com/financeai/mobile/MainActivity.kt`)
- Android WebView → SMS bridge: exposes bridge (evidence: `ai_mobile/app/src/main/java/com/financeai/mobile/MainActivity.kt`)
- SMS receiver → Android WebView: forwards SMS (evidence: `ai_mobile/app/src/main/java/com/financeai/mobile/SmsReceiver.kt`)
- SMS bridge → SMS parsing: delivers SMS (evidence: `README.md`)
- Finance web UI → Finance pages: supports pages (evidence: `public/shared.js`)
- Finance pages → Flask routes: calls API
- SMS parsing → Flask routes: posts transactions (evidence: `README.md`)
- Android WebView → Flask service: loads web app (evidence: `README.md`)
- Flask service → Flask routes: serves app (evidence: `README.md`)
- Flask routes → Token verification: protects routes (evidence: `finance_app/app.py`)
- Token verification → Firebase client: verifies token (evidence: `finance_app/auth.py`)
- Firebase client → Firebase Authentication: uses Admin SDK (evidence: `finance_app/firebase_client.py`)
- Flask routes → Chat orchestration: routes chat (evidence: `finance_app/app.py`)
- Flask routes → Transactions: routes transactions (evidence: `finance_app/app.py`)
- Flask routes → Analytics: routes analytics (evidence: `finance_app/app.py`)
- Flask routes → Reports: routes reports (evidence: `finance_app/app.py`)
- Flask routes → Budgets: routes budgets (evidence: `finance_app/app.py`)
- Flask routes → Bills: routes bills (evidence: `finance_app/app.py`)
- Flask routes → Savings goals: routes goals (evidence: `finance_app/app.py`)
- Chat orchestration → Assistant tools: dispatches tools (evidence: `finance_app/chat_service.py`)
- Chat orchestration → Conversation state: reads state (evidence: `finance_app/chat_service.py`)
- Chat orchestration → Assistant prompt: uses prompt (evidence: `finance_app/chat_service.py`)
- Chat orchestration → Groq API: requests completion (evidence: `README.md`)
- Assistant tools → Transactions: calls transaction actions (evidence: `finance_app/tools.py`)
- Assistant tools → Analytics: calls analytics (evidence: `finance_app/tools.py`)
- Assistant tools → Budgets: calls budget actions (evidence: `finance_app/tools.py`)
- Assistant tools → Bills: calls bill actions (evidence: `finance_app/tools.py`)
- Assistant tools → Savings goals: calls goal actions (evidence: `finance_app/tools.py`)
- Analytics → Transactions: reads transactions (evidence: `finance_app/analytics_service.py`)
- Reports → Analytics: uses analytics (evidence: `finance_app/report_service.py`)
- Reports → Budgets: uses budgets (evidence: `finance_app/report_service.py`)
- Budgets → Transactions: reads transactions (evidence: `finance_app/budget_service.py`)
- Bills → Transactions: creates transaction (evidence: `finance_app/bill_service.py`)
- Transactions → Date utilities: resolves dates (evidence: `finance_app/expense_service.py`)
- Bills → Date utilities: resolves dates (evidence: `finance_app/bill_service.py`)
- Budgets → Date utilities: uses date windows (evidence: `finance_app/budget_service.py`)
- Savings goals → Date utilities: resolves dates (evidence: `finance_app/goal_service.py`)
- Transactions → Firebase client: gets database (evidence: `finance_app/expense_service.py`)
- Budgets → Firebase client: gets database (evidence: `finance_app/budget_service.py`)
- Bills → Firebase client: gets database (evidence: `finance_app/bill_service.py`)
- Savings goals → Firebase client: gets database (evidence: `finance_app/goal_service.py`)
- Conversation state → Firebase client: gets database (evidence: `finance_app/chat_state_service.py`)
- Firebase client → Firestore: opens client (evidence: `finance_app/firebase_client.py`)
