# nizelite/alfalah_chatbot_demo architecture

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

- Interactive diagram: https://gitdiagram.com/nizelite/alfalah_chatbot_demo
- Repository: https://github.com/nizelite/alfalah_chatbot_demo

## Overview

Alfa Business Assistant lets a signed-in merchant ask product questions or request account actions in English, Urdu, or Punjabi. The frontend authenticates and streams chat through Flask; the backend resolves a tenant-scoped context, applies guardrails, retrieves product knowledge, and orchestrates Gemini responses and account tools. Tools read merchant data or generate QR codes, with Supabase enforcing tenant isolation. Hybrid retrieval combines dense vectors with BM25. The graph follows README-documented wiring; some backend call details are unsampled, so uncertain links are omitted.

Main entry points: [`backend/agent.py`](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/agent.py) (Agent orchestration), [`backend/app.py`](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/app.py) (Flask API), [`alfa-frontend/src/App.jsx`](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/App.jsx) (Chat interface), [`backend/retrieval.py`](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/retrieval.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Merchant interface"]
  node_app_ui["Chat interface<br/>[App.jsx]"]
  node_login["Sign-in<br/>[Login.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_tool_cards["Result cards<br/>[Cards.jsx]"]
end

subgraph group_gateway["API and identity"]
  node_flask_api["Flask API<br/>[app.py]"]
  node_tenant_context["Tenant context<br/>[context.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_assistant_agent["Agent orchestration<br/>[agent.py]"]
  node_guardrails["Guardrails<br/>[guardrails.py]"]
  node_prompts["Prompt assembly<br/>[prompts.py]"]
  node_conversation_memory["Session memory<br/>[memory.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_retriever["Hybrid retrieval<br/>[retrieval.py]"]
  node_vector_store[("Vector store<br/>[vectorstore.py]")]
  node_bm25_corpus["BM25 corpus<br/>[bm25_corpus.json]"]
end

subgraph group_account["Merchant services"]
  node_tool_handlers["Account tools<br/>[tools.py]"]
  node_merchant_data["Merchant data<br/>[data.py]"]
  node_qr_generation["QR generation<br/>[qrgen.py]"]
  node_schema["Schema and RLS<br/>[001_schema.sql]"]
end

node_merchant(("Merchant"))
node_supabase_auth["Supabase Auth"]
node_gemini["Gemini"]
node_supabase_db[("Supabase Postgres")]
node_pinecone[("Pinecone")]
node_faiss[("Local FAISS")]

node_merchant -->|"asks"| node_app_ui
node_app_ui -->|"signs in"| node_login
node_login -->|"authenticates"| node_supabase_auth
node_app_ui -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_flask_api
node_flask_api -->|"resolves identity"| node_tenant_context
node_tenant_context -->|"validates token"| node_supabase_auth
node_tenant_context -->|"loads merchant"| node_merchant_data
node_flask_api -->|"runs chat"| node_assistant_agent
node_flask_api -->|"manages sessions"| node_conversation_memory
node_assistant_agent -->|"checks request"| node_guardrails
node_assistant_agent -->|"searches knowledge"| node_retriever
node_assistant_agent -->|"assembles turn"| node_prompts
node_assistant_agent -->|"reads and saves turns"| node_conversation_memory
node_assistant_agent -->|"generates response"| node_gemini
node_assistant_agent -->|"dispatches tools"| node_tool_handlers
node_retriever -->|"embeds query"| node_gemini
node_retriever -->|"searches vectors"| node_vector_store
node_retriever -->|"reads sparse index"| node_bm25_corpus
node_vector_store -.->|"uses when configured"| node_pinecone
node_vector_store -->|"falls back locally"| node_faiss
node_tool_handlers -->|"reads account data"| node_merchant_data
node_tool_handlers -->|"builds QR"| node_qr_generation
node_merchant_data -->|"queries tenant data"| node_supabase_db
node_conversation_memory -->|"stores sessions"| node_supabase_db
node_supabase_db -->|"enforces policies"| node_schema
node_flask_api -->|"streams events"| node_api_client
node_api_client -->|"delivers events"| node_app_ui
node_app_ui -->|"renders tool results"| node_tool_cards

click node_app_ui "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/App.jsx"
click node_login "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/Login.jsx"
click node_api_client "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/api.js"
click node_tool_cards "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/Cards.jsx"
click node_flask_api "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/app.py"
click node_tenant_context "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/context.py"
click node_assistant_agent "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/agent.py"
click node_guardrails "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/guardrails.py"
click node_prompts "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/prompts.py"
click node_conversation_memory "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/memory.py"
click node_retriever "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/retrieval.py"
click node_vector_store "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/vectorstore.py"
click node_bm25_corpus "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/data/bm25_corpus.json"
click node_tool_handlers "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/tools.py"
click node_merchant_data "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/data.py"
click node_qr_generation "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/qrgen.py"
click node_schema "https://github.com/nizelite/alfalah_chatbot_demo/blob/main/db/001_schema.sql"

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_login,node_api_client,node_tool_cards toneBlue
class node_flask_api,node_tenant_context,node_supabase_db,node_pinecone,node_faiss toneAmber
class node_assistant_agent,node_guardrails,node_prompts,node_conversation_memory toneMint
class node_retriever,node_vector_store,node_bm25_corpus toneRose
class node_tool_handlers,node_merchant_data,node_qr_generation,node_schema,node_merchant,node_supabase_auth,node_gemini toneIndigo
```

## Components

### Merchant interface

- [Chat interface](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/App.jsx): `alfa-frontend/src/App.jsx`
- [Sign-in](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/Login.jsx): `alfa-frontend/src/Login.jsx`
- [API client](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/api.js): `alfa-frontend/src/api.js`
- [Result cards](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/alfa-frontend/src/Cards.jsx): `alfa-frontend/src/Cards.jsx`

### API and identity

- [Flask API](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/app.py): `backend/app.py`
- [Tenant context](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/context.py): `backend/context.py`

### Assistant runtime

- [Agent orchestration](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/agent.py): `backend/agent.py`
- [Guardrails](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/guardrails.py): `backend/guardrails.py`
- [Prompt assembly](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/prompts.py): `backend/prompts.py`
- [Session memory](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/memory.py): `backend/memory.py`

### Knowledge retrieval

- [Hybrid retrieval](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/retrieval.py): `backend/retrieval.py`
- [Vector store](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/vectorstore.py): `backend/vectorstore.py`
- [BM25 corpus](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/data/bm25_corpus.json): `data/bm25_corpus.json`

### Merchant services

- [Account tools](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/tools.py): `backend/tools.py`
- [Merchant data](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/data.py): `backend/data.py`
- [QR generation](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/backend/qrgen.py): `backend/qrgen.py`
- [Schema and RLS](https://github.com/nizelite/alfalah_chatbot_demo/blob/main/db/001_schema.sql): `db/001_schema.sql`

### Other components

- **Merchant**
- **Supabase Auth**
- **Gemini**
- **Supabase Postgres**
- **Pinecone**
- **Local FAISS**

## Connections

- Merchant → Chat interface: asks
- Chat interface → Sign-in: signs in
- Sign-in → Supabase Auth: authenticates
- Chat interface → API client: calls
- API client → Flask API: sends requests
- Flask API → Tenant context: resolves identity
- Tenant context → Supabase Auth: validates token
- Tenant context → Merchant data: loads merchant
- Flask API → Agent orchestration: runs chat
- Flask API → Session memory: manages sessions
- Agent orchestration → Guardrails: checks request
- Agent orchestration → Hybrid retrieval: searches knowledge
- Agent orchestration → Prompt assembly: assembles turn
- Agent orchestration → Session memory: reads and saves turns
- Agent orchestration → Gemini: generates response
- Agent orchestration → Account tools: dispatches tools
- Hybrid retrieval → Gemini: embeds query
- Hybrid retrieval → Vector store: searches vectors
- Hybrid retrieval → BM25 corpus: reads sparse index
- Vector store → Pinecone: uses when configured
- Vector store → Local FAISS: falls back locally
- Account tools → Merchant data: reads account data
- Account tools → QR generation: builds QR
- Merchant data → Supabase Postgres: queries tenant data
- Session memory → Supabase Postgres: stores sessions
- Supabase Postgres → Schema and RLS: enforces policies
- Flask API → API client: streams events
- API client → Chat interface: delivers events
- Chat interface → Result cards: renders tool results