Jan Saathi (जन साथी)

Voice-first, Hindi-first AI companion that helps citizens discover and apply for government schemes in simple language.

This repository contains the current production direction of Jan Saathi:

• Next.js App Router frontend with PWA support in nextjs-app/
• FastAPI backend in backend/
• Data ingestion and enrichment pipeline in pipeline/
• Legacy Vite frontend in frontend/ (kept for reference; active UI is nextjs-app/)

Team

• Team Name: ALGOMIND
• Team Lead: PRACHI AGARWALLA
• Developer: ANIRUDDH VIJAYVARGIA

Hackathon context: Build4Bharat 9.0 (CSIHACK05), focused on improving access to government services.

Overview

Jan Saathi is built for citizens who face language, literacy, and form-filling barriers when accessing welfare schemes.

Core experience:

• Audio-first entry with Shubh avatar
• Voice capture and transcription with Sarvam Saaras v3
• Automatic language adaptation for conversation
• Scheme matching with multilingual embeddings + vector search
• Plain-language spoken guidance for next steps
• Session memory for return conversations

Key target beneficiaries include farmers, daily wage workers, pregnant women, students, and senior citizens.

Current Product Direction

• Active frontend: Next.js + PWA (nextjs-app/)
• Backend API: FastAPI (backend/)
• Database and vector retrieval: Supabase PostgreSQL + pgvector
• AI orchestration: Groq (LLM fallback chain), Cohere (embeddings), Sarvam (STT/TTS)

Important: the old React+Vite app in frontend/ is not the primary application path now.

Repository Structure

.
|- nextjs-app/        # Active web app (Next.js 16 + PWA)
|- backend/           # FastAPI API services and business logic
|- pipeline/          # Data extraction, translation, embedding, ingest scripts
|- frontend/          # Legacy Vite frontend (reference)
|- scripts/           # Verification/util scripts

Tech Stack

Frontend (active)

• Next.js 16 (App Router), React 19, TypeScript
• Tailwind CSS v4
• PWA: @ducanh2912/next-pwa + Web App Manifest
• UI: Radix primitives and custom components
• State/context for session, language, and chat flow

Backend

• FastAPI + Uvicorn
• httpx async clients for external APIs
• python-jose for JWT auth
• slowapi rate limiting
• ReportLab/PDF tooling for form output flows

AI and Voice

• STT: Sarvam Saaras v3
• TTS: Sarvam Bulbul v3 (Shubh voice)
• LLM: Groq with configured fallback model chain
• Embeddings: Cohere multilingual embedding model

Data

• Supabase PostgreSQL
• pgvector similarity search (via RPC search functions)

Testing

• Frontend unit tests: Vitest + Testing Library
• Frontend E2E: Playwright
• Backend tests: Pytest

Setup

1. Prerequisites

• Node.js 20+
• npm 10+
• Python 3.11+ (3.12 recommended for backend runtime parity)

2. Backend Setup (backend/)

cd backend
python -m venv .venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env

Populate .env with your real credentials:

• Supabase (SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, etc.)
• Groq (GROQ_API_KEY)
• Cohere (COHERE_API_KEY)
• Sarvam (SARVAM_API_KEY)
• Google OAuth (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET)
• JWT and app config values

Run backend:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

Health check:

curl http://localhost:8000/health

3. Frontend Setup (nextjs-app/)

cd nextjs-app
npm install

Create .env.local and set at least:

• NEXT_PUBLIC_API_URL
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_URL
• SUPABASE_SERVICE_ROLE_KEY
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• ADMIN_EMAIL
• NEXT_PUBLIC_ADMIN_EMAIL

Run frontend:

npm run dev

Open:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000

4. Pipeline Setup (pipeline/)

cd pipeline
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Pipeline scripts support extraction, enrichment, translation context patching, embedding ingest, and verification.

Running Tests

Backend

cd backend
pytest -q

Frontend Unit Tests

cd nextjs-app
npm run test:unit

Frontend E2E

cd nextjs-app
npm run test:e2e

APISetu and Government API Integration Status

Jan Saathi is architected for department-level government API connectivity through APISetu.

Current status:

• API contracts/endpoints are considered in system design.
• Organization registration and approval are required before live APISetu connectivity.
• Endpoints exist in architecture, but no production APISetu connection is active yet.

Planned scope after approval:

• Cross-department scheme and service data fetch through APISetu APIs
• Real-time eligibility/status checks where available
• Stronger document and identity verification workflows

Aadhaar/UUID Note (Government Approval Dependent)

Planned architecture includes Aadhaar-based user authentication/eKYC flow and UUID-linked identity continuity, subject to required government approvals and compliant API availability.

Until approval and access are granted, Jan Saathi uses its existing authenticated/anonymous session model and does not claim live Aadhaar integration.

Deployment Notes

• Backend is configured for Railway deployment (backend/railway.json, backend/Procfile)
• Next.js app is deployable on Vercel
• PWA manifest and service worker behavior are configured in nextjs-app/public/manifest.json and nextjs-app/next.config.ts

Important Implementation Notes

• Voice and language handling is central to the product UX.
• Plain-language guidance is enforced in LLM prompting so responses remain citizen-friendly.
• Form autofill and full government portal integration are being implemented incrementally.

Credits and Ownership

Built by Team ALGOMIND for public service accessibility.

If you are onboarding to this repository, start with:

1. README.md (this file)
2. nextjs-app/README.md
3. backend/.env.example