A WhatsApp AI Agent for Welfare-Scheme Discovery.
Talk naturally. Let the agent extract your profile attributes from conversational messages. Deterministic Java rules evaluate eligibility over 82 normalized schemes.
Architecture · Backend · Security · AI Integration
Java · Spring Boot · PostgreSQL · Groq
Release Ready (Documented Conditions)
WhatsApp + Portfolio Demo
63 Central · 11 State · 8 Philanthropic
Seeded into 1NF relational schema on Supabase PostgreSQL 17.
42 Passing Tests Across Core Suites
Backend release-gate verification recorded 42/42 passing tests.
0 Critical / High Findings in Final Security Audit
Verified in release-gate security audit with zero high-severity findings.
PostgreSQL Relational Indexing
Eligibility rules are evaluated through indexed relational criteria queries rather than unstructured prompt context or table scans.
Verification note: Benchmarks and tests reflect verified relational schema normalization, automated test suite passes, and security boundary assertions. External network delivery depends on telecommunication and messaging gateway factors.
Real-World Multilingual Scheme Discovery
Historical interaction captures from the original Yojna Setu conversational pipeline. These unedited captures demonstrate how real citizens interface with natural-language intake, slot filling, and eligibility resolution.
Intake & Multi-Variable Demographic Extraction
The user triggers a session reset and inputs multi-variable demographic parameters in conversational Hinglish ('namaste, main ek student hoon, 20 saal, UP se, general hoon, income 1.5 lakh , hindu'). The engine extracts the attributes, identifies the missing gender slot, asks for clarification ('Aap purush hain ya mahila?'), and recommends 5 matched schemes upon receiving 'Purush'.
Historical Product Interaction — Captured during original prototype conversational testing.
Temporal Deadlines & Prerequisite Documentation
The user inquires about deadlines by messaging 'Deadline', receiving upcoming dates for UP Mukhyamantri Abhyudaya Yojana. Following with 'Documents', the system delivers the exact documentation checklist required across matching schemes (Aadhaar Card, Ration Card, Income Certificate, Class 12 Marksheet, Admission Letter).
Historical Product Interaction — Captured during original prototype conversational testing.
The 3-Step WhatsApp Experience
The screenshots record an actual conversation. The user talks naturally in Hinglish, the bot asks for any missing profile detail, and the backend returns matching schemes with deadlines and documents:
- PHASE I: INTAKE & CLARIFICATION
1. User sends
Resetto start fresh.
2. User provides unformatted Hinglish with age, state, student occupation, income, and religion.
3. System identifies missing gender and asks for clarification (“Aap purush hain ya mahila?”). - PHASE II: SCHEME EVALUATION
4. User replies
Purush.
5. All demographic criteria are satisfied; rules engine filters 82 schemes down to 5 qualified programs.
6. User receives verified scheme titles with direct portal application URLs. - PHASE III: GUIDANCE & CHECKLISTS
7. User sends
Deadline, receiving upcoming cutoff dates.
8. User sendsDocuments.
9. System details the required identity and verification paperwork for each scheme.
Context: These captures show the front-facing WhatsApp conversation from prototype testing. In V2, the entire backend was rebuilt from scratch with the deterministic Java rules engine and security controls explained below.
From Prototype to Hardened Backend
The original prototype had critical security and correctness issues. Here are the 5 key engineering fixes made in V2 to harden the backend architecture.
Credential Security
Plaintext database credentials committed directly in startup shell scripts (start-app.sh).
Environment-based secrets with strict startup validation and complete Git history cleanup.
Eligibility Matching Logic
Brittle substring evaluation: scheme.getGender().contains("MALE") erroneously returned true for "FEMALE".
Deterministic relational rules (EligibilityEngine) using typed enums and database join criteria.
Media & SSRF Defense
Unvalidated remote media downloads allowing potential SSRF against private networks and metadata endpoints.
SSRF protection: HTTPS enforcement, Twilio host allowlist, private IP blocking, and bounded streaming.
Conversation State
In-memory ConcurrentHashMap causing state loss across server restarts and cross-thread concurrency issues.
Persistent database-backed conversation state machine (ConversationSession) with session recovery.
Webhook Idempotency
Retried provider webhooks generated duplicate outbound messages and corrupted multi-step state.
Idempotency layer: in-memory cache backed by unique constraints on webhook_events in PostgreSQL.
Security Scope: Hardening focused on verifiable engineering controls: eliminating hardcoded secrets, guaranteeing mathematical determinism in benefits matching, sanitizing inputs and remote media, and enforcing strict session idempotency.
How the System Works
The main design principle is simple: AI extracts information. Java rules decide eligibility. The language model handles informal, multilingual chat, while the deterministic Java backend enforces statutory rules.
User Ingress
WhatsApp & Browser DemoUsers send conversational messages in Hindi, Hinglish, or English, or spoken voice notes.
Webhook Security
Spring Security LayerChecks webhook signatures, verifies idempotency, and filters external media downloads.
AI Profile Extraction
Groq Cloud (LLM + Whisper)Parses conversational text and voice into structured profile fields (age, state, income, caste).
Java Eligibility Rules
Deterministic EngineEvaluates exact statutory rules: age limits, income ceilings, caste, and state residency criteria.
PostgreSQL Database
Supabase (yojna_setu Schema)Stores 82 normalized schemes, criteria tables, conversation state, and webhook deduplication records.
AI Understands. Rules Decide.
Even if AI extraction is imperfect, it cannot directly decide eligibility. The final decision is made by deterministic Java rules evaluated against verified government scheme criteria.
Where AI Is Used
Language models are great at parsing messy, conversational inputs. In Yojna Setu, Groq Cloud (GPT-OSS-20B and Whisper Large V3 Turbo) is used strictly for:
- 01.Understanding Natural Language: Handling informal messages in Hindi, Hinglish, and English without requiring rigid menus.
- 02.Profile Extraction: Pulling key details like age, state, annual income, caste, and occupation into structured fields.
- 03.Voice-to-Text: Transcribing WhatsApp audio voice notes into clean text for downstream extraction.
Where AI Is NOT Used
The AI has zero authority over scheme eligibility decisions. All qualification is handled by the Java rules engine because:
- 01.Bounded AI Impact: The AI only extracts structured profile information. It does not decide whether a user qualifies for a scheme.
- 02.Clear Audit Trail: Every matched scheme returns the exact mathematical reason (e.g., age ≤ 25, income ≤ ₹2.5L, state = UP).
- 03.Reliable Testing: Rules can be tested with unit tests and database queries rather than hoping prompts don't drift.
Interview Summary: If the user enters a typo or ambiguous input, the AI might misinterpret a demographic slot, but the Java engine will only evaluate what is structured. The AI cannot fabricate an entitlement or bypass statutory income limits.
Security Controls
Key security controls implemented in V2. Instead of generic marketing claims, these represent concrete software defenses built into the backend.
Webhook Verification
Twilio webhook signatures are checked before processing requests.
Inbound requests without valid HMAC signatures are immediately dropped, preventing forged or spoofed messages.
SSRF Protection
External media URLs are validated before the server downloads them.
Restricts media downloads to verified Twilio hosts, blocks private IP ranges and cloud metadata endpoints, and enforces 5MB stream limits.
PII-Safe Logging
Sensitive phone numbers and demographic data are masked in logs.
Phone numbers are stored as salted SHA-256 hashes, and a custom Logback converter masks mobile numbers in application logs.
Webhook Idempotency
Repeated webhook deliveries do not create duplicate processing.
Unique database constraints on webhook event IDs prevent re-processing retried requests or sending duplicate replies.
Persistent Conversation State
Conversation state is stored so multi-step conversations survive restarts.
Multi-turn demographic collection is backed by PostgreSQL sessions rather than volatile in-memory maps.
0 Critical / High Findings
Verified in the final independent security audit before release.
Backend test suites verify webhook HMAC, SSRF revalidation, and session isolation.
42/42 Tests Passing: Core Test Areas
Backend release-gate verification recorded 42/42 passing tests across four primary areas. Tests were written around actual regression vectors from the prototype.
Eligibility Rules
Deterministic age bounds, income ceilings, gender matching, and state residency rules.
Webhook Security
HMAC signature verification, replay protection, and provider response formatting.
Media / SSRF Security
Host allowlisting, private IP blocking, 5MB bounded streaming, and redirect re-validation.
Conversation Flow
Multi-turn state transitions, slot clarification, legacy endpoint removal, and container startup.
View detailed test classes (9 test classes · 42 tests total)↓
Interview Context: Passing 42 automated tests confirms that specific security regressions, SSRF vectors, and eligibility matching invariants are protected in CI. It demonstrates solid engineering hygiene rather than a theoretical guarantee against all hypothetical bugs.
Release Status & Known Boundaries
What is verified in V2, and what known limitations remain. The independent release gate classified Yojna Setu V2 as Release Ready With Documented Conditions.
- ✓Supabase PostgreSQL 17 live connectivity and yojna_setu schema isolation.
- ✓82 normalized welfare schemes seeded with relational child tables.
- ✓Groq Cloud AI connectivity for multilingual demographic extraction (gpt-oss-20b).
- ✓Whisper Large V3 Turbo connectivity for voice-note transcription.
- ✓42/42 automated unit, integration, and security tests passing.
- ✓Historical plaintext credentials completely expunged from reachable repository history.
- ✓Strict PII log masking and blind-indexed phone storage verified.
Live production WhatsApp delivery over Twilio was not verified with live carrier traffic due to sandbox constraints. Webhook reception, HMAC verification, and response serialization are fully verified via automated suites.
PostgreSQL Row Level Security (RLS) is not currently implemented on the database tables; all access authorization is enforced strictly within the Spring Boot application service layer via authenticated database roles.
Bucket4j rate-limiting tokens are stored in local JVM memory. While effective for single-instance deployments, horizontal scaling across multiple instances requires a centralized Redis token bucket.
How Intake & Eligibility Work in Practice
Simulated portfolio experience — not a live government service. Select a sample persona below to walk through the 4 steps: from citizen message to extracted profile, rule checks, and matched schemes.
PM-KISAN Samman Nidhi
Central WelfareBenefit: Direct income support of ₹6,000 per year in three installments for landholding farmer families.
Active farmer, landholding criteria satisfied, income within prescribed ceiling.
Ayushman Bharat PMJAY
Central WelfareBenefit: Health insurance cover of up to ₹5,00,000 per family per year for secondary and tertiary hospitalization.
Low-income rural household meeting deprivation criteria.
UP Mahila Samarthya Yojana
State WelfareBenefit: Financial and technical support for rural women self-help groups and agrarian enterprises.
Female resident of Uttar Pradesh engaged in agrarian micro-enterprise.