SchemeAI

Find Indian government schemes you may be eligible for — with every match traced back to an official source.

SchemeAI helps citizens discover central and state welfare schemes — scholarships, farmer support, pensions, housing, health cover, livelihood loans and more. A short profile runs through a transparent, rule-based eligibility engine; every result explains which rules were met, which failed, and which still need official confirmation, alongside excerpts from official guidelines and a link to the official portal.

---

Why

India runs hundreds of welfare schemes across ministries, states and departments. Citizens struggle to find the ones relevant to them, to parse eligibility criteria written in dense official language, to locate the genuine application portal, and to know which documents to prepare. Many aggregators paraphrase — or invent — details with no traceable source.

SchemeAI takes the opposite approach:

• Deterministic eligibility. Matching is done by documented rules, never by an LLM guessing.
• Evidence first. Each scheme carries guideline excerpts and the official URL they came from.
• Honest verification. Records are labelled Reference record until a real check of the official domain succeeds; failed checks are shown as failures.
• Citizen stays in control. No login, CAPTCHA, OTP or Aadhaar automation — those steps always happen on the official portal.

Features

• Guided profile wizard — 4-step, guest-first (no account required); asks only basic attributes such as age, state, education, occupation and income band.
• Explainable eligibility engine — every rule evaluates to MET, FAILED or UNKNOWN; OR-groups for alternative criteria; results labelled Likely Eligible, Possibly Eligible, Not Eligible (per provided info) or Unable to Determine.
• Reference scheme database — 33 schemes (central plus selected Uttar Pradesh / Madhya Pradesh schemes), 94 structured eligibility rules, 22 registered official sources.
• Search and browse — debounced full-text search, category, state and central/state-level filters, sorting and pagination.
• Scheme detail — rule-by-rule "why this may match you", what still needs verification, documented benefits, interactive document checklist, source evidence and a direct link to the official application portal.
• Live source verification — real HTTP checks of official domains with recorded status, page title, timing and errors; every run is logged as a FetchJob.
• TinyFish live extraction — when TINYFISH_API_KEY is set, a hosted browser agent reads official pages and returns structured JSON: current deadline, eligibility, documents and benefit for a scheme (from the scheme page's Verify button), or scheme names, announcements and closing dates for a source (from admin discovery). Results are stored with their TinyFish run ID; without a key the integration reports NOT_CONFIGURED and direct checks continue.
• Ask SchemeAI assistant — retrieval-grounded answers that cite official URLs, with a deterministic fallback when no LLM is available.
• Compare — up to 3 schemes side by side; undocumented values are shown as "Not documented".
• Saved schemes and application tracker — guest mode via local storage, signed-in mode persisted in the database; tracker statuses are self-reported and labelled as such.
• Admin dashboard (admin role only) — real metrics, source registry, per-source live checks, a Run TinyFish discovery button, fetch-job history and TinyFish status.
• Bilingual UI — English and Hindi, switchable from the navigation bar.
• Email/password auth — scrypt password hashing, database-backed sessions in httpOnly cookies, user / admin roles.

Architecture

flowchart LR
    U["Citizen (browser)"] --> UI["Next.js App Router UI<br/>(single-page shell at /)"]
    UI --> API["Route handlers<br/>src/app/api/*"]
    API --> ENG["Eligibility engine<br/>src/lib/eligibility.ts"]
    API --> ASSIST["Ask SchemeAI<br/>(retrieval + LLM / fallback)"]
    API --> LIVE["Live check<br/>src/lib/live-check.ts"]
    API --> TF["TinyFish layer<br/>src/lib/tinyfish.ts"]
    API --> DB[("PostgreSQL via Prisma")]
    ENG --> DB
    ASSIST --> DB
    LIVE --> GOV["Official .gov.in / .nic.in portals"]
    TF --> TFE["TinyFish agent API<br/>POST /v1/automation/run"]
    TFE --> GOV
    LIVE --> TF
    LIVE --> DB
    SEED["Seed data<br/>src/lib/schemes/data"] --> DB

Loading

See docs/ARCHITECTURE.md for the full breakdown.

How it works

1. Profile. The wizard collects a minimal profile (age, state, gender, education, employment, income band, and optional category flags). The profile is kept in the browser (local storage), for guests and signed-in users alike.
2. Eligibility engine. POST /api/schemes/match evaluates each scheme's structured rules (attribute, operator, value, required, ruleGroup). Rules sharing a ruleGroup are OR'ed (e.g. Stand-Up India: SC/ST or woman); groups are AND'ed. Missing information yields UNKNOWN, never a guess. isBpl is deliberately unanswerable from a profile — BPL/SECC listing can only be confirmed on official records. Relevance is shown as bands (High Relevance / Potential Match / Explore), never as a legal eligibility percentage.
3. Evidence. Each result links to SourceEvidence rows — guideline excerpts with the official URL — plus documented benefits, required documents and application steps. Fields that could not be verified read "Not documented".
4. Live verification. Every check makes a genuine HTTP request to the official domain (12 s timeout). Successes record the HTTP status and page title and upgrade linked schemes from REFERENCE to LIVE_CHECKED; failures are stored with the real error.
   • Scheme refresh — the Verify button on a scheme page calls POST /api/sources/verify with sourceId and schemeId. Anyone can use it. Alongside the direct check, a TinyFish run (when TINYFISH_API_KEY is set) extracts the scheme's current deadline, eligibility, documents and benefit from its official page; the result is stored as LIVE_FETCH evidence, shown on the page, and reused for 6 hours.
   • Discovery — POST /api/discovery (admin only) checks up to 5 sources. Each gets a direct check plus, when configured, a TinyFish extraction of scheme names, announcements and deadlines (at most 2 runs in parallel), stored in FetchJob.resultJson.
5. AI assistant. POST /api/assistant retrieves the most relevant scheme records, then asks an LLM to answer only from those records with citations. If the model is unavailable, a deterministic, cited listing is returned instead, and the response is labelled AI_GROUNDED or DETERMINISTIC.

Detailed sequence diagrams are in docs/FLOWS.md; TinyFish specifics are in docs/TINYFISH.md.

Tech stack

Layer	Technology
Framework	Next.js 16 (App Router), React 19
Language	TypeScript 5
Styling / UI	Tailwind CSS 4, shadcn/ui (Radix primitives), Framer Motion, lucide-react
State	Zustand (persisted guest state), TanStack Query
Validation	Zod 4
Database	PostgreSQL (e.g. Neon) via Prisma 6
Auth	Custom scrypt hashing + DB sessions (httpOnly cookies)
Live verification	Native fetch against official domains; optional TinyFish agent API
Assistant	Retrieval over the scheme DB + z-ai-web-dev-sdk chat completions, deterministic fallback
Hosting	Vercel (bom1 region)

Project structure

prisma/schema.prisma          11 models: User, Session, UserProfile, GovernmentSource, Scheme,
                              SchemeEligibilityRule, SourceEvidence, FetchJob, SavedScheme,
                              ApplicationTracker, AuditLog
scripts/
  seed.ts                     Idempotent seed of sources + schemes
  create-admin.ts             Creates the demo admin account
src/app/
  page.tsx                    Renders the single-page app shell
  api/                        Route handlers (schemes, match, compare, sources, discovery,
                              assistant, auth, saved, tracker, admin, setup, health)
src/components/schemeai/      Home, Wizard, Results, Browse, Detail, Compare, Dashboard,
                              Admin, Assistant, Auth views
src/lib/
  eligibility.ts              Rule engine
  live-check.ts               Direct HTTP source checks, TinyFish scheme refresh, FetchJob recording
  tinyfish.ts                 TinyFish API client, goal prompts and status model
  auth.ts                     Password hashing and sessions
  i18n.tsx                    English / Hindi dictionary
  store.ts                    Zustand client store
  schemes/data/               Reference schemes and official source registry
tests/eligibility.test.ts     Eligibility engine unit tests

Getting started

Prerequisites

• Node.js 20+ (or Bun)
• A PostgreSQL database — a free Neon project works well

Install

git clone https://github.com/LearnCodeZaid/schemeai.git
cd schemeai
npm install            # runs `prisma generate` via postinstall
cp .env.example .env   # then fill in the values

Environment variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string (pooled Neon URI recommended).
SETUP_SECRET	For /api/setup	Shared secret that authorises the one-time seed endpoint.
TINYFISH_API_KEY	No	Enables TinyFish live extraction. Create a key at https://agent.tinyfish.ai/api-keys.
TINYFISH_API_URL	No	TinyFish API base URL (defaults to https://agent.tinyfish.ai).

Without TINYFISH_API_KEY the integration reports NOT_CONFIGURED and direct HTTP checks continue to work. The assistant has no environment variable of its own: its LLM mode depends on the z-ai-web-dev-sdk client finding its own configuration; otherwise it answers in deterministic mode.

Database setup and seed

npx prisma db push       # create tables
npm run db:seed          # 22 sources + 33 schemes with rules and evidence
npm run db:seed:admin    # demo admin: admin@schemeai.in / Admin@1234

On a hosted deployment you can instead seed once with POST /api/setup?setup=1 and the header x-setup-secret: <SETUP_SECRET> (idempotent; also creates the demo admin). Change the demo admin password after first login.

Run

npm run dev              # http://localhost:3000

Check GET /api/health — it returns database status, scheme/source counts and TinyFish status.

Test and lint

npm test                 # 29 eligibility engine checks (tsx tests/eligibility.test.ts)
npm run lint
npm run typecheck        # tsc --noEmit

Build

npm run build            # prisma generate && next build
npm start                # serves on port 3000

Deployment

SchemeAI is set up for Vercel with a Neon Postgres database (vercel.json pins the bom1 / Mumbai region). Follow the step-by-step guide in DEPLOY-VERCEL.md.

Documentation

Document	Contents
docs/ARCHITECTURE.md	System components, data model, design decisions
docs/FLOWS.md	User and data flows (matching, verification, assistant)
docs/API.md	REST endpoint reference
docs/TINYFISH.md	TinyFish integration, configuration and status model
DEPLOY-VERCEL.md	Hosting on Vercel + Neon

Data and trust model

• Scheme records are compiled from official guidelines and stored as REFERENCE with a compilation date. A record becomes LIVE_CHECKED only after a successful real check of its official source or a successful TinyFish refresh of its official page.
• Direct checks verify that the official domain is reachable and record its page title. Content is re-extracted only by TinyFish runs; those results are stored as separate LIVE_FETCH evidence with the run ID and never overwrite the curated reference fields.
• Source access is limited to read-only public pages. Login, CAPTCHA, OTP and Aadhaar flows are never automated.
• The assistant answers only from retrieved records and labels its mode; final eligibility is always decided by the official authority.

Registered sources include the National Scholarship Portal, National Portal of India, PM-Kisan, Ministry of Social Justice and Empowerment, DST, AICTE, PMAY-G/U, PM-JAY, Jan Suraksha (PMSBY/PMJJBY), NSAP, MUDRA, Stand-Up India, PMKVY, eSHRAM, PM Vishwakarma, PM Surya Ghar, PMFBY, PMSYM, and the UP and MP women & child development portals.

Known limitations

• Scheme data is a curated reference compilation; always confirm details on the official portal before applying.
• Coverage is 33 schemes — central schemes plus selected UP and MP schemes.
• TinyFish extraction requires an API key, takes roughly 15–90 s per run, and some portals return a CAPTCHA or access-denied page (recorded as BLOCKED, nothing stored).
• The assistant's LLM mode is tied to z-ai-web-dev-sdk; there is no provider setting in this repo.
• The seed creates a demo admin (admin@schemeai.in / Admin@1234), and the sign-in page has a button that fills it in. Change the password, or remove that account, on any public deployment.
• next.config.ts sets typescript.ignoreBuildErrors: true; run npm run typecheck before deploying.
• There is no rate limiting on any endpoint. Scheme refreshes are open to everyone; TinyFish cost is bounded only by the 6-hour cache of successful runs.
• Hindi support covers the interface and scheme summaries; official scheme names remain as published.

Roadmap

• Scheduled refresh of stale schemes with TinyFish, plus alerts when an extracted deadline differs from the reference record.
• Admin cooldowns and budget caps for TinyFish runs.
• Broader state coverage and imports from official open-data sources.
• Deadline reminders with real notification delivery.
• Additional Indian languages on top of the existing i18n dictionary.
• Rate limiting for the live verification endpoints.

License

No license file is currently included in this repository. All rights are reserved by the author until a license is added.