Haqdar AI ( हकदार AI ) - Context-Aware Multilingual Scheme Discovery Engine

🎯 Value Proposition

Haqdar AI bypasses complex government bureaucracy by leveraging cutting-edge LLM parameter extraction and real-time cloud data indexing. Citizens can discover eligible welfare schemes through natural language queries, voice commands, or simple form inputs—eliminating the need to navigate complex government portals and understand technical eligibility criteria.

🚀 Tech Stack

Backend

Node.js (v18+) - JavaScript runtime
Express.js (v4.x) - Web framework
MongoDB Atlas - Cloud database with real-time indexing
Mongoose (v9.x) - MongoDB object modeling
Gemini 2.5 Flash API - Google's advanced LLM for parameter extraction
Helmet - Security headers middleware
Express Rate Limit - API abuse prevention
CORS - Cross-origin resource sharing

Frontend

HTML5 - Semantic markup
Tailwind CSS - Utility-first CSS framework
Lucide Icons - Beautiful icon library
Chart.js - Data visualization
Web Speech API - Browser-native voice recognition

✨ Key Features

🤖 AI Unstructured Search

Natural language query processing using Gemini 2.5 Flash
Automatic extraction of demographic parameters (age, income, state, profession)
Context-aware scheme matching based on extracted parameters
Zero-latency intelligent filtering

🎤 Multilingual Voice Discovery

Web Speech API integration for voice input
Real-time speech-to-text conversion
Voice-triggered AI query processing
Hands-free scheme discovery experience

🏗️ Production MVC Architecture

Models: Robust MongoDB schemas with validation
Controllers: Centralized business logic and database operations
Routes: Clean API endpoint definitions
Middleware: Security, error handling, and rate limiting
Config: Centralized configuration management

⚡ Zero-Lag Skeleton UX

Beautiful Tailwind skeleton shimmer cards
Instant visual feedback during data fetching
Smooth loading transitions
Professional loading states for all async operations

📊 Seeded Database

21 live government schemes pre-loaded
Real eligibility criteria and financial benefits
Document requirements tracking
State and profession-based filtering

🏛️ System Architecture

User Query (Text/Voice)
         ↓
   Frontend Interface
         ↓
   POST /api/ai/process-query
         ↓
   Gemini 2.5 Flash API
         ↓
   JSON Parameter Extraction
   { age, income, state, profession }
         ↓
   MongoDB Atlas Query
         ↓
   Dynamic Filtering Logic
         ↓
   Matching Schemes Array
         ↓
   Bento Grid Rendering
         ↓
   Tailwind CSS Cards Display

📁 Project Structure

haqdar-ai/
├── config/
│   └── db.js                 # Database configuration
├── controllers/
│   ├── schemeController.js   # Scheme business logic
│   └── aiController.js       # AI query processing
├── middleware/
│   └── errorHandler.js       # Global error handling
├── models/
│   └── Scheme.js             # MongoDB schema
├── routes/
│   ├── schemeRoutes.js       # Scheme endpoints
│   └── aiRoutes.js           # AI endpoints
├── public/
│   └── index.html            # Frontend application
├── .env                      # Environment variables
├── package.json              # Dependencies
├── seedSchemes.js            # Database seeding
└── server.js                 # Server entry point

🛠️ Local Setup Instructions

Prerequisites

Node.js (v18 or higher)
MongoDB Atlas account (or local MongoDB)
npm or yarn

Installation

Clone the repository

git clone https://github.com/your-username/haqdar-ai.git
cd haqdar-ai

Install dependencies

npm install

Configure environment variables

Create a .env file in the root directory:

# MongoDB Atlas Configuration
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/haqdar-ai?retryWrites=true&w=majority

# Server Configuration
PORT=5000
NODE_ENV=development

# CORS Configuration
FRONTEND_URL=http://localhost:3000

# AI Configuration
GEMINI_API_KEY=your_gemini_api_key_here

Note: Replace the placeholder values with your actual credentials:

MONGO_URI: Your MongoDB Atlas connection string
GEMINI_API_KEY: Your Google Gemini API key

Start the development server

npm run dev

Access the application

Open your browser and navigate to: http://localhost:5000
Health check endpoint: http://localhost:5000/health

📡 API Endpoints

Scheme Endpoints

Method	Endpoint	Description
GET	`/api/schemes`	Get all schemes with optional filters
GET	`/health`	Server health check

AI Endpoints

Method	Endpoint	Description
POST	`/api/ai/process-query`	Process unstructured query with AI

Example API Usage

Get All Schemes

curl http://localhost:5000/api/schemes

AI Query Processing

curl -X POST http://localhost:5000/api/ai/process-query \
  -H "Content-Type: application/json" \
  -d '{"query": "I am a 25 year old farmer from Maharashtra with income 200000"}'

Filter Schemes

curl "http://localhost:5000/api/schemes?age=25&income=200000&state=Maharashtra&profession=Farmer"

🔒 Security Features

Helmet: Secure HTTP headers
Rate Limiting: 100 requests per 15 minutes per IP
CORS: Configurable cross-origin policies
Environment Variables: Sensitive data protection
Input Validation: Request body validation
Error Handling: Centralized error middleware

📊 Database Schema

Scheme Model

{
  title: String (required, indexed),
  category: String (required, enum),
  financialBenefit: String (required),
  minAge: Number (default: 0),
  maxAge: Number,
  maxIncome: Number,
  allowedStates: [String],
  allowedProfessions: [String],
  documentsRequired: [String],
  matchPercentageDescription: String
}

🎨 Frontend Features

Bento Grid Layout: Modern card-based UI
Skeleton Loading: Zero-lag loading states
Voice Input: Web Speech API integration
Real-time Filtering: Instant scheme matching
Document Verification: Upload and verify documents
Responsive Design: Mobile-friendly interface
Dark Theme: Premium dark mode with glassmorphism

🚢 Deployment

Production Setup

Set environment variables

NODE_ENV=production
MONGO_URI=mongodb+srv://username:password@cluster.mongodb.net/haqdar-ai
PORT=5000
FRONTEND_URL=https://your-domain.com
GEMINI_API_KEY=your_production_gemini_key

Install production dependencies

npm install --production

Start production server

npm start

Recommended Process Manager

npm install -g pm2
pm2 start server.js --name haqdar-ai

📝 Development Scripts

npm start        # Start production server
npm run dev      # Start development server with nodemon
npm run seed     # Seed database with government schemes

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

ISC

👥 Support

For issues and questions, please open an issue on GitHub or contact the development team.

Built with ❤️ for citizens seeking government welfare schemes

Name		Name	Last commit message	Last commit date
config		config
controllers		controllers
middleware		middleware
models		models
public		public
routes		routes
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
seedSchemes.js		seedSchemes.js
server.js		server.js
testApi.js		testApi.js

Latest commit

History

Folders and files

Repository files navigation