How nizelite/alfalah_chatbot_demo works
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: agent.py Agent orchestration · app.py Flask API · App.jsx Chat interface · retrieval.py Hybrid retrieval
Components 23
Merchant interface
- Chat interface
alfa-frontend/src/App.jsx - Sign-in
alfa-frontend/src/Login.jsx - API client
alfa-frontend/src/api.js - Result cards
alfa-frontend/src/Cards.jsx
API and identity
- Flask API
backend/app.py - Tenant context
backend/context.py
Assistant runtime
- Agent orchestration
backend/agent.py - Guardrails
backend/guardrails.py - Prompt assembly
backend/prompts.py - Session memory
backend/memory.py
Knowledge retrieval
- Hybrid retrieval
backend/retrieval.py - Vector store
backend/vectorstore.py - BM25 corpus
data/bm25_corpus.json
Merchant services
- Account tools
backend/tools.py - Merchant data
backend/data.py - QR generation
backend/qrgen.py - Schema and RLS
db/001_schema.sql
Other components
- Merchant
- Supabase Auth
- Gemini
- Supabase Postgres
- Pinecone
- Local FAISS
Connections 29
- 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