Phase 2 Architecture Diagram
System Overview
┌─────────────────────────────────────────────────────────────────────────┐
│ SCAMSHIELD AI SYSTEM │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ USER INTERFACES │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ Phase 1 UI │ │ Phase 2 UI │ │ │
│ │ │ (index.html) │ │ (voice.html) │ │ │
│ │ │ │ │ │ │ │
│ │ │ Text Chat │ │ 🎤 Voice Chat │ │ │
│ │ │ Interface │ │ Interface │ │ │
│ │ └────────┬─────────┘ └────────┬─────────┘ │ │
│ └───────────┼────────────────────────────────┼──────────────────────┘ │
│ │ │ │
│ │ HTTP/JSON │ HTTP/FormData │
│ │ │ │
└──────────────┼─────────────────────────────────┼────────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────────────────┐
│ API LAYER │
│ │
│ ┌────────────────────────┐ ┌────────────────────────┐ │
│ │ Phase 1 Endpoints │ │ Phase 2 Endpoints │ │
│ │ (endpoints.py) │ │ (voice_endpoints.py) │ │
│ │ │ │ │ │
│ │ POST /honeypot/engage │ │ POST /voice/engage │ │
│ │ GET /honeypot/session│ │ GET /voice/audio/:id │ │
│ │ POST /honeypot/batch │ │ GET /voice/health │ │
│ └────────────┬───────────┘ └────────────┬───────────┘ │
└───────────────┼──────────────────────────────────┼───────────────────────┘
│ │
│ │
│ ▼
│ ┌──────────────────────────┐
│ │ Phase 2 Voice Layer │
│ │ │
│ │ ┌────────────────────┐ │
│ │ │ Audio Upload │ │
│ │ │ (multipart/form) │ │
│ │ └─────────┬──────────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌────────────────────┐ │
│ │ │ ASR Engine │ │
│ │ │ (Whisper) │ │
│ │ │ │ │
│ │ │ Audio → Text │ │
│ │ └─────────┬──────────┘ │
│ │ │ │
│ └────────────┼─────────────┘
│ │
│ │ Transcribed Text
│ │
▼◄────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────┐
│ PHASE 1 CORE (UNCHANGED) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ DETECTION LAYER │ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ │
│ │ │ Language Detector│ │ Scam Detector │ │ Scam Type │ │ │
│ │ │ (language.py) │───▶│ (detector.py) │───▶│ Classifier │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ Auto-detect │ │ IndicBERT + │ │ Financial │ │ │
│ │ │ en/hi/gu/etc │ │ Rules-based │ │ Tech Support│ │ │
│ │ └──────────────────┘ └──────────────────┘ │ Impersonation│ │
│ │ └──────────────┘ │ │
│ └──────────────────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ HONEYPOT LAYER │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────┐ │ │
│ │ │ LangGraph Workflow │ │ │
│ │ │ │ │ │
│ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │
│ │ │ │ Plan │─────▶│Generate │─────▶│ Extract │ │ │ │
│ │ │ │ Node │ │ Node │ │ Node │ │ │ │
│ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ ▼ │ │ │ │
│ │ │ │ ┌──────────┐ │ │ │ │
│ │ │ │ │ Groq LLM │ │ │ │ │
│ │ │ │ │ (Llama) │ │ │ │ │
│ │ │ │ └──────────┘ │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ └───────────────┬───────────────────┘ │ │ │
│ │ │ │ │ │ │
│ │ │ ▼ │ │ │
│ │ │ ┌───────────────┐ │ │ │
│ │ │ │ State Manager │ │ │ │
│ │ │ │ (Redis) │ │ │ │
│ │ │ └───────────────┘ │ │ │
│ │ └──────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Output: Text Reply │ │
│ └──────────────────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ EXTRACTION LAYER │ │
│ │ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ UPI Extractor│ │ Bank Account │ │ Phone/URL │ │ │
│ │ │ (Regex) │ │ Extractor │ │ Extractor │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ Output: Extracted Intelligence │ │
│ └──────────────────────────────────────┬───────────────────────────────┘ │
└─────────────────────────────────────────┼───────────────────────────────┘
│
│ Text Reply
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ PHASE 2 OUTPUT LAYER │
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ TTS Engine (gTTS) │ │
│ │ │ │
│ │ Text Reply ───▶ Text-to-Speech ───▶ Audio File (.mp3) │ │
│ │ │ │
│ │ Languages: en, hi, gu, ta, te, bn, mr │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Output: Audio URL │
└───────────────────────────────────────────────────────────────────────────┘
│
│ Audio URL
│
▼
┌──────────┐
│ User │
│ Hears │
│ AI Voice│
└──────────┘
Data Flow: Voice Conversation
Step-by-Step Flow
1. USER SPEAKS
│
│ "Your account is blocked. Send OTP now!"
│
▼
2. BROWSER CAPTURES AUDIO
│
│ MediaRecorder API → WebM/WAV blob
│
▼
3. UPLOAD TO API
│
│ POST /api/v1/voice/engage
│ FormData: audio_file, session_id, language
│
▼
4. ASR (WHISPER)
│
│ Audio → Text Transcription
│ Output: "Your account is blocked. Send OTP now!"
│ Language: "en"
│ Confidence: 0.95
│
▼
5. PHASE 1 DETECTION (UNCHANGED)
│
│ Input: Transcribed text
│ Scam Detector → is_scam: true, confidence: 0.92
│ Type: "financial_fraud"
│
▼
6. PHASE 1 HONEYPOT (UNCHANGED)
│
│ LangGraph Workflow:
│ - Plan: Select "confused_elderly" persona
│ - Generate: Groq LLM creates reply
│ - Extract: Parse for UPI/bank/phone
│
│ Output: "Oh no! What should I do? I'm scared!"
│
▼
7. TTS (gTTS)
│
│ Text → Speech Synthesis
│ Input: "Oh no! What should I do? I'm scared!"
│ Language: "en"
│ Output: /tmp/reply_xyz.mp3
│
▼
8. RESPONSE TO USER
│
│ JSON Response:
│ {
│ "ai_reply_text": "Oh no! What should I do?",
│ "ai_reply_audio_url": "/api/v1/voice/audio/reply_xyz.mp3",
│ "transcription": {...},
│ "scam_detected": true,
│ ...
│ }
│
▼
9. BROWSER PLAYS AUDIO
│
│ <audio controls src="/api/v1/voice/audio/reply_xyz.mp3">
│
▼
10. USER HEARS AI VOICE
│
│ "Oh no! What should I do? I'm scared!"
│
└─▶ Loop continues for multi-turn conversation
Component Isolation
Phase 1 (Existing - Untouched)
┌─────────────────────────────────────┐
│ PHASE 1 COMPONENTS │
│ │
│ ✅ app/models/detector.py │
│ ✅ app/models/language.py │
│ ✅ app/models/extractor.py │
│ ✅ app/agent/honeypot.py │
│ ✅ app/agent/personas.py │
│ ✅ app/agent/strategies.py │
│ ✅ app/api/endpoints.py │
│ ✅ app/api/schemas.py │
│ ✅ ui/index.html │
│ ✅ ui/app.js │
│ │
│ NO MODIFICATIONS REQUIRED │
└─────────────────────────────────────┘
Phase 2 (New - Isolated)
┌─────────────────────────────────────┐
│ PHASE 2 COMPONENTS │
│ │
│ 🆕 app/voice/asr.py │
│ 🆕 app/voice/tts.py │
│ 🆕 app/voice/fraud_detector.py │
│ 🆕 app/api/voice_endpoints.py │
│ 🆕 app/api/voice_schemas.py │
│ 🆕 ui/voice.html │
│ 🆕 ui/voice.js │
│ 🆕 ui/voice.css │
│ │
│ COMPLETELY SEPARATE │
└─────────────────────────────────────┘
Integration Points (Minimal)
┌─────────────────────────────────────┐
│ INTEGRATION POINTS │
│ │
│ 📝 app/main.py │
│ + Add voice router (conditional)│
│ │
│ 📝 app/config.py │
│ + Add Phase 2 settings │
│ │
│ 📝 .env │
│ + Add PHASE_2_ENABLED=true │
│ │
│ MINIMAL CHANGES │
└─────────────────────────────────────┘
Optional: Voice Fraud Detection
┌──────────────────────────────────────────────────────────────┐
│ VOICE FRAUD DETECTION (OPTIONAL) │
│ │
│ Audio Input │
│ │ │
│ ├──────────────────────────────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ │
│ │ ASR │ │ Fraud │ │
│ │(Whisper)│ │Detector │ │
│ └────┬────┘ │(Wav2Vec2│ │
│ │ │resemb.) │ │
│ │ └────┬────┘ │
│ │ │ │
│ │ Transcribed Text │ Fraud Score │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Combined Analysis │ │
│ │ │ │
│ │ - Text content (scam detection) │ │
│ │ - Voice authenticity (fraud detection) │ │
│ │ │ │
│ │ Risk Score = f(scam_conf, fraud_conf) │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ If VOICE_FRAUD_DETECTION=true │
└──────────────────────────────────────────────────────────────┘
Database & State Management
┌─────────────────────────────────────────────────────────────┐
│ STATE PERSISTENCE │
│ │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ Redis │ │ PostgreSQL │ │
│ │ (Session State) │ │ (Conversation Logs) │ │
│ │ │ │ │ │
│ │ - Active sessions │ │ - Full transcripts │ │
│ │ - Turn count │ │ - Extracted intel │ │
│ │ - Extracted intel │ │ - Audio metadata │ │
│ │ - Persona state │ │ - Timestamps │ │
│ │ - TTL: 1 hour │ │ - Permanent storage │ │
│ └──────────────────────┘ └──────────────────────┘ │
│ │
│ SAME AS PHASE 1 - NO CHANGES │
└─────────────────────────────────────────────────────────────┘
Performance Considerations
┌─────────────────────────────────────────────────────────────┐
│ LATENCY BREAKDOWN │
│ │
│ User Speaks (5s audio) │
│ │ │
│ ▼ │
│ Upload to API (0.5s) │
│ │ │
│ ▼ │
│ ASR Transcription (1.5s) ◄── Whisper base model │
│ │ │
│ ▼ │
│ Scam Detection (0.2s) ◄── IndicBERT │
│ │ │
│ ▼ │
│ Honeypot LLM (1.0s) ◄── Groq API │
│ │ │
│ ▼ │
│ TTS Synthesis (0.8s) ◄── gTTS │
│ │ │
│ ▼ │
│ Download Audio (0.3s) │
│ │ │
│ ▼ │
│ Total: ~4.3s │
│ │
│ Target: <5s ✅ │
└─────────────────────────────────────────────────────────────┘
Deployment Architecture
┌─────────────────────────────────────────────────────────────┐
│ DEPLOYMENT │
│ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ Docker Container │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ FastAPI Application │ │ │
│ │ │ │ │ │
│ │ │ - Phase 1 Endpoints (always enabled) │ │ │
│ │ │ - Phase 2 Endpoints (if PHASE_2_ENABLED=true) │ │ │
│ │ │ │ │ │
│ │ │ Dependencies: │ │ │
│ │ │ - Base: transformers, langchain, groq │ │ │
│ │ │ - Phase 2: whisper, gTTS, torchaudio │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────┐ │ │
│ │ │ Model Cache │ │ │
│ │ │ │ │ │
│ │ │ - IndicBERT (~500MB) │ │ │
│ │ │ - Whisper base (~150MB) [Phase 2] │ │ │
│ │ └──────────────────────────────────────────────────┘ │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ External Services: │
│ - Redis (session state) │
│ - PostgreSQL (conversation logs) │
│ - Groq API (LLM) │
└─────────────────────────────────────────────────────────────┘
Security Architecture
┌─────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
│ │
│ 1. API Authentication │
│ └─▶ x-api-key header (both Phase 1 & 2) │
│ │
│ 2. Input Validation │
│ ├─▶ File size limits (<10MB) │
│ ├─▶ File type validation (audio/* only) │
│ └─▶ Sanitize filenames │
│ │
│ 3. Rate Limiting │
│ └─▶ Max requests per session │
│ │
│ 4. Data Privacy │
│ ├─▶ Temporary audio storage │
│ ├─▶ Auto-delete after processing │
│ └─▶ No raw audio in database │
│ │
│ 5. Error Handling │
│ └─▶ No sensitive info in error messages │
└─────────────────────────────────────────────────────────────┘
Key Takeaways
- Phase 2 wraps Phase 1: Voice is input/output layer only
- Zero modifications to Phase 1: Core honeypot unchanged
- Conditional loading: Phase 2 only loads if enabled
- Separate UI: Voice UI is independent of text UI
- Same state management: Reuses Redis/PostgreSQL
- Performance target: <5s for full voice loop
- Security first: Audio files temporary, validated, rate-limited
For detailed implementation steps, see: PHASE_2_VOICE_IMPLEMENTATION_PLAN.md
For quick start guide, see: PHASE_2_README.md
For progress tracking, see: PHASE_2_CHECKLIST.md