# mukhtar280506/ai-bank-chatbot architecture

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

- Interactive diagram: https://gitdiagram.com/mukhtar280506/ai-bank-chatbot
- Repository: https://github.com/mukhtar280506/ai-bank-chatbot

## Overview

AI Bank Chatbot combines a React customer/admin interface with a FastAPI banking backend. Customers use the chat UI for beneficiary management, balance and transaction queries, and transfers; transfer validation and execution are distinct stages. The backend also supports complaint analysis and sanctions/rules ingestion for RAG-based compliance, while admins manage limits, customers, wallets, beneficiaries, and rules. The tree and README identify these capabilities, but unsampled route and agent implementations limit confidence about their internal call wiring.

Main entry points: [`backend/app/core/database.py`](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/core/database.py) (Banking database), [`backend/app/main.py`](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/main.py) (FastAPI app), [`frontend/unified-ui/src/App.jsx`](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/App.jsx) (Application routes), [`backend/app/routes/chat.py`](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/chat.py) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_app_ui["Application routes<br/>[App.jsx]"]
  node_auth["Role context<br/>[AuthContext.jsx]"]
  node_customer_chat["Customer chat<br/>[ChatWindow.jsx]"]
  node_admin_ui["Admin dashboard<br/>[AdminDashboard.jsx]"]
  node_api_service["API client<br/>[api.js]"]
end

subgraph group_api["API workflows"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_chat_routes["Chat endpoints<br/>[chat.py]"]
  node_validation_routes["Transfer validation<br/>[validation.py]"]
  node_beneficiary_routes["Beneficiary endpoints<br/>[beneficiary.py]"]
  node_admin_routes["Admin endpoints<br/>[admin.py]"]
end

subgraph group_intelligence["AI and compliance"]
  node_chat_agent["Chat agent<br/>[chat_agent.py]"]
  node_crm_agent["Complaint analysis<br/>[crm_sub_agent.py]"]
  node_complaint_chain["Complaint classifier<br/>[complaint_chain.py]"]
  node_rag_ingestion["Rules ingestion<br/>[ingestion.py]"]
  node_rag_retriever["Rules retrieval<br/>[retriever.py]"]
end

subgraph group_data["Persistence"]
  node_sql_db[("Banking database<br/>[database.py]")]
  node_account_model["Accounts<br/>[account.py]"]
  node_beneficiary_model["Beneficiaries"]
  node_transaction_model["Transactions<br/>[transaction.py]"]
  node_limits_model["Transfer limits<br/>[limits_table.py]"]
  node_crm_model["CRM complaints<br/>[crm_table.py]"]
end

node_customer(("Customer"))
node_admin_user(("Admin"))
node_llm{{"OpenAI LLM"}}
node_qdrant[("Rules vector store")]

node_customer -->|"uses"| node_app_ui
node_admin_user -->|"uses"| node_app_ui
node_app_ui -->|"provides session"| node_auth
node_app_ui -->|"renders"| node_customer_chat
node_app_ui -->|"renders"| node_admin_ui
node_customer_chat -->|"requests banking actions"| node_fastapi
node_admin_ui -->|"requests admin actions"| node_api_service
node_api_service -->|"sends API requests"| node_fastapi
node_fastapi -->|"mounts"| node_chat_routes
node_fastapi -->|"mounts"| node_validation_routes
node_fastapi -->|"mounts"| node_beneficiary_routes
node_fastapi -->|"mounts"| node_admin_routes
node_chat_routes -->|"delegates chat"| node_chat_agent
node_chat_agent -.->|"generates response"| node_llm
node_crm_agent -->|"classifies message"| node_complaint_chain
node_complaint_chain -.->|"analyzes complaint"| node_llm
node_crm_agent -->|"creates complaint"| node_crm_model
node_admin_routes -->|"ingests documents"| node_rag_ingestion
node_rag_ingestion -.->|"embeds rules"| node_llm
node_rag_ingestion -->|"upserts vectors"| node_qdrant
node_rag_retriever -->|"searches rules"| node_qdrant
node_admin_routes -->|"reads and updates"| node_sql_db
node_beneficiary_routes -->|"reads and writes"| node_sql_db
node_validation_routes -->|"validates and executes"| node_sql_db
node_chat_routes -->|"uses banking data"| node_sql_db
node_sql_db -->|"stores"| node_account_model
node_sql_db -->|"stores"| node_beneficiary_model
node_sql_db -->|"stores"| node_transaction_model
node_sql_db -->|"stores"| node_limits_model
node_sql_db -->|"stores"| node_crm_model

click node_app_ui "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/App.jsx"
click node_auth "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/auth/AuthContext.jsx"
click node_customer_chat "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/components/ChatWindow.jsx"
click node_admin_ui "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/pages/AdminDashboard.jsx"
click node_api_service "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/services/api.js"
click node_fastapi "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/main.py"
click node_chat_routes "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/chat.py"
click node_validation_routes "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/validation.py"
click node_beneficiary_routes "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/beneficiary.py"
click node_admin_routes "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/admin.py"
click node_chat_agent "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/agents/chat_agent.py"
click node_crm_agent "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/agents/crm_sub_agent.py"
click node_complaint_chain "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/chains/complaint_chain.py"
click node_rag_ingestion "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/rag/ingestion.py"
click node_rag_retriever "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/rag/retriever.py"
click node_sql_db "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/core/database.py"
click node_account_model "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/account.py"
click node_beneficiary_model "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/beneficiary_table.py"
click node_transaction_model "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/transaction.py"
click node_limits_model "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/limits_table.py"
click node_crm_model "https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/crm_table.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_app_ui,node_auth,node_customer_chat,node_admin_ui,node_api_service toneBlue
class node_fastapi,node_chat_routes,node_validation_routes,node_beneficiary_routes,node_admin_routes,node_qdrant toneAmber
class node_chat_agent,node_crm_agent,node_complaint_chain,node_rag_ingestion,node_rag_retriever toneMint
class node_sql_db,node_account_model,node_beneficiary_model,node_transaction_model,node_limits_model,node_crm_model toneRose
class node_customer,node_admin_user,node_llm toneIndigo
```

## Components

### Web interface

- [Application routes](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/App.jsx): `frontend/unified-ui/src/App.jsx`
- [Role context](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/auth/AuthContext.jsx): `frontend/unified-ui/src/auth/AuthContext.jsx`
- [Customer chat](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/components/ChatWindow.jsx): `frontend/unified-ui/src/components/ChatWindow.jsx`
- [Admin dashboard](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/pages/AdminDashboard.jsx): `frontend/unified-ui/src/pages/AdminDashboard.jsx`
- [API client](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/frontend/unified-ui/src/services/api.js): `frontend/unified-ui/src/services/api.js`

### API workflows

- [FastAPI app](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat endpoints](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/chat.py): `backend/app/routes/chat.py`
- [Transfer validation](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/validation.py): `backend/app/routes/validation.py`
- [Beneficiary endpoints](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/beneficiary.py): `backend/app/routes/beneficiary.py`
- [Admin endpoints](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/routes/admin.py): `backend/app/routes/admin.py`

### AI and compliance

- [Chat agent](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/agents/chat_agent.py): `backend/app/agents/chat_agent.py`
- [Complaint analysis](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/agents/crm_sub_agent.py): `backend/app/agents/crm_sub_agent.py`
- [Complaint classifier](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/chains/complaint_chain.py): `backend/app/chains/complaint_chain.py`
- [Rules ingestion](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/rag/ingestion.py): `backend/app/rag/ingestion.py`
- [Rules retrieval](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/rag/retriever.py): `backend/app/rag/retriever.py`

### Persistence

- [Banking database](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Accounts](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/account.py): `backend/app/models/account.py`
- [Beneficiaries](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/beneficiary_table.py): `backend/app/models/beneficiary_table.py`
- [Transactions](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/transaction.py): `backend/app/models/transaction.py`
- [Transfer limits](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/limits_table.py): `backend/app/models/limits_table.py`
- [CRM complaints](https://github.com/mukhtar280506/ai-bank-chatbot/blob/main/backend/app/models/crm_table.py): `backend/app/models/crm_table.py`

### Other components

- **Customer**
- **Admin**
- **OpenAI LLM**
- **Rules vector store**

## Connections

- Customer → Application routes: uses
- Admin → Application routes: uses
- Application routes → Role context: provides session
- Application routes → Customer chat: renders
- Application routes → Admin dashboard: renders
- Customer chat → FastAPI app: requests banking actions
- Admin dashboard → API client: requests admin actions
- API client → FastAPI app: sends API requests
- FastAPI app → Chat endpoints: mounts
- FastAPI app → Transfer validation: mounts
- FastAPI app → Beneficiary endpoints: mounts
- FastAPI app → Admin endpoints: mounts
- Chat endpoints → Chat agent: delegates chat
- Chat agent → OpenAI LLM: generates response
- Complaint analysis → Complaint classifier: classifies message
- Complaint classifier → OpenAI LLM: analyzes complaint
- Complaint analysis → CRM complaints: creates complaint
- Admin endpoints → Rules ingestion: ingests documents
- Rules ingestion → OpenAI LLM: embeds rules
- Rules ingestion → Rules vector store: upserts vectors
- Rules retrieval → Rules vector store: searches rules
- Admin endpoints → Banking database: reads and updates
- Beneficiary endpoints → Banking database: reads and writes
- Transfer validation → Banking database: validates and executes
- Chat endpoints → Banking database: uses banking data
- Banking database → Accounts: stores
- Banking database → Beneficiaries: stores
- Banking database → Transactions: stores
- Banking database → Transfer limits: stores
- Banking database → CRM complaints: stores